2022-04-14 12:30:30 +00:00
|
|
|
===============
|
|
|
|
|
Connection URIs
|
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
|
.. contents::
|
|
|
|
|
|
|
|
|
|
Since libvirt supports many different kinds of virtualization (often referred to
|
|
|
|
|
as "drivers" or "hypervisors"), we need a way to be able to specify which driver
|
|
|
|
|
a connection refers to. Additionally we may want to refer to a driver on a
|
|
|
|
|
remote machine over the network.
|
|
|
|
|
|
|
|
|
|
To this end, libvirt uses URIs as used on the Web and as defined in `RFC
|
|
|
|
|
2396 <https://www.ietf.org/rfc/rfc2396.txt>`__. This page documents libvirt
|
|
|
|
|
URIs.
|
|
|
|
|
|
|
|
|
|
Specifying URIs to libvirt
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
The URI is passed as the ``name`` parameter to
|
|
|
|
|
`virConnectOpen <html/libvirt-libvirt-host.html#virConnectOpen>`__ or
|
|
|
|
|
`virConnectOpenReadOnly <html/libvirt-libvirt-host.html#virConnectOpenReadOnly>`__
|
|
|
|
|
. For example:
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
|
|
virConnectPtr conn = virConnectOpenReadOnly ("test:///default");
|
|
|
|
|
|
|
|
|
|
Configuring URI aliases
|
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
|
|
To simplify life for administrators, it is possible to setup URI aliases in a
|
|
|
|
|
libvirt client configuration file. The configuration file is
|
|
|
|
|
``/etc/libvirt/libvirt.conf`` for the root user, or
|
|
|
|
|
``$XDG_CONFIG_HOME/libvirt/libvirt.conf`` for any unprivileged user. In this
|
|
|
|
|
file, the following syntax can be used to setup aliases
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
|
|
uri_aliases = [
|
|
|
|
|
"hail=qemu+ssh://root@hail.cloud.example.com/system",
|
|
|
|
|
"sleet=qemu+ssh://root@sleet.cloud.example.com/system",
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
A URI alias should be a string made up from the characters ``a-Z, 0-9, _, -``.
|
|
|
|
|
Following the ``=`` can be any libvirt URI string, including arbitrary URI
|
|
|
|
|
parameters. URI aliases will apply to any application opening a libvirt
|
|
|
|
|
connection, unless it has explicitly passed the ``VIR_CONNECT_NO_ALIASES``
|
|
|
|
|
parameter to ``virConnectOpenAuth``. If the passed in URI contains characters
|
|
|
|
|
outside the allowed alias character set, no alias lookup will be attempted.
|
|
|
|
|
|
|
|
|
|
Default URI choice
|
|
|
|
|
------------------
|
|
|
|
|
|
2022-04-19 15:02:35 +00:00
|
|
|
If the URI passed to ``virConnectOpen*`` is NULL or empty string, then libvirt
|
|
|
|
|
will use the following logic to determine what URI to use.
|
2022-04-14 12:30:30 +00:00
|
|
|
|
|
|
|
|
#. The environment variable ``LIBVIRT_DEFAULT_URI``
|
|
|
|
|
#. The client configuration file ``uri_default`` parameter
|
|
|
|
|
#. Probe each hypervisor in turn until one that works is found
|
|
|
|
|
|
2022-04-19 15:02:35 +00:00
|
|
|
Historically an empty URI was equivalent to ``xen:///system``.
|
|
|
|
|
|
2022-04-14 12:30:30 +00:00
|
|
|
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
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
To access a Xen hypervisor running on the local machine use the URI
|
|
|
|
|
``xen:///system``.
|
|
|
|
|
|
2022-04-19 15:12:07 +00:00
|
|
|
Historically libvirt 0.2.2 and previous versions required to use the name
|
|
|
|
|
``"xen"`` to refer to the Xen hypervisor.
|
|
|
|
|
|
2022-04-14 12:30:30 +00:00
|
|
|
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.
|
