+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1 >Remote support</h1>
- <p>
-Libvirt allows you to access hypervisors running on remote
-machines through authenticated and encrypted connections.
-</p>
- <ul id="toc"></ul>
-
- <h2>
- <a id="Remote_basic_usage">Basic usage</a>
- </h2>
- <p>
-On the remote machine, <code>libvirtd</code> should be running in general.
-See <a href="#Remote_libvirtd_configuration">the section
-on configuring libvirtd</a> for more information.
-</p>
- <p>
- Not all hypervisors supported by libvirt require a running
- <code>libvirtd</code>. If you want to connect to a VMware ESX/ESXi or
- GSX server then <code>libvirtd</code> is not necessary. See the
- <a href="drvesx.html">VMware ESX page</a> for details.
- </p>
- <p>
-To tell libvirt that you want to access a remote resource,
-you should supply a hostname in the normal <a href="uri.html">URI</a> 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>compute1.libvirt.org</code> you would use
-<code>qemu://compute1.libvirt.org/system</code>.
-</p>
- <p>
-The <a href="uri.html#URI_remote">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>
- <h2>
- <a id="Remote_transports">Transports</a>
- </h2>
- <p>
-Remote libvirt supports a range of transports:
-</p>
- <dl>
- <dt><code>tls</code></dt>
- <dd><a href="https://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="kbase/tlscerts.html" title="Generating TLS certificates">generate client and
- server certificates</a>.
- The standard port is 16514.
- </dd>
- <dt><code>unix</code></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><code>ssh</code></dt>
- <dd> Transported over an ordinary
- <a href="https://www.openssh.com/" title="OpenSSH homepage">ssh
- (secure shell)</a> connection.
- Requires <a href="http://netcat.sourceforge.net/">Netcat (nc)</a>
- installed and libvirtd should be running
- on the remote machine. 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><code>ext</code></dt>
- <dd> Any external program which can make a connection to the
- remote machine by means outside the scope of libvirt. </dd>
- <dt><code>tcp</code></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>
- <dt><code>libssh2</code></dt>
- <dd> Transport over the SSH protocol using
- <a href="https://libssh2.org/" title="libssh2 homepage">libssh2</a> instead
-of the OpenSSH binary. This transport uses the libvirt authentication callback for
-all ssh authentication calls and therefore supports keyboard-interactive authentication
-even with graphical management applications. As with the classic ssh transport
-netcat is required on the remote side.</dd>
- <dt><code>libssh</code></dt>
- <dd> Transport over the SSH protocol using
- <a href="https://libssh.org/" title="libssh homepage">libssh</a> instead
-of the OpenSSH binary. This transport uses the libvirt authentication callback for
-all ssh authentication calls and therefore supports keyboard-interactive authentication
-even with graphical management applications. As with the classic ssh transport
-netcat is required on the remote side.</dd>
- </dl>
- <p>
- The choice of transport is determined by the <a href="uri.html#URI_remote">URI scheme</a>,
- with <code>tls</code> as the default if no explicit transport is requested.
- </p>
- <h2>
- <a id="Remote_libvirtd_configuration">libvirtd configuration file</a>
- </h2>
- <p>
-Libvirtd (the remote daemon) is configured from a file called
-<code>/etc/libvirt/libvirtd.conf</code>, or specified on
-the command line using <code>-f filename</code> or
-<code>--config filename</code>.
-</p>
- <p>
-This file should contain lines of the form below.
-Blank lines and comments beginning with <code>#</code> are ignored.
-</p>
- <pre>setting = value</pre>
- <p>The following settings, values and default are:</p>
- <table class="top_table">
- <tr>
- <th> Line </th>
- <th> Default </th>
- <th> Meaning </th>
- </tr>
- <tr>
- <td> listen_tls <i>[0|1]</i> </td>
- <td> 1 (on) </td>
- <td>
- Listen for secure TLS connections on the public TCP/IP port.
- Note: it is also necessary to start the server in listening mode
- by running it with --listen or adding a LIBVIRTD_ARGS="--listen"
- line to /etc/sysconfig/libvirtd.
-</td>
- </tr>
- <tr>
- <td> listen_tcp <i>[0|1]</i> </td>
- <td> 0 (off) </td>
- <td>
- Listen for unencrypted TCP connections on the public TCP/IP port.
- Note: it is also necessary to start the server in listening mode.
-</td>
- </tr>
- <tr>
- <td> tls_port <i>"service"</i> </td>
- <td> "16514" </td>
- <td>
- The port number or service name to listen on for secure TLS connections.
-</td>
- </tr>
- <tr>
- <td> tcp_port <i>"service"</i> </td>
- <td> "16509" </td>
- <td>
- The port number or service name to listen on for unencrypted TCP connections.
-</td>
- </tr>
- <tr>
- <td> unix_sock_group <i>"groupname"</i> </td>
- <td> "root" </td>
- <td>
- The UNIX group to own the UNIX domain socket. If the socket permissions allow
- group access, then applications running under matching group can access the
- socket. Only valid if running as root
-</td>
- </tr>
- <tr>
- <td> unix_sock_ro_perms <i>"octal-perms"</i> </td>
- <td> "0777" </td>
- <td>
- The permissions for the UNIX domain socket for read-only client connections.
- The default allows any user to monitor domains.
-</td>
- </tr>
- <tr>
- <td> unix_sock_rw_perms <i>"octal-perms"</i> </td>
- <td> "0700" </td>
- <td>
- The permissions for the UNIX domain socket for read-write client connections.
- The default allows only root to manage domains.
-</td>
- </tr>
- <tr>
- <td> tls_no_verify_certificate <i>[0|1]</i> </td>
- <td> 0 (certificates are verified) </td>
- <td>
- If set to 1 then if a client certificate check fails, it is not an error.
-</td>
- </tr>
- <tr>
- <td> tls_no_verify_address <i>[0|1]</i> </td>
- <td> 0 (addresses are verified) </td>
- <td>
- If set to 1 then if a client IP address check fails, it is not an error.
-</td>
- </tr>
- <tr>
- <td> key_file <i>"filename"</i> </td>
- <td> "/etc/pki/libvirt/ private/serverkey.pem" </td>
- <td>
- Change the path used to find the server's private key.
- If you set this to an empty string, then no private key is loaded.
-</td>
- </tr>
- <tr>
- <td> cert_file <i>"filename"</i> </td>
- <td> "/etc/pki/libvirt/ servercert.pem" </td>
- <td>
- Change the path used to find the server's certificate.
- If you set this to an empty string, then no certificate is loaded.
-</td>
- </tr>
- <tr>
- <td> ca_file <i>"filename"</i> </td>
- <td> "/etc/pki/CA/cacert.pem" </td>
- <td>
- Change the path used to find the trusted CA certificate.
- If you set this to an empty string, then no trusted CA certificate is loaded.
-</td>
- </tr>
- <tr>
- <td> crl_file <i>"filename"</i> </td>
- <td> (no CRL file is used) </td>
- <td>
- Change the path used to find the CA certificate revocation list (CRL) file.
- If you set this to an empty string, then no CRL is loaded.
-</td>
- </tr>
- <tr>
- <td> tls_allowed_dn_list ["DN1", "DN2"] </td>
- <td> (none - DNs are not checked) </td>
- <td>
- <p>
- Enable an access control list of client certificate Distinguished
- Names (DNs) which can connect to the TLS port on this server.
- </p>
- <p>
- The default is that DNs are not checked.
- </p>
- <p>
- This list may contain wildcards such as <code>"C=GB,ST=London,L=London,O=Libvirt Project,CN=*"</code>
- Any * matches in the string matches any number of consecutive characters,
- like a simplified <code>glob(7)</code>.
- </p>
- <p>
- Note that if this is an empty list, <i>no client can connect</i>.
- </p>
- <p>
- Note also that GnuTLS returns DNs without spaces
- after commas between the fields (and this is what we check against),
- but the <code>openssl x509</code> tool shows spaces.
- </p>
- To make it easy to see the order of the fields in the DN a helper executable
- <code>virt-pki-query-dn</code> is provided for this particular use case.
- <p>
-</p>
- </td>
- </tr>
- </table>
- <h2>
- <a id="Remote_IPv6">IPv6 support</a>
- </h2>
- <p>
-The libvirtd service and libvirt remote client driver both use the
-<code>getaddrinfo()</code> functions for name resolution and are
-thus fully IPv6 enabled. ie, if a server has IPv6 address configured
-the daemon will listen for incoming connections on both IPv4 and IPv6
-protocols. If a client has an IPv6 address configured and the DNS
-address resolved for a service is reachable over IPv6, then an IPv6
-connection will be made, otherwise IPv4 will be used. In summary it
-should just 'do the right thing(tm)'.
-</p>
- <h2>
- <a id="Remote_limitations">Limitations</a>
- </h2>
- <ul>
- <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>
- </body>
-</html>
--- /dev/null
+==============
+Remote support
+==============
+
+Libvirt allows you to access hypervisors running on remote machines through
+authenticated and encrypted connections.
+
+.. contents::
+
+Basic usage
+-----------
+
+On the remote machine, ``libvirtd`` should be running in general. See
+`libvirtd configuration file`_ section on how to configure ``libvirtd``.
+
+Not all hypervisors supported by libvirt require a running ``libvirtd``. If you
+want to connect to a VMware ESX/ESXi or GSX server then ``libvirtd`` is not
+necessary. See the `VMware ESX page <drvesx.html>`__ for details.
+
+To tell libvirt that you want to access a remote resource, you should supply a
+hostname in the normal `URI <uri.html>`__ 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 ``compute1.libvirt.org`` you would use
+``qemu://compute1.libvirt.org/system``.
+
+The `section on remote URIs <uri.html#URI_remote>`__ 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:
+
+- Additional errors can be generated, specifically ones relating to failures in
+ the remote transport itself.
+- Remote calls are handled synchronously, so they will be much slower than,
+ say, direct hypervisor calls.
+
+Transports
+----------
+
+Remote libvirt supports a range of transports:
+
+``tls``
+ `TLS <https://en.wikipedia.org/wiki/Transport_Layer_Security>`__ 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 `generate client and server
+ certificates <kbase/tlscerts.html>`__. The standard port is 16514.
+``unix``
+ 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 ``/var/run/libvirt/libvirt-sock`` and
+ ``/var/run/libvirt/libvirt-sock-ro`` (the latter for read-only connections).
+``ssh``
+ Transported over an ordinary `ssh (secure
+ shell) <https://www.openssh.com/>`__ connection. Requires `Netcat
+ (nc) <http://netcat.sourceforge.net/>`__ installed and libvirtd should be
+ running on the remote machine. You should use some sort of ssh key management
+ (eg. `ssh-agent <http://mah.everybody.org/docs/ssh>`__) otherwise programs
+ which use this transport will stop to ask for a password.
+``ext``
+ Any external program which can make a connection to the remote machine by
+ means outside the scope of libvirt.
+``tcp``
+ 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.
+``libssh2``
+ Transport over the SSH protocol using `libssh2 <https://libssh2.org/>`__
+ instead of the OpenSSH binary. This transport uses the libvirt authentication
+ callback for all ssh authentication calls and therefore supports
+ keyboard-interactive authentication even with graphical management
+ applications. As with the classic ssh transport netcat is required on the
+ remote side.
+``libssh``
+ Transport over the SSH protocol using `libssh <https://libssh.org/>`__
+ instead of the OpenSSH binary. This transport uses the libvirt authentication
+ callback for all ssh authentication calls and therefore supports
+ keyboard-interactive authentication even with graphical management
+ applications. As with the classic ssh transport netcat is required on the
+ remote side.
+
+The choice of transport is determined by the `URI
+scheme <uri.html#URI_remote>`__, with ``tls`` as the default if no explicit
+transport is requested.
+
+libvirtd configuration file
+---------------------------
+
+Libvirtd (the remote daemon) is configured from a file called
+``/etc/libvirt/libvirtd.conf``, or specified on the command line using
+``-f filename`` or ``--config filename``.
+
+This file should contain lines of the form below. Blank lines and comments
+beginning with ``#`` are ignored.
+
+::
+
+ setting = value
+
+The following settings, values and default are:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Line
+ - Default
+ - Meaning
+
+ * - listen_tls *[0|1]*
+ - 1 (on)
+ - Listen for secure TLS connections on the public TCP/IP port.
+ Note: it is also necessary to start the server in listening mode
+ by running it with --listen or adding a LIBVIRTD_ARGS="--listen" line to
+ /etc/sysconfig/libvirtd.
+
+ * - listen_tcp *[0|1]*
+ - 0 (off)
+ - Listen for unencrypted TCP connections on the public TCP/IP port. Note:
+ it is also necessary to start the server in listening mode.
+
+ * - tls_port *"service"*
+ - "16514"
+ - The port number or service name to listen on for secure TLS connections.
+
+ * - tcp_port *"service"*
+ - "16509"
+ - The port number or service name to listen on for unencrypted TCP
+ connections.
+
+ * - unix_sock_group *"groupname"*
+ - "root"
+ - The UNIX group to own the UNIX domain socket. If the socket permissions
+ allow group access, then applications running under matching group can
+ access the socket. Only valid if running as root
+
+ * - unix_sock_ro_perms *"octal-perms"*
+ - "0777"
+ - The permissions for the UNIX domain socket for read-only client
+ connections. The default allows any user to monitor domains.
+
+ * - unix_sock_rw_perms *"octal-perms"*
+ - "0700"
+ - The permissions for the UNIX domain socket for read-write client
+ connections. The default allows only root to manage domains.
+
+ * - tls_no_verify_certificate *[0|1]*
+ - 0 (certificates are verified)
+ - If set to 1 then if a client certificate check fails, it is not an
+ error.
+
+ * - tls_no_verify_address *[0|1]*
+ - 0 (addresses are verified)
+ - If set to 1 then if a client IP address check fails, it is not an
+ error.
+
+ * - key_file *"filename"*
+ - "/etc/pki/libvirt/private/serverkey.pem"
+ - Change the path used to find the server's private key. If you set this
+ to an empty string, then no private key is loaded.
+
+ * - cert_file *"filename"*
+ - "/etc/pki/libvirt/servercert.pem"
+ - Change the path used to find the server's certificate. If you set this
+ to an empty string, then no certificate is loaded.
+
+ * - ca_file *"filename"*
+ - "/etc/pki/CA/cacert.pem"
+ - Change the path used to find the trusted CA certificate. If you set this
+ to an empty string, then no trusted CA certificate is loaded.
+
+ * - crl_file *"filename"*
+ - (no CRL file is used)
+ - Change the path used to find the CA certificate revocation list (CRL)
+ file. If you set this to an empty string, then no CRL is loaded.
+
+ * - tls_allowed_dn_list ["DN1", "DN2"]
+ - (none - DNs are not checked)
+ - Enable an access control list of client certificate Distinguished Names
+ (DNs) which can connect to the TLS port on this server.
+
+ The default is that DNs are not checked.
+
+ This list may contain wildcards such as
+ ``"C=GB,ST=London,L=London,O=Libvirt Project,CN=*"``
+ Any * matches in the string matches any number of consecutive characters,
+ like a simplified ``glob(7)``.
+
+ Note that if this is an empty list, *no client can connect*.
+
+ Note also that GnuTLS returns DNs without spaces after commas between
+ the fields (and this is what we check against), but the ``openssl x509``
+ tool shows spaces.
+
+ To make it easy to see the order of the fields in the DN a helper
+ executable ``virt-pki-query-dn`` is provided for this particular use
+ case.
+
+IPv6 support
+------------
+
+The libvirtd service and libvirt remote client driver both use the
+``getaddrinfo()`` functions for name resolution and are thus fully IPv6 enabled.
+ie, if a server has IPv6 address configured the daemon will listen for incoming
+connections on both IPv4 and IPv6 protocols. If a client has an IPv6 address
+configured and the DNS address resolved for a service is reachable over IPv6,
+then an IPv6 connection will be made, otherwise IPv4 will be used. In summary it
+should just 'do the right thing(tm)'.
+
+Limitations
+-----------
+
+- 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.
+
+Please come and discuss these issues and more on `the mailing
+list <https://www.redhat.com/mailman/listinfo/libvir-list>`__.
projects / thirdparty / libvirt.git / commitdiff
