/ 
Protocol-Sys-Virt-v10.9.13
River stage one • 1 direct dependent • 1 total dependent
/ Protocol::Sys::Virt::Remote

NAME

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

VERSION

v10.9.13

Based on LibVirt tag v10.9.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);
$on_stream->(header => $hdr, final => $final);

Passthrough from the on_stream event in Protocol::Sys::Virt::Transport, with the exception of the final argument which indicates a positive confirmation of the end of the stream. This message comes after the last data message (which sends zero-length data); both ends send this message which serves as a synchronization point for the stream communication.

Please note that if an error occurs, no final message is sent.

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

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

Sends data or a stream hole to the server, relating to the stream opened with remote procedure $proc through serial $serial.

Note that errors terminate the stream and should be transmitted using stream_end.

stream_end

$remote->stream_end( $proc, $serial );         # regular stream termination
$remote->stream_end( $proc, $serial, 1 );      # abort, on client
$remote->stream_end( $proc, $serial, $error ); # abort, on server

Closes the stream, either through regular confirmation or through an error condition. The client does not send its error to the server, but the server sends its error information to the client -- which explains the difference in invocation between clients and servers. The role attribute should be set to server for servers to handle error conditions in streams correctly.

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.