From e76632c912efc9dabda5a0f198413a74c2f3c0b5 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones"
The remote support means the capacity to connect to hosts which are -not on the machine where the program using libvirt is running. But there -is ongoing work to add that support.
+ ++NB. Remote support is available only as a series of +patches posted on libvir-list against libvirt CVS. It is only +for experimental use at the moment. +— Richard Jones, 2007-04-18. +
+ ++Libvirt allows you to access hypervisors running on remote +machines through authenticated and encrypted connections. +
+ +
+On the remote machine, libvirtd
should be running.
+See the section
+on configuring libvirtd for more information.
+
+To tell libvirt that you want to access a remote resource,
+you should supply a hostname in the normal URI that is passed
+to virConnectOpen
(or virsh -c ...
).
+For example, if you normally use qemu:///system
+to access the system-wide QEMU daemon, then to access
+the system-wide QEMU daemon on a remote machine called
+oirase
you would use qemu://oirase/system
.
+
+The section on remote URIs +describes in more detail these remote URIs. +
+ ++From an API point of view, apart from the change in URI, the +API should behave the same. For example, ordinary calls +are routed over the remote connection transparently, and +values or errors from the remote side are returned to you +as if they happened locally. Some differences you may notice: +
+ ++Remote libvirt supports a range of transports: +
+ +/var/run/libvirt/libvirt-sock
and
+ /var/run/libvirt/libvirt-sock-ro
(the latter
+ for read-only connections).
+
+The default transport, if no other is specified, is tls
.
+
+Remote URIs have the general form ("[...]" meaning an optional part): +
+ +
+driver
[+transport
]://
[username@
]hostname
[:port
]/
[path
][?extraparameters
]
+
+Either the transport or the hostname must be given in order +to distinguish this from a local URI. +
+ ++Some examples: +
+ +xen+ssh://rjones@towada/
towada
using ssh transport and ssh
+username rjones
.
+xen://towada/
towada
using TLS.
+xen://towada/?no_verify=1
towada
using TLS. Do not verify
+the server's certificate.
+qemu+unix:///system?socket=/opt/libvirt/run/libvirt/libvirt-sock
test+tcp://localhost:5000/default
+Extra parameters can be added to remote URIs as part
+of the query string (the part following
).
+Remote URIs understand the extra parameters shown below.
+Any others are passed unmodified through to the back end.
+Note that parameter values must be
+URI-escaped.
+?
Name | +Transports | +Meaning | +
---|---|---|
name |
+any transport | ++ The name passed to the remote virConnectOpen function. The + name is normally formed by removing transport, hostname, port + number, username and extra parameters from the remote URI, but in certain + very complex cases it may be better to supply the name explicitly. + | +
+ | Example: name=qemu:///system |
+|
command |
+ssh, ext | +
+ The external command. For ext transport this is required.
+ For ssh the default is ssh .
+ The PATH is searched for the command.
+ |
+
+ | Example: command=/opt/openssh/bin/ssh |
+|
socket |
+unix, ssh | ++ The path to the Unix domain socket, which overrides the + compiled-in default. For ssh transport, this is passed to + the remote netcat command (see next). + | +
+ | Example: socket=/opt/libvirt/run/libvirt/libvirt-sock |
+|
netcat |
+ssh | +
+ The name of the netcat command on the remote machine.
+ The default is nc . For ssh transport, libvirt
+ constructs an ssh command which looks like:
+
++command -p port [-l username] hostname netcat -U socket ++ + where port, username, hostname can be + specified as part of the remote URI, and command, netcat + and socket come from extra parameters (or + sensible defaults). + + |
+
+ | Example: netcat=/opt/netcat/bin/nc |
+|
no_verify |
+tls | ++ If set to a non-zero value, this disables client checks of the + server's certificate. Note that to disable server checks of + the client's certificate or IP address you must + change the libvirtd + configuration. + | +
+ | Example: no_verify=1 |
+
+This section to follow. +
+ + + + + + ++This section to follow. +
+ + + + + + ++IPv6 has received some limited testing and should work. Problems with +libvirt and IPv6 should be reported as bugs. +
+ ++Please come and discuss these issues and more on the mailing list. +
+ ++The current implementation uses XDR-encoded packets with a +simple remote procedure call implementation which also supports +asynchronous messaging and asynchronous and out-of-order replies, +although these latter features are not used at the moment. +
+ ++The implementation should be considered strictly internal to +libvirt and subject to change at any time without notice. If +you wish to talk to libvirtd, link to libvirt. If there is a problem +that means you think you need to use the protocol directly, please +first discuss this on the mailing list. +
+ +
+The messaging protocol is described in
+qemud/remote_protocol.x
.
+
+Authentication and encryption (for TLS) is done using GnuTLS and the RPC protocol is unaware of this layer. +
+ +
+Protocol messages are sent using a simple 32 bit length word (encoded
+XDR int) followed by the message header (XDR
+remote_message_header
) followed by the message body. The
+length count includes the length word itself, and is measured in
+bytes. Maximum message size is REMOTE_MESSAGE_MAX
and to
+avoid denial of services attacks on the XDR decoders strings are
+individually limited to REMOTE_STRING_MAX
bytes. In the
+TLS case, messages may be split over TLS records, but a TLS record
+cannot contain parts of more than one message. In the common RPC case
+a single REMOTE_CALL
message is sent from client to
+server, and the server then replies synchronously with a single
+REMOTE_REPLY
message, but other forms of messaging are
+also possible.
+
+The protocol contains support for multiple program types and protocol +versioning, modelled after SunRPC. +