mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-16 22:57:15 +00:00
Wed Apr 18 16:16:00 BST 2007 Richard W.M. Jones <rjones@redhat.com>
* docs/libvir.html: Documentation for the remote patch.
This commit is contained in:
Richard W.M. Jones
parent
dbcc662ea3
commit
e76632c912
@ -1,3 +1,7 @@
|
||||
Wed Apr 18 16:16:00 BST 2007 Richard W.M. Jones <rjones@redhat.com>
|
||||
|
||||
* docs/libvir.html: Documentation for the remote patch.
|
||||
|
||||
Wed Apr 18 11:12:00 BST 2007 Richard W.M. Jones <rjones@redhat.com>
|
||||
|
||||
* src/test.c, src/libvirt.c, src/virterror.c,
|
||||
|
||||
370
docs/libvir.html
370
docs/libvir.html
@ -1339,9 +1339,373 @@ to post to the <a href="mailto:libvir-list@redhat.com">mailing-list</a>
|
||||
too if the issue looks serious, thanks !</p>
|
||||
|
||||
<h2><a name="Remote">Remote support</a></h2>
|
||||
<p> 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. </p>
|
||||
|
||||
<p>
|
||||
<b>NB. Remote support is available only as a <a
|
||||
href="https://www.redhat.com/archives/libvir-list/">series of
|
||||
patches posted on libvir-list</a> against <a
|
||||
href="http://libvirt.org/downloads.html">libvirt CVS</a>. It is only
|
||||
for experimental use at the moment.</b>
|
||||
— Richard Jones, 2007-04-18.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Libvirt allows you to access hypervisors running on remote
|
||||
machines through authenticated and encrypted connections.
|
||||
</p>
|
||||
|
||||
<h3><a name="Remote_basic_usage">Basic usage</a></h3>
|
||||
|
||||
<p>
|
||||
On the remote machine, <code>libvirtd</code> should be running.
|
||||
See <a href="#Remote_libvirtd_configuration">the section
|
||||
on configuring libvirtd</a> for more information.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To tell libvirt that you want to access a remote resource,
|
||||
you should supply a hostname in the normal URI that is passed
|
||||
to <code>virConnectOpen</code> (or <code>virsh -c ...</code>).
|
||||
For example, if you normally use <code>qemu:///system</code>
|
||||
to access the system-wide QEMU daemon, then to access
|
||||
the system-wide QEMU daemon on a remote machine called
|
||||
<code>oirase</code> you would use <code>qemu://oirase/system</code>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The <a href="#Remote_URI_reference">section on remote URIs</a>
|
||||
describes in more detail these remote URIs.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li> Additional errors can be generated, specifically ones
|
||||
relating to failures in the remote transport itself. </li>
|
||||
<li> Remote calls are handled synchronously, so they will be
|
||||
much slower than, say, direct hypervisor calls. </li>
|
||||
</ul>
|
||||
|
||||
<h3><a name="Remote_transports">Transports</a></h3>
|
||||
|
||||
<p>
|
||||
Remote libvirt supports a range of transports:
|
||||
</p>
|
||||
|
||||
<dl>
|
||||
<dt> tls </dt>
|
||||
<dd> <a href="http://en.wikipedia.org/wiki/Transport_Layer_Security"
|
||||
title="Transport Layer Security">TLS</a>
|
||||
1.0 (SSL 3.1) authenticated and encrypted TCP/IP socket, usually
|
||||
listening on a public port number. To use this you will need to
|
||||
<a href="#Remote_certificates"
|
||||
title="Generating TLS certificates">generate client and
|
||||
server certificates</a>.
|
||||
The standard port is 16514.
|
||||
</dd>
|
||||
|
||||
<dt> unix </dt>
|
||||
<dd> Unix domain socket. Since this is only accessible on the
|
||||
local machine, it is not encrypted, and uses Unix permissions or
|
||||
SELinux for authentication.
|
||||
The standard socket names are
|
||||
<code>/var/run/libvirt/libvirt-sock</code> and
|
||||
<code>/var/run/libvirt/libvirt-sock-ro</code> (the latter
|
||||
for read-only connections).
|
||||
</dd>
|
||||
|
||||
<dt> ssh </dt>
|
||||
<dd> Transported over an ordinary
|
||||
<a href="http://www.openssh.com/" title="OpenSSH homepage">ssh
|
||||
(secure shell)</a> connection.
|
||||
Requires <a href="http://netcat.sourceforge.net/">Netcat (nc)</a>
|
||||
installed on the remote machine, and the remote libvirtd should
|
||||
be listening on the unix transport. You should use some sort of
|
||||
ssh key management (eg.
|
||||
<a href="http://mah.everybody.org/docs/ssh"
|
||||
title="Using ssh-agent with ssh">ssh-agent</a>)
|
||||
otherwise programs which use
|
||||
this transport will stop to ask for a password. </dd>
|
||||
|
||||
<dt> ext </dt>
|
||||
<dd> Any external program which can make a connection to the
|
||||
remote machine by means outside the scope of libvirt. </dd>
|
||||
|
||||
<dt> tcp </dt>
|
||||
<dd> Unencrypted TCP/IP socket. Not recommended for production
|
||||
use, this is normally disabled, but an administrator can enable
|
||||
it for testing or use over a trusted network.
|
||||
The standard port is 16509.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<p>
|
||||
The default transport, if no other is specified, is <code>tls</code>.
|
||||
</p>
|
||||
|
||||
<h3><a name="Remote_URI_reference">Remote URIs</a></h3>
|
||||
|
||||
<p>
|
||||
Remote URIs have the general form ("[...]" meaning an optional part):
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<code>driver</code>[<code>+transport</code>]<code>://</code>[<code>username@</code>]<code>hostname</code>[<code>:port</code>]<code>/</code>[<code>path</code>][<code>?extraparameters</code>]
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Either the transport or the hostname must be given in order
|
||||
to distinguish this from a local URI.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Some examples:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li> <code>xen+ssh://rjones@towada/</code> <br/> — Connect to a
|
||||
remote Xen hypervisor on host <code>towada</code> using ssh transport and ssh
|
||||
username <code>rjones</code>.
|
||||
</li>
|
||||
|
||||
<li> <code>xen://towada/</code> <br/> — Connect to a
|
||||
remote Xen hypervisor on host <code>towada</code> using TLS.
|
||||
</li>
|
||||
|
||||
<li> <code>xen://towada/?no_verify=1</code> <br/> — Connect to a
|
||||
remote Xen hypervisor on host <code>towada</code> using TLS. Do not verify
|
||||
the server's certificate.
|
||||
</li>
|
||||
|
||||
<li> <code>qemu+unix:///system?socket=/opt/libvirt/run/libvirt/libvirt-sock</code> <br/> —
|
||||
Connect to the local qemu instances over a non-standard
|
||||
Unix socket (the full path to the Unix socket is
|
||||
supplied explicitly in this case).
|
||||
</li>
|
||||
|
||||
<li> <code>test+tcp://localhost:5000/default</code> <br/> —
|
||||
Connect to a libvirtd daemon offering unencrypted TCP/IP connections
|
||||
on localhost port 5000 and use the test driver with default
|
||||
settings.
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
<h4><a name="Remote_URI_parameters">Extra parameters</a></h4>
|
||||
|
||||
<p>
|
||||
Extra parameters can be added to remote URIs as part
|
||||
of the query string (the part following <q><code>?</code></q>).
|
||||
Remote URIs understand the extra parameters shown below.
|
||||
Any others are passed unmodified through to the back end.
|
||||
Note that parameter values must be
|
||||
<a href="http://xmlsoft.org/html/libxml-uri.html#xmlURIEscapeStr">URI-escaped</a>.
|
||||
</p>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th> Name </th>
|
||||
<th> Transports </th>
|
||||
<th> Meaning </th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td> <code>name</code> </td>
|
||||
<td> <i>any transport</i> </td>
|
||||
<td>
|
||||
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.
|
||||
</td>
|
||||
</tr>
|
||||
<tr> <td colspan="2"></td>
|
||||
<td> Example: <code>name=qemu:///system</code> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td> <code>command</code> </td>
|
||||
<td> ssh, ext </td>
|
||||
<td>
|
||||
The external command. For ext transport this is required.
|
||||
For ssh the default is <code>ssh</code>.
|
||||
The PATH is searched for the command.
|
||||
</td>
|
||||
</tr>
|
||||
<tr> <td colspan="2"></td>
|
||||
<td> Example: <code>command=/opt/openssh/bin/ssh</code> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td> <code>socket</code> </td>
|
||||
<td> unix, ssh </td>
|
||||
<td>
|
||||
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).
|
||||
</td>
|
||||
</tr>
|
||||
<tr> <td colspan="2"></td>
|
||||
<td> Example: <code>socket=/opt/libvirt/run/libvirt/libvirt-sock</code> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td> <code>netcat</code> </td>
|
||||
<td> ssh </td>
|
||||
<td>
|
||||
The name of the netcat command on the remote machine.
|
||||
The default is <code>nc</code>. For ssh transport, libvirt
|
||||
constructs an ssh command which looks like:
|
||||
|
||||
<pre>
|
||||
<i>command</i> -p <i>port</i> [-l <i>username</i>] <i>hostname</i> <i>netcat</i> -U <i>socket</i>
|
||||
</pre>
|
||||
|
||||
where <i>port</i>, <i>username</i>, <i>hostname</i> can be
|
||||
specified as part of the remote URI, and <i>command</i>, <i>netcat</i>
|
||||
and <i>socket</i> come from extra parameters (or
|
||||
sensible defaults).
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr> <td colspan="2"></td>
|
||||
<td> Example: <code>netcat=/opt/netcat/bin/nc</code> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td> <code>no_verify</code> </td>
|
||||
<td> tls </td>
|
||||
<td>
|
||||
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
|
||||
<a href="#Remote_libvirtd_configuration">change the libvirtd
|
||||
configuration</a>.
|
||||
</td>
|
||||
</tr>
|
||||
<tr> <td colspan="2"></td>
|
||||
<td> Example: <code>no_verify=1</code> </td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
<h3><a name="Remote_certificates">Generating TLS certificates</a></h3>
|
||||
|
||||
<p>
|
||||
<i>This section to follow.</i>
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<h3><a name="Remote_libvirtd_configuration">libvirtd configuration</a></h3>
|
||||
|
||||
<p>
|
||||
<i>This section to follow.</i>
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<h3><a name="Remote_IPv6">IPv6 support</a></h3>
|
||||
|
||||
<p>
|
||||
IPv6 has received some limited testing and should work. Problems with
|
||||
libvirt and IPv6 should be reported as <a href="bugs.html">bugs</a>.
|
||||
</p>
|
||||
|
||||
<h3><a name="Remote_limitations">Limitations</a></h3>
|
||||
|
||||
<ul>
|
||||
<li> Remote storage: To be fully useful, particularly for
|
||||
creating new domains, it should be possible to enumerate
|
||||
and provision storage on the remote machine. This is currently
|
||||
in the design phase. </li>
|
||||
|
||||
<li> Migration: We expect libvirt will support migration,
|
||||
and obviously remote support is what makes migration worthwhile.
|
||||
This is also in the design phase. Issues <a
|
||||
href="https://www.redhat.com/mailman/listinfo/libvir-list"
|
||||
title="libvir-list mailing list">to discuss</a> include
|
||||
which path the migration data should follow (eg. client to
|
||||
client direct, or client to server to client) and security.
|
||||
</li>
|
||||
|
||||
<li> Fine-grained authentication: libvirt in general,
|
||||
but in particular the remote case should support more
|
||||
fine-grained authentication for operations, rather than
|
||||
just read-write/read-only as at present.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Please come and discuss these issues and more on <a
|
||||
href="https://www.redhat.com/mailman/listinfo/libvir-list"
|
||||
title="libvir-list mailing list">the mailing list</a>.
|
||||
</p>
|
||||
|
||||
<h3><a name="Remote_implementation_notes">Implementation notes</a></h3>
|
||||
|
||||
<p>
|
||||
The current implementation uses <a
|
||||
href="http://en.wikipedia.org/wiki/External_Data_Representation"
|
||||
title="External Data Representation">XDR</a>-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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The implementation should be considered <b>strictly internal</b> to
|
||||
libvirt and <b>subject to change at any time without notice</b>. 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 <a
|
||||
href="https://www.redhat.com/mailman/listinfo/libvir-list"
|
||||
title="libvir-list mailing list">the mailing list</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The messaging protocol is described in
|
||||
<code>qemud/remote_protocol.x</code>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Authentication and encryption (for TLS) is done using <a
|
||||
href="http://www.gnu.org/software/gnutls/" title="GnuTLS project
|
||||
page">GnuTLS</a> and the RPC protocol is unaware of this layer.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Protocol messages are sent using a simple 32 bit length word (encoded
|
||||
XDR int) followed by the message header (XDR
|
||||
<code>remote_message_header</code>) followed by the message body. The
|
||||
length count includes the length word itself, and is measured in
|
||||
bytes. Maximum message size is <code>REMOTE_MESSAGE_MAX</code> and to
|
||||
avoid denial of services attacks on the XDR decoders strings are
|
||||
individually limited to <code>REMOTE_STRING_MAX</code> 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 <code>REMOTE_CALL</code> message is sent from client to
|
||||
server, and the server then replies synchronously with a single
|
||||
<code>REMOTE_REPLY</code> message, but other forms of messaging are
|
||||
also possible.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The protocol contains support for multiple program types and protocol
|
||||
versioning, modelled after SunRPC.
|
||||
</p>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
244
docs/remote.html
244
docs/remote.html
@ -1,5 +1,243 @@
|
||||
<?xml version="1.0" encoding="ISO-8859-1"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="libvirt.css" /><link rel="SHORTCUT ICON" href="/32favicon.png" /><title>Remote support</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">Remote support</h1><p> 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. </p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="remote.html">Remote support</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="https://bugzilla.redhat.com/bugzilla/buglist.cgi?product=Fedora+Core&component=libvirt&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED&short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr">Open bugs</a></li><li><a href="http://virt-manager.et.redhat.com/">virt-manager</a></li><li><a href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">Perl bindings</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="libvirt.css" /><link rel="SHORTCUT ICON" href="/32favicon.png" /><title>Remote support</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">Remote support</h1><p>
|
||||
<b>NB. Remote support is available only as a <a href="https://www.redhat.com/archives/libvir-list/">series of
|
||||
patches posted on libvir-list</a> against <a href="http://libvirt.org/downloads.html">libvirt CVS</a>. It is only
|
||||
for experimental use at the moment.</b>
|
||||
— Richard Jones, 2007-04-18.
|
||||
</p><p>
|
||||
Libvirt allows you to access hypervisors running on remote
|
||||
machines through authenticated and encrypted connections.
|
||||
</p><h3><a name="Remote_basic_usage" id="Remote_basic_usage">Basic usage</a></h3><p>
|
||||
On the remote machine, <code>libvirtd</code> should be running.
|
||||
See <a href="#Remote_libvirtd_configuration">the section
|
||||
on configuring libvirtd</a> for more information.
|
||||
</p><p>
|
||||
To tell libvirt that you want to access a remote resource,
|
||||
you should supply a hostname in the normal URI that is passed
|
||||
to <code>virConnectOpen</code> (or <code>virsh -c ...</code>).
|
||||
For example, if you normally use <code>qemu:///system</code>
|
||||
to access the system-wide QEMU daemon, then to access
|
||||
the system-wide QEMU daemon on a remote machine called
|
||||
<code>oirase</code> you would use <code>qemu://oirase/system</code>.
|
||||
</p><p>
|
||||
The <a href="#Remote_URI_reference">section on remote URIs</a>
|
||||
describes in more detail these remote URIs.
|
||||
</p><p>
|
||||
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:
|
||||
</p><ul><li> Additional errors can be generated, specifically ones
|
||||
relating to failures in the remote transport itself. </li>
|
||||
<li> Remote calls are handled synchronously, so they will be
|
||||
much slower than, say, direct hypervisor calls. </li>
|
||||
</ul><h3><a name="Remote_transports" id="Remote_transports">Transports</a></h3><p>
|
||||
Remote libvirt supports a range of transports:
|
||||
</p><dl><dt> tls </dt>
|
||||
<dd> <a href="http://en.wikipedia.org/wiki/Transport_Layer_Security" title="Transport Layer Security">TLS</a>
|
||||
1.0 (SSL 3.1) authenticated and encrypted TCP/IP socket, usually
|
||||
listening on a public port number. To use this you will need to
|
||||
<a href="#Remote_certificates" title="Generating TLS certificates">generate client and
|
||||
server certificates</a>.
|
||||
The standard port is 16514.
|
||||
</dd>
|
||||
|
||||
<dt> unix </dt>
|
||||
<dd> Unix domain socket. Since this is only accessible on the
|
||||
local machine, it is not encrypted, and uses Unix permissions or
|
||||
SELinux for authentication.
|
||||
The standard socket names are
|
||||
<code>/var/run/libvirt/libvirt-sock</code> and
|
||||
<code>/var/run/libvirt/libvirt-sock-ro</code> (the latter
|
||||
for read-only connections).
|
||||
</dd>
|
||||
|
||||
<dt> ssh </dt>
|
||||
<dd> Transported over an ordinary
|
||||
<a href="http://www.openssh.com/" title="OpenSSH homepage">ssh
|
||||
(secure shell)</a> connection.
|
||||
Requires <a href="http://netcat.sourceforge.net/">Netcat (nc)</a>
|
||||
installed on the remote machine, and the remote libvirtd should
|
||||
be listening on the unix transport. You should use some sort of
|
||||
ssh key management (eg.
|
||||
<a href="http://mah.everybody.org/docs/ssh" title="Using ssh-agent with ssh">ssh-agent</a>)
|
||||
otherwise programs which use
|
||||
this transport will stop to ask for a password. </dd>
|
||||
|
||||
<dt> ext </dt>
|
||||
<dd> Any external program which can make a connection to the
|
||||
remote machine by means outside the scope of libvirt. </dd>
|
||||
|
||||
<dt> tcp </dt>
|
||||
<dd> Unencrypted TCP/IP socket. Not recommended for production
|
||||
use, this is normally disabled, but an administrator can enable
|
||||
it for testing or use over a trusted network.
|
||||
The standard port is 16509.
|
||||
</dd>
|
||||
</dl><p>
|
||||
The default transport, if no other is specified, is <code>tls</code>.
|
||||
</p><h3><a name="Remote_URI_reference" id="Remote_URI_reference">Remote URIs</a></h3><p>
|
||||
Remote URIs have the general form ("[...]" meaning an optional part):
|
||||
</p><p>
|
||||
<code>driver</code>[<code>+transport</code>]<code>://</code>[<code>username@</code>]<code>hostname</code>[<code>:port</code>]<code>/</code>[<code>path</code>][<code>?extraparameters</code>]
|
||||
</p><p>
|
||||
Either the transport or the hostname must be given in order
|
||||
to distinguish this from a local URI.
|
||||
</p><p>
|
||||
Some examples:
|
||||
</p><ul><li> <code>xen+ssh://rjones@towada/</code> <br /> — Connect to a
|
||||
remote Xen hypervisor on host <code>towada</code> using ssh transport and ssh
|
||||
username <code>rjones</code>.
|
||||
</li>
|
||||
|
||||
<li> <code>xen://towada/</code> <br /> — Connect to a
|
||||
remote Xen hypervisor on host <code>towada</code> using TLS.
|
||||
</li>
|
||||
|
||||
<li> <code>xen://towada/?no_verify=1</code> <br /> — Connect to a
|
||||
remote Xen hypervisor on host <code>towada</code> using TLS. Do not verify
|
||||
the server's certificate.
|
||||
</li>
|
||||
|
||||
<li> <code>qemu+unix:///system?socket=/opt/libvirt/run/libvirt/libvirt-sock</code> <br /> —
|
||||
Connect to the local qemu instances over a non-standard
|
||||
Unix socket (the full path to the Unix socket is
|
||||
supplied explicitly in this case).
|
||||
</li>
|
||||
|
||||
<li> <code>test+tcp://localhost:5000/default</code> <br /> —
|
||||
Connect to a libvirtd daemon offering unencrypted TCP/IP connections
|
||||
on localhost port 5000 and use the test driver with default
|
||||
settings.
|
||||
</li>
|
||||
|
||||
</ul><h4><a name="Remote_URI_parameters" id="Remote_URI_parameters">Extra parameters</a></h4><p>
|
||||
Extra parameters can be added to remote URIs as part
|
||||
of the query string (the part following <q><code>?</code></q>).
|
||||
Remote URIs understand the extra parameters shown below.
|
||||
Any others are passed unmodified through to the back end.
|
||||
Note that parameter values must be
|
||||
<a href="http://xmlsoft.org/html/libxml-uri.html#xmlURIEscapeStr">URI-escaped</a>.
|
||||
</p><table><tr><th> Name </th>
|
||||
<th> Transports </th>
|
||||
<th> Meaning </th>
|
||||
</tr><tr><td> <code>name</code> </td>
|
||||
<td> <i>any transport</i> </td>
|
||||
<td>
|
||||
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.
|
||||
</td>
|
||||
</tr><tr><td colspan="2"></td>
|
||||
<td> Example: <code>name=qemu:///system</code> </td>
|
||||
</tr><tr><td> <code>command</code> </td>
|
||||
<td> ssh, ext </td>
|
||||
<td>
|
||||
The external command. For ext transport this is required.
|
||||
For ssh the default is <code>ssh</code>.
|
||||
The PATH is searched for the command.
|
||||
</td>
|
||||
</tr><tr><td colspan="2"></td>
|
||||
<td> Example: <code>command=/opt/openssh/bin/ssh</code> </td>
|
||||
</tr><tr><td> <code>socket</code> </td>
|
||||
<td> unix, ssh </td>
|
||||
<td>
|
||||
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).
|
||||
</td>
|
||||
</tr><tr><td colspan="2"></td>
|
||||
<td> Example: <code>socket=/opt/libvirt/run/libvirt/libvirt-sock</code> </td>
|
||||
</tr><tr><td> <code>netcat</code> </td>
|
||||
<td> ssh </td>
|
||||
<td>
|
||||
The name of the netcat command on the remote machine.
|
||||
The default is <code>nc</code>. For ssh transport, libvirt
|
||||
constructs an ssh command which looks like:
|
||||
|
||||
<pre>
|
||||
<i>command</i> -p <i>port</i> [-l <i>username</i>] <i>hostname</i> <i>netcat</i> -U <i>socket</i>
|
||||
</pre>
|
||||
|
||||
where <i>port</i>, <i>username</i>, <i>hostname</i> can be
|
||||
specified as part of the remote URI, and <i>command</i>, <i>netcat</i>
|
||||
and <i>socket</i> come from extra parameters (or
|
||||
sensible defaults).
|
||||
|
||||
</td>
|
||||
</tr><tr><td colspan="2"></td>
|
||||
<td> Example: <code>netcat=/opt/netcat/bin/nc</code> </td>
|
||||
</tr><tr><td> <code>no_verify</code> </td>
|
||||
<td> tls </td>
|
||||
<td>
|
||||
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
|
||||
<a href="#Remote_libvirtd_configuration">change the libvirtd
|
||||
configuration</a>.
|
||||
</td>
|
||||
</tr><tr><td colspan="2"></td>
|
||||
<td> Example: <code>no_verify=1</code> </td>
|
||||
</tr></table><h3><a name="Remote_certificates" id="Remote_certificates">Generating TLS certificates</a></h3><p>
|
||||
<i>This section to follow.</i>
|
||||
</p><h3><a name="Remote_libvirtd_configuration" id="Remote_libvirtd_configuration">libvirtd configuration</a></h3><p>
|
||||
<i>This section to follow.</i>
|
||||
</p><h3><a name="Remote_IPv6" id="Remote_IPv6">IPv6 support</a></h3><p>
|
||||
IPv6 has received some limited testing and should work. Problems with
|
||||
libvirt and IPv6 should be reported as <a href="bugs.html">bugs</a>.
|
||||
</p><h3><a name="Remote_limitations" id="Remote_limitations">Limitations</a></h3><ul><li> Remote storage: To be fully useful, particularly for
|
||||
creating new domains, it should be possible to enumerate
|
||||
and provision storage on the remote machine. This is currently
|
||||
in the design phase. </li>
|
||||
|
||||
<li> Migration: We expect libvirt will support migration,
|
||||
and obviously remote support is what makes migration worthwhile.
|
||||
This is also in the design phase. Issues <a href="https://www.redhat.com/mailman/listinfo/libvir-list" title="libvir-list mailing list">to discuss</a> include
|
||||
which path the migration data should follow (eg. client to
|
||||
client direct, or client to server to client) and security.
|
||||
</li>
|
||||
|
||||
<li> Fine-grained authentication: libvirt in general,
|
||||
but in particular the remote case should support more
|
||||
fine-grained authentication for operations, rather than
|
||||
just read-write/read-only as at present.
|
||||
</li>
|
||||
</ul><p>
|
||||
Please come and discuss these issues and more on <a href="https://www.redhat.com/mailman/listinfo/libvir-list" title="libvir-list mailing list">the mailing list</a>.
|
||||
</p><h3><a name="Remote_implementation_notes" id="Remote_implementation_notes">Implementation notes</a></h3><p>
|
||||
The current implementation uses <a href="http://en.wikipedia.org/wiki/External_Data_Representation" title="External Data Representation">XDR</a>-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.
|
||||
</p><p>
|
||||
The implementation should be considered <b>strictly internal</b> to
|
||||
libvirt and <b>subject to change at any time without notice</b>. 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 <a href="https://www.redhat.com/mailman/listinfo/libvir-list" title="libvir-list mailing list">the mailing list</a>.
|
||||
</p><p>
|
||||
The messaging protocol is described in
|
||||
<code>qemud/remote_protocol.x</code>.
|
||||
</p><p>
|
||||
Authentication and encryption (for TLS) is done using <a href="http://www.gnu.org/software/gnutls/" title="GnuTLS project page">GnuTLS</a> and the RPC protocol is unaware of this layer.
|
||||
</p><p>
|
||||
Protocol messages are sent using a simple 32 bit length word (encoded
|
||||
XDR int) followed by the message header (XDR
|
||||
<code>remote_message_header</code>) followed by the message body. The
|
||||
length count includes the length word itself, and is measured in
|
||||
bytes. Maximum message size is <code>REMOTE_MESSAGE_MAX</code> and to
|
||||
avoid denial of services attacks on the XDR decoders strings are
|
||||
individually limited to <code>REMOTE_STRING_MAX</code> 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 <code>REMOTE_CALL</code> message is sent from client to
|
||||
server, and the server then replies synchronously with a single
|
||||
<code>REMOTE_REPLY</code> message, but other forms of messaging are
|
||||
also possible.
|
||||
</p><p>
|
||||
The protocol contains support for multiple program types and protocol
|
||||
versioning, modelled after SunRPC.
|
||||
</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvirt architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="format.html">XML Format</a></li><li><a href="python.html">Binding for Python</a></li><li><a href="errors.html">Handling of errors</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="remote.html">Remote support</a></li><li><a href="html/index.html">API Menu</a></li><li><a href="examples/index.html">C code examples</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="https://bugzilla.redhat.com/bugzilla/buglist.cgi?product=Fedora+Core&component=libvirt&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED&short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr">Open bugs</a></li><li><a href="http://virt-manager.et.redhat.com/">virt-manager</a></li><li><a href="http://search.cpan.org/~danberr/Sys-Virt-0.1.0/">Perl bindings</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user