Product SiteDocumentation Site

3.2.2. Remote URIs

Remote URIs have the general form ("[...]" meaning an optional part):
Each component of the URI is described below.

Table 3.2. URI components

The name of the libvirt hypervisor driver to connect to. This is the same as that used in a local URI. Some examples are xen, qemu, lxc, openvz, and test. As a special case, the pseudo driver name remote can be used, which will cause the remote daemon to probe for an active hypervisor and pick one to use. As a general rule if the application knows what hypervisor it wants, it should always specify the explicit driver name and not rely on automatic probing.
The name of one of the data transports described earlier in this section. Possible values include tls, tcp, unix, ssh and ext. If omitted, it will default to tls if a hostname is provided, or unix if no hostname is provided.
When using the SSH data transport this allows choice of a username that differs from the client's current login name.
The fully qualified hostname of the remote machine. If using TLS with x509 certificates, or SASL with the GSSAPI/Keberos plug-in, it is critical that this hostname match the hostname used in the server's x509 certificates / Kerberos principle. Mis-matched hostnames will guarantee authentication failures.
Rarely needed, unless SSH or libvirtd has been configured to run on a non-standard TCP port. Defaults to 22 for the SSH data transport, 16509 for the TCP data transport and 16514 for the TLS data transport.
The path should be the same path used for the hypervisor driver's local URIs. For Xen, this is always just /, while for QEMU this would be /system.
The URI query parameters provide the mean to fine tune some aspects of the remote connection, and are discussed in depth in the next section.
Based on the information described here and with reference to the hypervisor specific URIs earlier in this document, it is now possible to illustrate some example remote access URIs.
Connect to a remote Xen hypervisor on host using ssh tunneled data transport and ssh username root: xen+ssh://
Connect to a remote QEMU hypervisor on host using TLS with x509 certificates: qemu://
Connect to a remote Xen hypervisor on host using TLS, skipping verification of the server's x509 certificate (NB: this is compromising your security): xen://
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): qemu+unix:///system?socket=/opt/libvirt/run/libvirt/libvirt-sock
Connect to a libvirtd daemon offering unencrypted TCP/IP connections on an alternative TCP port 5000 and use the test driver with default configuration: test+tcp://
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 backend. Note that parameter values must be URI-escaped. Refer to for more information.

Table 3.3. Extra parameters for remote URIs

any transport
The local hypervisor URI passed to the remote virConnectOpen function. This URI 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 necessary to supply the name explicitly. Example: name=qemu:///system
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
unix, ssh
The external command. For ext transport this is required. For ssh the default is ssh. The PATH is searched for the command. Example: socket=/opt/libvirt/run/libvirt/libvirt-sock
The name of the netcat command on the remote machine. The default is nc. For ssh transport, libvirt constructs an ssh command which looks like:
command -p port [-l username] hostname 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: netcat=/opt/netcat/bin/nc
Client checks of the server's certificate are disable if a non-zero value is set. Note that to disable server checks of the client's certificate or IP address you must change the libvirtd configuration. Example: no_verify=1
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 (For example, when using a ssh-agent). Use this when you don't have access to a terminal - for example in graphical programs which use libvirt. Example: no_tty=1
The following example shows how to connect to a QEMU hypervisor using a remote URI.

Example 3.8. Connecting to a remote QEMU hypervisor

#!/usr/bin/env python3
import sys
import libvirt

conn = None
    conn ='qemu+tls://host2/system')
except libvirt.libvirtError as e:
    print(repr(e), file=sys.stderr)