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 <ahref="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. This page
documents libvirt URIs.
</p><ul><li><ahref="#URI_libvirt">Specifying URIs to libvirt</a></li>
<li><ahref="#URI_virsh">Specifying URIs to virsh, virt-manager and virt-install</a></li>
<li><ahref="#URI_xen">xen:/// URI</a></li>
<li><ahref="#URI_qemu">qemu:///... QEMU and KVM URIs</a></li>
<li><ahref="#URI_remote">Remote URIs</a></li>
<li><ahref="#URI_test">test:///... Test URIs</a></li>
<li><ahref="#URI_legacy">Other & legacy URI formats</a></li>
</ul><h3><aname="URI_libvirt"id="URI_libvirt">Specifying URIs to libvirt</a></h3><p>
The URI is passed as the <code>name</code> parameter to <ahref="html/libvirt-libvirt.html#virConnectOpen"><code>virConnectOpen</code></a> or <ahref="html/libvirt-libvirt.html#virConnectOpenReadOnly"><code>virConnectOpenReadOnly</code></a>. For example:
Remote URIs are formed by taking ordinary local URIs and adding a
hostname and/or transport name. For example:
</p><tableclass="top_table"><tr><th> Local URI </th>
<th> Remote URI </th>
<th> Meaning </th>
</tr><tr><td><code>xen:///</code></td>
<td><code>xen://oirase/</code></td>
<td> Connect to the Xen hypervisor running on host <code>oirase</code>
using TLS. </td>
</tr><tr><td><code>xen:///</code></td>
<td><code>xen+ssh://oirase/</code></td>
<td> Connect to the Xen hypervisor running on host <code>oirase</code>
by going over an <code>ssh</code> connection. </td>
</tr><tr><td><code>test:///default</code></td>
<td><code>test+tcp://oirase/default</code></td>
<td> Connect to the test driver on host <code>oirase</code>
using an unsecured TCP connection. </td>
</tr></table><p>
Remote URIs in libvirt offer a rich syntax and many features.
We refer you to <ahref="remote.html#Remote_URI_reference">the libvirt
remote URI reference</a> and <ahref="remote.html">full documentation
for libvirt remote support</a>.
</p><h3><aname="URI_test"id="URI_test">test:///... Test URIs</a></h3><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><h3><aname="URI_legacy"id="URI_legacy">Other & legacy URI formats</a></h3><h4><aname="URI_NULL"id="URI_NULL">NULL and empty string URIs</a></h4><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 <ahref="#URI_xen"><code>xen:///</code> URI</a>.
