[PATCH 07/15] docs: Convert 'uri' page to rst
Peter Krempa
pkrempa at redhat.com
Fri Apr 22 12:23:23 UTC 2022
Adjust links in the process.
Note that the conversion to the table is temporary and upcoming patch
will modify it for better readability.
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/meson.build | 2 +-
docs/uri.html.in | 507 -----------------------------------------------
docs/uri.rst | 447 +++++++++++++++++++++++++++++++++++++++++
3 files changed, 448 insertions(+), 508 deletions(-)
delete mode 100644 docs/uri.html.in
create mode 100644 docs/uri.rst
diff --git a/docs/meson.build b/docs/meson.build
index aa866bec51..d71f6006dd 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -19,7 +19,6 @@ docs_assets = [
docs_html_in_files = [
'index',
- 'uri',
]
docs_rst_files = [
@@ -106,6 +105,7 @@ docs_rst_files = [
'testapi',
'testsuites',
'testtck',
+ 'uri',
'windows',
]
diff --git a/docs/uri.html.in b/docs/uri.html.in
deleted file mode 100644
index 61917e77b4..0000000000
--- a/docs/uri.html.in
+++ /dev/null
@@ -1,507 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1 >Connection URIs</h1>
-
- <ul id="toc"></ul>
- <p>
-Since libvirt supports many different kinds of virtualization
-(often referred to as "drivers" or "hypervisors"), we need a
-way to be able to specify which driver a connection refers to.
-Additionally we may want to refer to a driver on a remote
-machine over the network.
-</p>
- <p>
-To this end, libvirt uses URIs as used on the Web and as defined in <a href="https://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. This page
-documents libvirt URIs.
-</p>
- <h2><a id="URI_libvirt">Specifying URIs to libvirt</a></h2>
-
- <p>
- The URI is passed as the <code>name</code> parameter to
- <a href="html/libvirt-libvirt-host.html#virConnectOpen">
- <code>virConnectOpen</code>
- </a>
- or
- <a href="html/libvirt-libvirt-host.html#virConnectOpenReadOnly">
- <code>virConnectOpenReadOnly</code>
- </a>.
- For example:
-</p>
- <pre>
-virConnectPtr conn = virConnectOpenReadOnly (<b>"test:///default"</b>);
-</pre>
- <h2>
- <a id="URI_config">Configuring URI aliases</a>
- </h2>
-
- <p>
-To simplify life for administrators, it is possible to setup URI aliases in a
-libvirt client configuration file. The configuration file is <code>/etc/libvirt/libvirt.conf</code>
-for the root user, or <code>$XDG_CONFIG_HOME/libvirt/libvirt.conf</code> for any unprivileged user.
-In this file, the following syntax can be used to setup aliases
- </p>
-
-<pre>
-uri_aliases = [
- "hail=qemu+ssh://root@hail.cloud.example.com/system",
- "sleet=qemu+ssh://root@sleet.cloud.example.com/system",
-]
-</pre>
-
-<p>
- A URI alias should be a string made up from the characters
- <code>a-Z, 0-9, _, -</code>. Following the <code>=</code>
- can be any libvirt URI string, including arbitrary URI parameters.
- URI aliases will apply to any application opening a libvirt
- connection, unless it has explicitly passed the <code>VIR_CONNECT_NO_ALIASES</code>
- parameter to <code>virConnectOpenAuth</code>. If the passed in
- URI contains characters outside the allowed alias character
- set, no alias lookup will be attempted.
-</p>
-
- <h2><a id="URI_default">Default URI choice</a></h2>
-
- <p>
-If the URI passed to <code>virConnectOpen*</code> is NULL, then libvirt will use the following
-logic to determine what URI to use.
-</p>
-
- <ol>
- <li>The environment variable <code>LIBVIRT_DEFAULT_URI</code></li>
- <li>The client configuration file <code>uri_default</code> parameter</li>
- <li>Probe each hypervisor in turn until one that works is found</li>
- </ol>
-
- <h2>
- <a id="URI_virsh">Specifying URIs to virsh, virt-manager and virt-install</a>
- </h2>
- <p>
-In virsh use the <code>-c</code> or <code>--connect</code> option:
-</p>
- <pre>
-virsh <b>-c test:///default</b> list
-</pre>
- <p>
-If virsh finds the environment variable
-<code>VIRSH_DEFAULT_CONNECT_URI</code> set, it will try this URI by
-default. Use of this environment variable is, however, deprecated
-now that libvirt supports <code>LIBVIRT_DEFAULT_URI</code> itself.
-</p>
- <p>
-When using the interactive virsh shell, you can also use the
-<code>connect</code> <i>URI</i> command to reconnect to another
-hypervisor.
-</p>
- <p>
-In virt-manager use the <code>-c</code> or <code>--connect=</code><i>URI</i> option:
-</p>
- <pre>
-virt-manager <b>-c test:///default</b>
-</pre>
- <p>
-In virt-install use the <code>--connect=</code><i>URI</i> option:
-</p>
- <pre>
-virt-install <b>--connect=test:///default</b> <i>[other options]</i>
-</pre>
- <h2>
- <a id="URI_xen">xen:///system URI</a>
- </h2>
- <p>
- <i>This section describes a feature which is new in libvirt >
-0.2.3. For libvirt ≤ 0.2.3 use <a href="#URI_legacy_xen"><code>"xen"</code></a>.</i>
- </p>
- <p>
-To access a Xen hypervisor running on the local machine
-use the URI <code>xen:///system</code>.
-</p>
- <h2>
- <a id="URI_qemu">qemu:///... QEMU and KVM URIs</a>
- </h2>
- <p>
-To use QEMU support in libvirt you must be running the
-<code>libvirtd</code> daemon (named <code>libvirt_qemud</code>
-in releases prior to 0.3.0). The purpose of this
-daemon is to manage qemu instances.
-</p>
- <p>
-The <code>libvirtd</code> daemon should be started by the
-init scripts when the machine boots. It should appear as
-a process <code>libvirtd --daemon</code> running as root
-in the background and will handle qemu instances on behalf
-of all users of the machine (among other things). </p>
- <p>
-So to connect to the daemon, one of two different URIs is used:
-</p>
- <ul>
- <li><code>qemu:///system</code> connects to a system mode daemon. </li>
- <li><code>qemu:///session</code> connects to a session mode daemon. </li>
- </ul>
- <p>
-(If you do <code>libvirtd --help</code>, the daemon will print
-out the paths of the Unix domain socket(s) that it listens on in
-the various different modes).
-</p>
- <p>
-KVM URIs are identical. You select between qemu, qemu accelerated and
-KVM guests in the <a href="format.html#KVM1">guest XML as described
-here</a>.
-</p>
- <h2>
- <a id="URI_remote">Remote URIs</a>
- </h2>
- <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/system</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/system</code><br/> — Connect to a
-remote Xen hypervisor on host <code>towada</code> using TLS.
-</li>
- <li><code>xen://towada/system?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>
-<li><code>qemu+libssh2://user at host/system?known_hosts=/home/user/.ssh/known_hosts</code><br/> —
-Connect to a remote host using a ssh connection with the libssh2 driver
-and use a different known_hosts file.</li>
-<li><code>qemu+libssh://user@host/system?known_hosts=/home/user/.ssh/known_hosts</code><br/> —
-Connect to a remote host using a ssh connection with the libssh driver
-and use a different known_hosts file.</li>
- </ul>
- <h3>
- <a id="Remote_URI_parameters">Extra parameters</a>
- </h3>
- <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 class="top_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> Example: <code>name=qemu:///system</code> </td>
- </tr>
- <tr>
- <td>
- <code>tls_priority</code>
- </td>
- <td> tls </td>
- <td>
- A valid GNUTLS priority string
-</td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>tls_priority=NORMAL:-VERS-SSL3.0</code> </td>
- </tr>
- <tr>
- <td>
- <code>mode</code>
- </td>
- <td> unix, ssh, libssh, libssh2 </td>
- <td>
- <dl>
- <dt><code>auto</code></dt><dd>automatically determine the daemon</dd>
- <dt><code>direct</code></dt><dd>connect to per-driver daemons</dd>
- <dt><code>legacy</code></dt><dd>connect to libvirtd</dd>
- </dl>
- Can also be set in <code>libvirt.conf</code> as <code>remote_mode</code>
- </td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>mode=direct</code> </td>
- </tr>
- <tr>
- <td>
- <code>proxy</code>
- </td>
- <td>auto, netcat, native </td>
- <td>
- <dl>
- <dt><code>auto</code></dt><dd>try native, fallback to netcat</dd>
- <dt><code>netcat</code></dt><dd>only use netcat</dd>
- <dt><code>native</code></dt><dd>only use native</dd>
- </dl>
- Can also be set in <code>libvirt.conf</code> as <code>remote_proxy</code>
- </td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>proxy=native</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> Example: <code>command=/opt/openssh/bin/ssh</code> </td>
- </tr>
- <tr>
- <td>
- <code>socket</code>
- </td>
- <td> unix, ssh, libssh2, libssh </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> Example: <code>socket=/opt/libvirt/run/libvirt/libvirt-sock</code> </td>
- </tr>
- <tr>
- <td>
- <code>netcat</code>
- </td>
- <td> ssh, libssh2, libssh </td>
- <td>
- The name of the netcat command on the remote machine.
- The default is <code>nc</code>. This is not permitted
- when using the <code>native</code> proxy mode. 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> Example: <code>netcat=/opt/netcat/bin/nc</code> </td>
- </tr>
-
- <tr>
- <td>
- <code>keyfile</code>
- </td>
- <td> ssh, libssh2, libssh </td>
- <td>
- The name of the private key file to use to authentication to the remote
- machine. If this option is not used the default keys are used.
- </td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>keyfile=/root/.ssh/example_key</code> </td>
- </tr>
-
- <tr>
- <td>
- <code>no_verify</code>
- </td>
- <td> ssh, tls </td>
- <td>
- SSH: If set to a non-zero value, this disables client's strict host key
- checking making it auto-accept new host keys. Existing host keys will
- still be validated.
- <br/>
- <br/>
- 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
- <a href="#Remote_libvirtd_configuration">change the libvirtd
- configuration</a>.
-</td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>no_verify=1</code> </td>
- </tr>
- <tr>
- <td>
- <code>no_tty</code>
- </td>
- <td> ssh </td>
- <td>
- If set to a non-zero value, this stops ssh from asking for
- a password if it cannot log in to the remote machine automatically
- (eg. using ssh-agent etc.). Use this when you don't have access
- to a terminal - for example in graphical programs which use libvirt.
-</td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>no_tty=1</code> </td>
- </tr>
- <tr>
- <td>
- <code>pkipath</code>
- </td>
- <td> tls</td>
- <td>
- Specifies x509 certificates path for the client. If any of
- the CA certificate, client certificate, or client key is
- missing, the connection will fail with a fatal error.
- </td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>pkipath=/tmp/pki/client</code> </td>
- </tr>
- <tr>
- <td>
- <code>known_hosts</code>
- </td>
- <td> libssh2, libssh </td>
- <td>
- Path to the known_hosts file to verify the host key against. LibSSH2 and
- libssh support OpenSSH-style known_hosts files, although LibSSH2 does not
- support all key types, so using files created by the OpenSSH binary may
- result into truncating the known_hosts file. Thus, with LibSSH2 it's
- recommended to use the default known_hosts file is located in libvirt's
- client local configuration directory e.g.: ~/.config/libvirt/known_hosts.
- Note: Use absolute paths.
-</td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>known_hosts=/root/.ssh/known_hosts</code> </td>
- </tr>
- <tr>
- <td>
- <code>known_hosts_verify</code>
- </td>
- <td> libssh2, libssh </td>
- <td>
- If set to <code>normal</code> (default), then the user will be
- asked to accept new host keys. If set to <code>auto</code>, new
- host keys will be auto-accepted, but existing host keys will
- still be validated. If set to <code>ignore</code>, this disables
- client's strict host key checking.
- </td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>known_hosts_verify=ignore</code> </td>
- </tr>
- <tr>
- <td>
- <code>sshauth</code>
- </td>
- <td> libssh2, libssh </td>
- <td>
- A comma separated list of authentication methods to use. Default (is
- "agent,privkey,password,keyboard-interactive". The order of the methods
- is preserved. Some methods may require additional parameters.
-</td>
- </tr>
- <tr>
- <td colspan="2"/>
- <td> Example: <code>sshauth=privkey,agent</code> </td>
- </tr>
- </table>
- <h2>
- <a id="URI_test">test:///... Test URIs</a>
- </h2>
- <p>
-The test driver is a dummy hypervisor for test purposes.
-The URIs supported are:
-</p>
- <ul>
- <li><code>test:///default</code> connects to a default set of
-host definitions built into the driver. </li>
- <li><code>test:///path/to/host/definitions</code> connects to
-a set of host definitions held in the named file.
-</li>
- </ul>
- <h2>
- <a id="URI_legacy">Other & legacy URI formats</a>
- </h2>
- <h3>
- <a id="URI_NULL">NULL and empty string URIs</a>
- </h3>
- <p>
-Libvirt allows you to pass a <code>NULL</code> pointer to
-<code>virConnectOpen*</code>. Empty string (<code>""</code>) acts in
-the same way. Traditionally this has meant
-<q>connect to the local Xen hypervisor</q>. However in future this
-may change to mean <q>connect to the best available hypervisor</q>.
-</p>
- <p>
-The theory is that if, for example, Xen is unavailable but the
-machine is running an OpenVZ kernel, then we should not try to
-connect to the Xen hypervisor since that is obviously the wrong
-thing to do.
-</p>
- <p>
-In any case applications linked to libvirt can continue to pass
-<code>NULL</code> as a default choice, but should always allow the
-user to override the URI, either by constructing one or by allowing
-the user to type a URI in directly (if that is appropriate). If your
-application wishes to connect specifically to a Xen hypervisor, then
-for future proofing it should choose a full <a href="#URI_xen"><code>xen:///system</code> URI</a>.
-</p>
- <h3>
- <a id="URI_legacy_xen">Legacy: <code>"xen"</code></a>
- </h3>
- <p>
-Another legacy URI is to specify name as the string
-<code>"xen"</code>. This will continue to refer to the Xen
-hypervisor. However you should prefer a full <a href="#URI_xen"><code>xen:///system</code> URI</a> in all future code.
-</p>
- </body>
-</html>
diff --git a/docs/uri.rst b/docs/uri.rst
new file mode 100644
index 0000000000..949032e0ff
--- /dev/null
+++ b/docs/uri.rst
@@ -0,0 +1,447 @@
+===============
+Connection URIs
+===============
+
+.. contents::
+
+Since libvirt supports many different kinds of virtualization (often referred to
+as "drivers" or "hypervisors"), we need a way to be able to specify which driver
+a connection refers to. Additionally we may want to refer to a driver on a
+remote machine over the network.
+
+To this end, libvirt uses URIs as used on the Web and as defined in `RFC
+2396 <https://www.ietf.org/rfc/rfc2396.txt>`__. This page documents libvirt
+URIs.
+
+Specifying URIs to libvirt
+--------------------------
+
+The URI is passed as the ``name`` parameter to
+`virConnectOpen <html/libvirt-libvirt-host.html#virConnectOpen>`__ or
+`virConnectOpenReadOnly <html/libvirt-libvirt-host.html#virConnectOpenReadOnly>`__
+. For example:
+
+::
+
+ virConnectPtr conn = virConnectOpenReadOnly ("test:///default");
+
+Configuring URI aliases
+-----------------------
+
+To simplify life for administrators, it is possible to setup URI aliases in a
+libvirt client configuration file. The configuration file is
+``/etc/libvirt/libvirt.conf`` for the root user, or
+``$XDG_CONFIG_HOME/libvirt/libvirt.conf`` for any unprivileged user. In this
+file, the following syntax can be used to setup aliases
+
+::
+
+ uri_aliases = [
+ "hail=qemu+ssh://root@hail.cloud.example.com/system",
+ "sleet=qemu+ssh://root@sleet.cloud.example.com/system",
+ ]
+
+A URI alias should be a string made up from the characters ``a-Z, 0-9, _, -``.
+Following the ``=`` can be any libvirt URI string, including arbitrary URI
+parameters. URI aliases will apply to any application opening a libvirt
+connection, unless it has explicitly passed the ``VIR_CONNECT_NO_ALIASES``
+parameter to ``virConnectOpenAuth``. If the passed in URI contains characters
+outside the allowed alias character set, no alias lookup will be attempted.
+
+Default URI choice
+------------------
+
+If the URI passed to ``virConnectOpen*`` is NULL, then libvirt will use the
+following logic to determine what URI to use.
+
+#. The environment variable ``LIBVIRT_DEFAULT_URI``
+#. The client configuration file ``uri_default`` parameter
+#. Probe each hypervisor in turn until one that works is found
+
+Specifying URIs to virsh, virt-manager and virt-install
+-------------------------------------------------------
+
+In virsh use the ``-c`` or ``--connect`` option:
+
+::
+
+ virsh -c test:///default list
+
+If virsh finds the environment variable ``VIRSH_DEFAULT_CONNECT_URI`` set, it
+will try this URI by default. Use of this environment variable is, however,
+deprecated now that libvirt supports ``LIBVIRT_DEFAULT_URI`` itself.
+
+When using the interactive virsh shell, you can also use the ``connect`` *URI*
+command to reconnect to another hypervisor.
+
+In virt-manager use the ``-c`` or ``--connect=``\ *URI* option:
+
+::
+
+ virt-manager -c test:///default
+
+In virt-install use the ``--connect=``\ *URI* option:
+
+::
+
+ virt-install --connect=test:///default [other options]
+
+xen:///system URI
+-----------------
+
+*This section describes a feature which is new in libvirt > 0.2.3. For libvirt ≤
+0.2.3 use* `Legacy: "xen"`_ *URI*.
+
+To access a Xen hypervisor running on the local machine use the URI
+``xen:///system``.
+
+qemu:///... QEMU and KVM URIs
+-----------------------------
+
+To use QEMU support in libvirt you must be running the ``libvirtd`` daemon
+(named ``libvirt_qemud`` in releases prior to 0.3.0). The purpose of this daemon
+is to manage qemu instances.
+
+The ``libvirtd`` daemon should be started by the init scripts when the machine
+boots. It should appear as a process ``libvirtd --daemon`` running as root in
+the background and will handle qemu instances on behalf of all users of the
+machine (among other things).
+
+So to connect to the daemon, one of two different URIs is used:
+
+- ``qemu:///system`` connects to a system mode daemon.
+- ``qemu:///session`` connects to a session mode daemon.
+
+(If you do ``libvirtd --help``, the daemon will print out the paths of the Unix
+domain socket(s) that it listens on in the various different modes).
+
+KVM URIs are identical. You select between qemu, qemu accelerated and KVM guests
+in the `guest XML as described here <format.html#KVM1>`__.
+
+Remote URIs
+-----------
+
+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/system``
+ — Connect to a remote Xen hypervisor on host ``towada`` using ssh transport
+ and ssh username ``rjones``.
+- ``xen://towada/system``
+ — Connect to a remote Xen hypervisor on host ``towada`` using TLS.
+- ``xen://towada/system?no_verify=1``
+ — Connect to a remote Xen hypervisor on host ``towada`` using TLS. Do not
+ verify the server's certificate.
+- ``qemu+unix:///system?socket=/opt/libvirt/run/libvirt/libvirt-sock``
+ — 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).
+- ``test+tcp://localhost:5000/default``
+ — Connect to a libvirtd daemon offering unencrypted TCP/IP connections on
+ localhost port 5000 and use the test driver with default settings.
+- ``qemu+libssh2://user at host/system?known_hosts=/home/user/.ssh/known_hosts``
+ — Connect to a remote host using a ssh connection with the libssh2 driver and
+ use a different known_hosts file.
+- ``qemu+libssh://user@host/system?known_hosts=/home/user/.ssh/known_hosts``
+ — Connect to a remote host using a ssh connection with the libssh driver and
+ use a different known_hosts file.
+
+Extra parameters
+~~~~~~~~~~~~~~~~
+
+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 <http://xmlsoft.org/html/libxml-uri.html#xmlURIEscapeStr>`__.
+
++-------------------------+-------------------------+-------------------------+
+| 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`` |
++-------------------------+-------------------------+-------------------------+
+| ``tls_priority`` | tls | A valid GNUTLS priority |
+| | | string |
++-------------------------+-------------------------+-------------------------+
+| | | Example: |
+| | | ``tls_priorit |
+| | | y=NORMAL:-VERS-SSL3.0`` |
++-------------------------+-------------------------+-------------------------+
+| ``mode`` | unix, ssh, libssh, | ``auto`` |
+| | libssh2 | automatically |
+| | | determine the daemon |
+| | | ``direct`` |
+| | | connect to |
+| | | per-driver daemons |
+| | | ``legacy`` |
+| | | connect to libvirtd |
+| | | |
+| | | Can also be set in |
+| | | ``libvirt.conf`` as |
+| | | ``remote_mode`` |
++-------------------------+-------------------------+-------------------------+
+| | | Example: |
+| | | ``mode=direct`` |
++-------------------------+-------------------------+-------------------------+
+| ``proxy`` | auto, netcat, native | ``auto`` |
+| | | try native, fallback |
+| | | to netcat |
+| | | ``netcat`` |
+| | | only use netcat |
+| | | ``native`` |
+| | | only use native |
+| | | |
+| | | Can also be set in |
+| | | ``libvirt.conf`` as |
+| | | ``remote_proxy`` |
++-------------------------+-------------------------+-------------------------+
+| | | Example: |
+| | | ``proxy=native`` |
++-------------------------+-------------------------+-------------------------+
+| ``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, libssh2, | The path to the Unix |
+| | libssh | 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, libssh2, libssh | The name of the netcat |
+| | | command on the remote |
+| | | machine. The default is |
+| | | ``nc``. This is not |
+| | | permitted when using |
+| | | the ``native`` proxy |
+| | | mode. For ssh |
+| | | transport, libvirt |
+| | | constructs an ssh |
+| | | command which looks |
+| | | like: |
+| | | |
+| | | ``command -p port`` |
+| | | ``[-l username]`` |
+| | | ``hostname`` or |
+| | | |
+| | | ``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: |
+| | | ``netc |
+| | | at=/opt/netcat/bin/nc`` |
++-------------------------+-------------------------+-------------------------+
+| ``keyfile`` | ssh, libssh2, libssh | The name of the private |
+| | | key file to use to |
+| | | authentication to the |
+| | | remote machine. If this |
+| | | option is not used the |
+| | | default keys are used. |
++-------------------------+-------------------------+-------------------------+
+| | | Example: |
+| | | ``keyfile=/ |
+| | | root/.ssh/example_key`` |
++-------------------------+-------------------------+-------------------------+
+| ``no_verify`` | ssh, tls | SSH: If set to a |
+| | | non-zero value, this |
+| | | disables client's |
+| | | strict host key |
+| | | checking making it |
+| | | auto-accept new host |
+| | | keys. Existing host |
+| | | keys will still be |
+| | | validated. |
+| | | 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 |
+| | | conf |
+| | | iguration <#Remote_libv |
+| | | irtd_configuration>`__. |
++-------------------------+-------------------------+-------------------------+
+| | | Example: |
+| | | ``no_verify=1`` |
++-------------------------+-------------------------+-------------------------+
+| ``no_tty`` | ssh | If set to a non-zero |
+| | | value, this stops ssh |
+| | | from asking for a |
+| | | password if it cannot |
+| | | log in to the remote |
+| | | machine automatically |
+| | | (eg. using ssh-agent |
+| | | etc.). Use this when |
+| | | you don't have access |
+| | | to a terminal - for |
+| | | example in graphical |
+| | | programs which use |
+| | | libvirt. |
++-------------------------+-------------------------+-------------------------+
+| | | Example: ``no_tty=1`` |
++-------------------------+-------------------------+-------------------------+
+| ``pkipath`` | tls | Specifies x509 |
+| | | certificates path for |
+| | | the client. If any of |
+| | | the CA certificate, |
+| | | client certificate, or |
+| | | client key is missing, |
+| | | the connection will |
+| | | fail with a fatal |
+| | | error. |
++-------------------------+-------------------------+-------------------------+
+| | | Example: |
+| | | ``pk |
+| | | ipath=/tmp/pki/client`` |
++-------------------------+-------------------------+-------------------------+
+| ``known_hosts`` | libssh2, libssh | Path to the known_hosts |
+| | | file to verify the host |
+| | | key against. LibSSH2 |
+| | | and libssh support |
+| | | OpenSSH-style |
+| | | known_hosts files, |
+| | | although LibSSH2 does |
+| | | not support all key |
+| | | types, so using files |
+| | | created by the OpenSSH |
+| | | binary may result into |
+| | | truncating the |
+| | | known_hosts file. Thus, |
+| | | with LibSSH2 it's |
+| | | recommended to use the |
+| | | default known_hosts |
+| | | file is located in |
+| | | libvirt's client local |
+| | | configuration directory |
+| | | e.g.: |
+| | | ~/.conf |
+| | | ig/libvirt/known_hosts. |
+| | | Note: Use absolute |
+| | | paths. |
++-------------------------+-------------------------+-------------------------+
+| | | Example: |
+| | | ``known_hosts=/ |
+| | | root/.ssh/known_hosts`` |
++-------------------------+-------------------------+-------------------------+
+| ``known_hosts_verify`` | libssh2, libssh | If set to ``normal`` |
+| | | (default), then the |
+| | | user will be asked to |
+| | | accept new host keys. |
+| | | If set to ``auto``, new |
+| | | host keys will be |
+| | | auto-accepted, but |
+| | | existing host keys will |
+| | | still be validated. If |
+| | | set to ``ignore``, this |
+| | | disables client's |
+| | | strict host key |
+| | | checking. |
++-------------------------+-------------------------+-------------------------+
+| | | Example: |
+| | | ``know |
+| | | n_hosts_verify=ignore`` |
++-------------------------+-------------------------+-------------------------+
+| ``sshauth`` | libssh2, libssh | A comma separated list |
+| | | of authentication |
+| | | methods to use. Default |
+| | | (is |
+| | | "agent,privkey,password |
+| | | ,keyboard-interactive". |
+| | | The order of the |
+| | | methods is preserved. |
+| | | Some methods may |
+| | | require additional |
+| | | parameters. |
++-------------------------+-------------------------+-------------------------+
+| | | Example: |
+| | | `` |
+| | | sshauth=privkey,agent`` |
++-------------------------+-------------------------+-------------------------+
+
+test:///... Test URIs
+---------------------
+
+The test driver is a dummy hypervisor for test purposes. The URIs supported are:
+
+- ``test:///default`` connects to a default set of host definitions built into
+ the driver.
+- ``test:///path/to/host/definitions`` connects to a set of host definitions
+ held in the named file.
+
+Other & legacy URI formats
+--------------------------
+
+NULL and empty string URIs
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Libvirt allows you to pass a ``NULL`` pointer to ``virConnectOpen*``. Empty
+string (``""``) acts in the same way. Traditionally this has meant “connect to
+the local Xen hypervisorâ€. However in future this may change to mean “connect to
+the best available hypervisorâ€.
+
+The theory is that if, for example, Xen is unavailable but the machine is
+running an OpenVZ kernel, then we should not try to connect to the Xen
+hypervisor since that is obviously the wrong thing to do.
+
+In any case applications linked to libvirt can continue to pass ``NULL`` as a
+default choice, but should always allow the user to override the URI, either by
+constructing one or by allowing the user to type a URI in directly (if that is
+appropriate). If your application wishes to connect specifically to a Xen
+hypervisor, then for future proofing it should choose a full
+`xen:///system URI`_.
+
+Legacy: ``"xen"``
+~~~~~~~~~~~~~~~~~
+
+Another legacy URI is to specify name as the string ``"xen"``. This will
+continue to refer to the Xen hypervisor. However you should prefer a full
+`xen:///system URI`_ in all future code.
--
2.35.1
More information about the libvir-list
mailing list