From a34c85732dd439d99c5494478a7899a9aeb73f02 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Tue, 19 Jun 2007 16:07:58 +0000 Subject: [PATCH] Tue Jun 19 17:02:00 BST 2007 Richard W.M. Jones * docs/libvir.html docs/remote.html docs/uri.html: Documented all supported URI formats. --- ChangeLog | 5 + docs/libvir.html | 313 +++++++++++++++++++++++++++++++++++++++++++++-- docs/remote.html | 4 +- docs/uri.html | 179 +++++++++++++++++++++++++-- 4 files changed, 485 insertions(+), 16 deletions(-) diff --git a/ChangeLog b/ChangeLog index b800509acf..f6911f8f80 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Tue Jun 19 17:02:00 BST 2007 Richard W.M. Jones + + * docs/libvir.html docs/remote.html docs/uri.html: Documented + all supported URI formats. + Tue Jun 19 15:42:26 CEST 2007 Daniel Veillard * docs/site.xsl docs/libvirt.html docs/uri.html docs/*.html: diff --git a/docs/libvir.html b/docs/libvir.html index 7d19b95ab1..7bb2ab11f3 100644 --- a/docs/libvir.html +++ b/docs/libvir.html @@ -1391,7 +1391,7 @@ on configuring libvirtd for more information.

To tell libvirt that you want to access a remote resource, -you should supply a hostname in the normal URI that is passed +you should supply a hostname in the normal URI that is passed to virConnectOpen (or virsh -c ...). For example, if you normally use qemu:///system to access the system-wide QEMU daemon, then to access @@ -1478,6 +1478,10 @@ The default transport, if no other is specified, is tls.

Remote URIs

+

+See also: documentation on ordinary ("local") URIs. +

+

Remote URIs have the general form ("[...]" meaning an optional part):

@@ -2237,12 +2241,305 @@ versioning, modelled after SunRPC.

Connection URIs

-

Since libvirt supports multiple kind of virtualization and allows -to access remote nodes, one need to be able to specify what engine -a connection refers too and on which node in the network. To this -effect libvirt uses URIs as used on the Web and as defined in -RFC 2396. This -page describes how the hypervisor engine and network name are -encoded in the URIs as used by libvirt:

+

+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. This page +documents libvirt URIs. +

+ + + +

Specifying URIs to libvirt

+ +

+The URI is passed as the name parameter to virConnectOpen or virConnectOpenReadOnly. For example: +

+ +
+virConnectPtr conn = virConnectOpenReadOnly ("test:///default");
+
+ +

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. +

+ +

+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:/// URI

+ +

This section describes a feature which is new in libvirt > +0.2.3. For libvirt ≤ 0.2.3 use "xen". +

+ +

+To access a Xen hypervisor running on the local machine +use the URI xen:///. +

+ +

qemu:///... QEMU and KVM URIs

+ +

+To use QEMU support in libvirt you must be running the +libvirt_qemud daemon. The purpose of this +daemon is to manage qemu instances. +

+ +

+The libvirt_qemud daemon can be run in two ways. It may +be started by init scripts when the machine boots and run in "system +mode" (libvirt_qemud --system), in which case it manages +qemu instances on behalf of all users of the machine. It may be also +be started by the local user in what is known as "session mode" +(libvirt_qemud --session), to manage qemu instances for +just the current user. If no libvirt_qemud is running at +all, then the qemu driver starts one running in session mode. +

+ +

+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 libvirt_qemud --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. +

+ +

Remote URIs

+ +

+Remote URIs are formed by taking ordinary local URIs and adding a +hostname and/or transport name. For example: +

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Local URI Remote URI Meaning
xen:/// xen://oirase/ Connect to the Xen hypervisor running on host oirase + using TLS.
xen:/// xen+ssh://oirase/ Connect to the Xen hypervisor running on host oirase + by going over an ssh connection.
test:///default test+tcp://oirase/default Connect to the test driver on host oirase + using an unsecured TCP connection.
+ +

+Remote URIs in libvirt offer a rich syntax and many features. +We refer you to the libvirt +remote URI reference and full documentation +for libvirt remote support. +

+ +

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:/// URI. +

+ +

File paths (xend-unix-server)

+ +

+If XenD is running and configured in /etc/xen/xend-config.sxp: +

+ +
+(xend-unix-server yes)
+
+ +

+then it listens on a Unix domain socket, usually at +/var/lib/xend/xend-socket. You may pass a different path +using a file URI such as: +

+ +
+virsh -c ///var/run/xend/xend-socket
+
+ +

Legacy: http://... (xend-http-server)

+ +

+If XenD is running and configured in /etc/xen/xend-config.sxp: + +

+(xend-http-server yes)
+
+ +

+then it listens on TCP port 8000. libvirt allows you to +try to connect to xend running on remote machines by passing +http://hostname[:port]/, for example: + +

+virsh -c http://oirase/ list
+
+ +

+This method is unencrypted and insecure and is definitely not +recommended for production use. Instead use libvirt's remote support. +

+ +

+Notes: +

+ +
    +
  1. The HTTP client does not fully support IPv6.
    2. +
  2. Many features do not work as expected across HTTP connections, in + particular, virConnectGetCapabilities. + The remote support however does work + correctly.
    3. +
  3. XenD's new-style XMLRPC interface is not supported by + libvirt, only the old-style sexpr interface known in the Xen + documentation as "unix server" or "http server".
    4. +
+ +

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:/// URI in all future code. +

+ +

Legacy: Xen proxy

+ +

+Libvirt continues to support connections to a separately running Xen +proxy daemon. This provides a way to allow non-root users to make a +safe (read-only) subset of queries to the hypervisor. +

+ +

+There is no specific "Xen proxy" URI. However if a Xen URI of any of +the ordinary or legacy forms is used (eg. NULL, +"", "xen", ...) which fails, and the +user is not root, and the Xen proxy socket can be connected to +(/tmp/libvirt_proxy_conn), then libvirt will use a proxy +connection. +

+ +

+You should consider using libvirt remote support +in future. +

+ diff --git a/docs/remote.html b/docs/remote.html index a6a3b03560..93ada967a9 100644 --- a/docs/remote.html +++ b/docs/remote.html @@ -9,7 +9,7 @@ See the section on configuring libvirtd for more information.

To tell libvirt that you want to access a remote resource, -you should supply a hostname in the normal URI that is passed +you should supply a hostname in the normal URI that is passed to virConnectOpen (or virsh -c ...). For example, if you normally use qemu:///system to access the system-wide QEMU daemon, then to access @@ -74,6 +74,8 @@ Remote libvirt supports a range of transports:

The default transport, if no other is specified, is tls.

Remote URIs

+See also: documentation on ordinary ("local") URIs. +

Remote URIs have the general form ("[...]" meaning an optional part):

driver[+transport]://[username@][hostname][:port]/[path][?extraparameters] diff --git a/docs/uri.html b/docs/uri.html index 2710d685ad..0990275c99 100644 --- a/docs/uri.html +++ b/docs/uri.html @@ -1,9 +1,174 @@ -Connection URIs

Connection URIs

Since libvirt supports multiple kind of virtualization and allows -to access remote nodes, one need to be able to specify what engine -a connection refers too and on which node in the network. To this -effect libvirt uses URIs as used on the Web and as defined in -RFC 2396. This -page describes how the hypervisor engine and network name are -encoded in the URIs as used by libvirt:

main menu

related links

Graphics and design by Diana Fong

+Connection URIs

Connection URIs

+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. This page +documents libvirt URIs. +

Specifying URIs to libvirt

+The URI is passed as the name parameter to virConnectOpen or virConnectOpenReadOnly. For example: +

+virConnectPtr conn = virConnectOpenReadOnly ("test:///default");
+

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. +

+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:/// URI

This section describes a feature which is new in libvirt > +0.2.3. For libvirt ≤ 0.2.3 use "xen". +

+To access a Xen hypervisor running on the local machine +use the URI xen:///. +

qemu:///... QEMU and KVM URIs

+To use QEMU support in libvirt you must be running the +libvirt_qemud daemon. The purpose of this +daemon is to manage qemu instances. +

+The libvirt_qemud daemon can be run in two ways. It may +be started by init scripts when the machine boots and run in "system +mode" (libvirt_qemud --system), in which case it manages +qemu instances on behalf of all users of the machine. It may be also +be started by the local user in what is known as "session mode" +(libvirt_qemud --session), to manage qemu instances for +just the current user. If no libvirt_qemud is running at +all, then the qemu driver starts one running in session mode. +

+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 libvirt_qemud --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. +

Remote URIs

+Remote URIs are formed by taking ordinary local URIs and adding a +hostname and/or transport name. For example: +

+ + + + + + + + + + + +
Local URI Remote URI Meaning
xen:/// xen://oirase/ Connect to the Xen hypervisor running on host oirase + using TLS.
xen:/// xen+ssh://oirase/ Connect to the Xen hypervisor running on host oirase + by going over an ssh connection.
test:///default test+tcp://oirase/default Connect to the test driver on host oirase + using an unsecured TCP connection.

+Remote URIs in libvirt offer a rich syntax and many features. +We refer you to the libvirt +remote URI reference and full documentation +for libvirt remote support. +

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:/// URI. +

File paths (xend-unix-server)

+If XenD is running and configured in /etc/xen/xend-config.sxp: +

+(xend-unix-server yes)
+

+then it listens on a Unix domain socket, usually at +/var/lib/xend/xend-socket. You may pass a different path +using a file URI such as: +

+virsh -c ///var/run/xend/xend-socket
+

Legacy: http://... (xend-http-server)

+If XenD is running and configured in /etc/xen/xend-config.sxp: + +

+(xend-http-server yes)
+

+then it listens on TCP port 8000. libvirt allows you to +try to connect to xend running on remote machines by passing +http://hostname[:port]/, for example: + +

+virsh -c http://oirase/ list
+

+This method is unencrypted and insecure and is definitely not +recommended for production use. Instead use libvirt's remote support. +

+Notes: +

  1. The HTTP client does not fully support IPv6.
    2. +
  2. Many features do not work as expected across HTTP connections, in + particular, virConnectGetCapabilities. + The remote support however does work + correctly.
    3. +
  3. XenD's new-style XMLRPC interface is not supported by + libvirt, only the old-style sexpr interface known in the Xen + documentation as "unix server" or "http server".
    4. +

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:/// URI in all future code. +

Legacy: Xen proxy

+Libvirt continues to support connections to a separately running Xen +proxy daemon. This provides a way to allow non-root users to make a +safe (read-only) subset of queries to the hypervisor. +

+There is no specific "Xen proxy" URI. However if a Xen URI of any of +the ordinary or legacy forms is used (eg. NULL, +"", "xen", ...) which fails, and the +user is not root, and the Xen proxy socket can be connected to +(/tmp/libvirt_proxy_conn), then libvirt will use a proxy +connection. +

+You should consider using libvirt remote support +in future. +

main menu

related links

Graphics and design by Diana Fong