From ab301453bc8c44c5ef8e5d5d3b149fc1283dc3a9 Mon Sep 17 00:00:00 2001 From: Peter Krempa Date: Thu, 14 Apr 2022 14:30:30 +0200 Subject: [PATCH] docs: Convert 'uri' page to rst Adjust links in the process. Note that the conversion to the table is temporary and upcoming patch will modify it for better readability. Signed-off-by: Peter Krempa Reviewed-by: Michal Privoznik --- docs/meson.build | 2 +- docs/uri.html.in | 507 ----------------------------------------------- docs/uri.rst | 447 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 448 insertions(+), 508 deletions(-) delete mode 100644 docs/uri.html.in create mode 100644 docs/uri.rst diff --git a/docs/meson.build b/docs/meson.build index aa866bec51..d71f6006dd 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -19,7 +19,6 @@ docs_assets = [ docs_html_in_files = [ 'index', - 'uri', ] docs_rst_files = [ @@ -106,6 +105,7 @@ docs_rst_files = [ 'testapi', 'testsuites', 'testtck', + 'uri', 'windows', ] diff --git a/docs/uri.html.in b/docs/uri.html.in deleted file mode 100644 index 61917e77b4..0000000000 --- a/docs/uri.html.in +++ /dev/null @@ -1,507 +0,0 @@ - - - - -

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");
-
    -

    - 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

    - -

    -If the URI passed to virConnectOpen* is NULL, then libvirt will use the following -logic to determine what URI to use. -

    - -
      -
    1. The environment variable LIBVIRT_DEFAULT_URI
      2. -
    2. The client configuration file uri_default parameter
      3. -
    3. Probe each hypervisor in turn until one that works is found
      4. -
    - -

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

    -

    - 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:///system. -

    -

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

    -

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

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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_priority=NORMAL:-VERS-SSL3.0
    - mode - unix, ssh, libssh, libssh2 -
    -
    auto
    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, libssh - 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). -
    - 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 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
    - 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 - 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: pkipath=/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.: ~/.config/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: known_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. -
      • -
    -

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

    -

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

    - - diff --git a/docs/uri.rst b/docs/uri.rst new file mode 100644 index 0000000000..949032e0ff --- /dev/null +++ b/docs/uri.rst @@ -0,0 +1,447 @@ +=============== +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 `__. 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"); + +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 +------------------ + +If the URI passed to ``virConnectOpen*`` is NULL, then libvirt will use the +following logic to determine what URI to use. + +#. The environment variable ``LIBVIRT_DEFAULT_URI`` +#. The client configuration file ``uri_default`` parameter +#. Probe each hypervisor in turn until one that works is found + +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 +----------------- + +*This section describes a feature which is new in libvirt > 0.2.3. For libvirt ≤ +0.2.3 use* `Legacy: "xen"`_ *URI*. + +To access a Xen hypervisor running on the local machine use the URI +``xen:///system``. + +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 `__. + +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 `__. + ++-------------------------+-------------------------+-------------------------+ +| 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. + +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:///system URI`_. + +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:///system URI`_ in all future code.