shaba/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-28 11:21:44 +03:00
Code Releases Activity
07f347101c
libvirt/docs/remote.html

244 lines
14 KiB
HTML
Raw Normal View History

* docs/remote.html docs/site.html docs/*.html: added a stub for the remote page, added it to stylesheet and regenerated Daniel
2007-04-18 13:58:35 +04:00
<?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">
Wed Apr 18 16:16:00 BST 2007 Richard W.M. Jones <rjones@redhat.com> * docs/libvir.html: Documentation for the remote patch.
2007-04-18 19:14:32 +04:00
<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>
&#8212;<EFBFBD>Richard<EFBFBD>Jones,<2C>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 /> &#8212; 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 /> &#8212; Connect to a
remote Xen hypervisor on host <code>towada</code> using TLS.
</li>
<li> <code>xen://towada/?no_verify=1</code> <br /> &#8212; 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 /> &#8212;
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 /> &#8212;
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<EFBFBD>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&#10;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&amp;component=libvirt&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;bug_status=MODIFIED&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;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>
Copy Permalink