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 > -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@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@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
