NAME

Protocol::Sys::Virt::Remote - Connect to remote libvirt daemon

VERSION

v10.3.7

Based on LibVirt tag v10.3.0

SYNOPSIS

  use Protocol::Sys::Virt::Transport;
  use Protocol::Sys::Virt::Remote;
  use Protocol::Sys::Virt::Remote::XDR;
  my $prot = 'Protocol::Sys::Virt::Remote::XDR';

  open my $fh, 'rw', '/run/libvirt/libvirt.sock';
  my $transport = Protocol::Sys::Virt::Transport->new(
       role => 'client',
       on_send => sub { my $opaque = shift; syswrite( $fh, $_ ) for @_; $opaque }
  );

  my $remote = Protocol::Sys::Virt::Remote->new(
       role => 'client',
       on_reply => sub { say 'Reply handled!'; },
  );
  $remote->register( $transport );

  $remote->start_auth( $prot->AUTH_NONE,
                       on_complete => sub { say "Authenticated!" });

  my $serial = $remote->call( $prot->PROC_CONNECT_OPEN,
                 { name => 'qemu:///system', flags => 0 } );

DESCRIPTION

This module contains a class to connect to a "remote" libvirt daemon. That is, a deamon connected to a stream, which may be a Unix socket, a TCP socket, a pipe, etc. The data sent and received is encoded and decoded before passing it on to the transport or back to the caller.

EVENTS

on_closed

Called when the remote side of the stream announces it will close the stream using the REMOTE_PROC_CONNECT_CLOSE message, or when it confirms such a message as initiated locally.

on_call

  $on_call->(header => $hdr, data => $decoded_data, [fds => $fds]);

Called when receiving a VIR_NET_CALL or VIR_NET_CALL_WITH_FDS (abbreviated as CALL or CALL_WITH_FDS) message. This callback differs from the one in Protocol::Sys::Virt::Transport by the fact the data has been decoded from XDR to the Perl representation.

on_reply

  $on_reply->(header => $hdr, data  => $decoded_data, [fds => $fds]);
  $on_reply->(header => $hdr, error => $err);

Called when receiving a VIR_NET_REPLY or VIR_NET_REPLY_WITH_FDS (abbreviated as REPLY or REPLY_WITH_FDS) message. This callback differs from the one in Protocol::Sys::Virt::Transport by the fact the data has been decoded from XDR to the Perl representation.

on_message

  $on_message->(header => $hdr, data  => $data);

Called when receiving a VIR_NET_MESSAGE (abbreviated as MESSAGE) message. This callback differs from the one in Protocol::Sys::Virt::Transport by the fact the data has been decoded from XDR to the Perl representation.

on_stream

  $on_stream->(header => $hdr, data => $data);
  $on_stream->(header => $hdr, hole => $hole);
  $on_stream->(header => $hdr, error => $err);

Passthrough from the on_stream event in Protocol::Sys::Virt::Transport.

CONSTRUCTOR

new

   my $remote = Protocol::Sys::Virt::Remote->new(
       role     => 'client',
       on_close => sub { ... },
       on_call  => sub { ... },
   );

Creates an instance on the client side (role => 'client') or server side (role => 'server') of the connection. In addition to the required role parameter, the constructor may be provided with a coderef for each of the events.

METHODS

configure

  $remote->configure( on_reply => $callback, ... );

Sets callback handlers for events.

register

  $remote->register( $transport );

Sets the callbacks on $transport for $remote->PROGRAM, allowing this instance to handle any incoming transfers.

start_auth

  $remote->start_auth( $wanted_auth_type,
                       sasl => $sasl,
                       on_complete => sub { ... } );

Starts a sequence of message exchanges to authenticate with the remote. The messages being exchanged are handled internally and not passed to the event handlers. When AUTH_SASL is wanted, the sasl key should be provided with an instance of Authen::SASL. The on_complete handler is defined as:

  $on_complete->(status => $status);

Where $status can be success or fail.

call

  $serial = $remote->call( $proc, $data );

Calls the remote procedure $proc with the arguments given in $data. $proc is one of the values in the enum procedure as defined in Protocol::Sys::Virt::Remote::XDR. Reply and stream messages in response to this call are identified by $serial.

Note: If the on_send callback of the associated transport is declared async (as in Future::AsyncAwait), a Future is returned which (eventually) resolves to the $serial.

reply

  $remote->reply( $proc, $serial, $status, $data );

Sends a reply to a remote call $proc using $serial. If $status is ERROR, $data is expected to provide an error (remote_error) structure.

Note: If the on_send callback of the associated transport is declared async (as in Future::AsyncAwait), a Future is returned which resolves when the reply has been sent.

message

  $remote->message( $proc, $data );

Sends a notification message $data to the remote procedure $proc.

Note: If the on_send callback of the associated transport is declared async (as in Future::AsyncAwait), a Future is returned which resolves when the message has been sent.

stream

  # TODO

CONSTANTS

DRV_FEATURE_MIGRATION_V1

DRV_FEATURE_REMOTE

DRV_FEATURE_MIGRATION_V2

DRV_FEATURE_MIGRATION_P2P

DRV_FEATURE_MIGRATION_DIRECT

DRV_FEATURE_MIGRATION_V3

DRV_FEATURE_MIGRATE_CHANGE_PROTECTION

DRV_FEATURE_FD_PASSING

DRV_FEATURE_TYPED_PARAM_STRING

DRV_FEATURE_PROGRAM_KEEPALIVE

DRV_FEATURE_XML_MIGRATABLE

DRV_FEATURE_MIGRATION_OFFLINE

DRV_FEATURE_MIGRATION_PARAMS

DRV_FEATURE_REMOTE_EVENT_CALLBACK

DRV_FEATURE_REMOTE_CLOSE_CALLBACK

DRV_FEATURE_NETWORK_UPDATE_HAS_CORRECT_ORDER

LICENSE AND COPYRIGHT

See the LICENSE file in this distribution.

cpanm Protocol::Sys::Virt

perl -MCPAN -e shell
install Protocol::Sys::Virt