[PATCH 07/15] docs: Convert 'uri' page to rst

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxx>
---
 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@xxxxxxxxxxxxxxxxxxxxxx/system",
-  "sleet=qemu+ssh://root@xxxxxxxxxxxxxxxxxxxxxxx/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 &gt;
-0.2.3.  For libvirt &#x2264; 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/> &#x2014; 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/> &#x2014; Connect to a
-remote Xen hypervisor on host <code>towada</code> using TLS.
-</li>
-      <li><code>xen://towada/system?no_verify=1</code><br/> &#x2014; 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/> &#x2014;
-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/> &#x2014;
-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@host/system?known_hosts=/home/user/.ssh/known_hosts</code><br/> &#x2014;
-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/> &#x2014;
-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 &amp; 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@xxxxxxxxxxxxxxxxxxxxxx/system",
+     "sleet=qemu+ssh://root@xxxxxxxxxxxxxxxxxxxxxxx/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@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




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux