mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-23 21:34:54 +03:00
0ea50f0148
Reviewed-by: Peter Krempa <pkrempa@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
491 lines
16 KiB
XML
491 lines
16 KiB
XML
<?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@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>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>
|