From nobody Mon Feb 9 01:21:54 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1650630228; cv=none; d=zohomail.com; s=zohoarc; b=gQ2wVMytPa3v16aAkq6of9qLah0G8VD33KGc0AEyflSoSGHIRaZT9q83ZVqxKI6QoCq6UI1U9hUHZdfkv2vYP+m4GOwk5sAfvSoqRELwGQRXCTFy+DsTnDVL7cBKd1iaiUHIW8HF8FdX1BreVlBOE60O2csXeZ3oQyGgwfucXAo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1650630228; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=8mOmyZFeDj2Cp5CCgDJv3w9bcGwAc4eDNEGNt6RllDA=; b=OU0bIrgHMuJvHqPAqohAaYEant4Po2UebArHbpFUNGtjgIW+ReSybuPfoSXahAshnlC38D+zn8beydSsc/oCVMVqwHRmzapKpIIyoio5/9gG1Hev10u+R8bWnh95ryDA/WuqTiBYjcJGWpCnCKoK5Nuq3sEQ+2n2hnV1oHV41zI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1650630228495640.6849877082526; Fri, 22 Apr 2022 05:23:48 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-12-JClDF5t3OFmJ4ljX7FfQtQ-1; Fri, 22 Apr 2022 08:23:45 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 1FD3A833974; Fri, 22 Apr 2022 12:23:42 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id F14F440D0174; Fri, 22 Apr 2022 12:23:41 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id A5AFD194035F; Fri, 22 Apr 2022 12:23:41 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 14D1C1940351 for ; Fri, 22 Apr 2022 12:23:40 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id EDD48416362; Fri, 22 Apr 2022 12:23:39 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.36]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3C9C0572328 for ; Fri, 22 Apr 2022 12:23:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1650630227; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=VVzOGc7jnqLO8Tm0VXinj4+VbD5DWQmIG4ehSXvywq4=; b=AvKF5RZzISmtgQfOtsSeNqIGcDCFNq8E3VS0Boss0P/SuY2UX9AP/McPnuHg2zzOTUDfg9 Q2TGyWwvwy61QiIyKbt/JQOWseEMDa0Xz/uJ3idTaJrC2Z15bG7NBEHP/Cl/wXgN3C/2RI qoS3SKALb2OXRoO2M4i2HvWY3u9AAsc= X-MC-Unique: JClDF5t3OFmJ4ljX7FfQtQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 07/15] docs: Convert 'uri' page to rst Date: Fri, 22 Apr 2022 14:23:23 +0200 Message-Id: <47c5e5326a40a6010ea4e6c93c1fdf0e95504a93.1650629879.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.10 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1650630229988100007 Content-Type: text/plain; charset="utf-8" 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 --- 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 =3D [ docs_html_in_files =3D [ 'index', - 'uri', ] docs_rst_files =3D [ @@ -106,6 +105,7 @@ docs_rst_files =3D [ '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 =3D virConnectOpenReadOnly ("test:///default");
-
    -

    - Configuring URI aliases -

    - -

    -To simplify life for administrators, it is possible to setup URI aliases i= n a -libvirt client configuration file. The configuration file is /etc/li= bvirt/libvirt.conf -for the root user, or $XDG_CONFIG_HOME/libvirt/libvirt.conf f= or any unprivileged user. -In this file, the following syntax can be used to setup aliases -

    - -
    -uri_aliases =3D [
-  "hail=3Dqemu+ssh://root@hail.cloud.example.com/system",
-  "sleet=3Dqemu+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 =3D - 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_ALI= ASES - 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 wi= ll 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=3DURI= option: -

    - 
    -virt-manager -c test:///default
-
    -

    -In virt-install use the --connect=3DURI option: -

    - 
    -virt-install --connect=3Dtest:///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
      — Connec= t 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=3D1
      — Con= nect to a -remote Xen hypervisor on host towada using TLS. Do not verify -the server's certificate. -
      • -
    • qemu+unix:///system?socket=3D/opt/libvirt/run/libvirt/libv= irt-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=3D/home/user/.ssh/kn= own_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=3D/home/user/.ssh/kno= wn_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-es= caped. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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=3Dqemu:///system
    - tls_priority - tls - A valid GNUTLS priority string -
    - Example: tls_priority=3DNORMAL:-VERS-SSL3.0
    - mode - unix, ssh, libssh, libssh2 -
    -
    auto
    automatically determine the daem= on
    -
    direct
    connect to per-driver daemons<= /dd> -
    legacy
    connect to libvirtd
    -
    - Can also be set in libvirt.conf as remote_mod= e -
    - Example: mode=3Ddirect
    - 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_pro= xy -
    - Example: proxy=3Dnative
    - 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=3D/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=3D/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=3D/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=3D/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=3D1
    - 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=3D1
    - 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=3D/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=3D/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 disabl= es - client's strict host key checking. -
    - Example: known_hosts_verify=3Dignore
    - 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=3Dprivkey,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 x= en:///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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Connection URIs +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Since libvirt supports many different kinds of virtualization (often refer= red 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 =3D virConnectOpenReadOnly ("test:///default"); + +Configuring URI aliases +----------------------- + +To simplify life for administrators, it is possible to setup URI aliases i= n 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 th= is +file, the following syntax can be used to setup aliases + +:: + + uri_aliases =3D [ + "hail=3Dqemu+ssh://root@hail.cloud.example.com/system", + "sleet=3Dqemu+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 ``=3D`` can be any libvirt URI string, including arbitrary U= RI +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 charact= ers +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=3D``\ *URI* option: + +:: + + virt-manager -c test:///default + +In virt-install use the ``--connect=3D``\ *URI* option: + +:: + + virt-install --connect=3Dtest:///default [other options] + +xen:///system URI +----------------- + +*This section describes a feature which is new in libvirt > 0.2.3. For lib= virt \ufffd\ufffd\ufffd +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 mac= hine +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][?extraparameter= s] + +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`` + \ufffd\ufffd\ufffd Connect to a remote Xen hypervisor on host ``towada`= ` using ssh transport + and ssh username ``rjones``. +- ``xen://towada/system`` + \ufffd\ufffd\ufffd Connect to a remote Xen hypervisor on host ``towada`= ` using TLS. +- ``xen://towada/system?no_verify=3D1`` + \ufffd\ufffd\ufffd Connect to a remote Xen hypervisor on host ``towada`= ` using TLS. Do not + verify the server's certificate. +- ``qemu+unix:///system?socket=3D/opt/libvirt/run/libvirt/libvirt-sock`` + \ufffd\ufffd\ufffd Connect to the local qemu instances over a non-stand= ard Unix socket (the + full path to the Unix socket is supplied explicitly in this case). +- ``test+tcp://localhost:5000/default`` + \ufffd\ufffd\ufffd Connect to a libvirtd daemon offering unencrypted TC= P/IP connections on + localhost port 5000 and use the test driver with default settings. +- ``qemu+libssh2://user@host/system?known_hosts=3D/home/user/.ssh/known_h= osts`` + \ufffd\ufffd\ufffd 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=3D/home/user/.ssh/known_ho= sts`` + \ufffd\ufffd\ufffd 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 = | ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D+ +| ``name`` | *any transport* | The name passed to t= he | +| | | remote virConnectOpe= n | +| | | function. The name i= s | +| | | normally formed by = | +| | | removing transport, = | +| | | hostname, port numbe= r, | +| | | username and extra = | +| | | parameters from the = | +| | | remote URI, but in = | +| | | certain very complex= | +| | | cases it may be bett= er | +| | | to supply the name = | +| | | explicitly. = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``name=3Dqemu:///sys= tem`` | ++-------------------------+-------------------------+---------------------= ----+ +| ``tls_priority`` | tls | A valid GNUTLS prior= ity | +| | | string = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``tls_priorit = | +| | | y=3DNORMAL:-VERS-SSL= 3.0`` | ++-------------------------+-------------------------+---------------------= ----+ +| ``mode`` | unix, ssh, libssh, | ``auto`` = | +| | libssh2 | automatically = | +| | | determine the dae= mon | +| | | ``direct`` = | +| | | connect to = | +| | | per-driver daemon= s | +| | | ``legacy`` = | +| | | connect to libvir= td | +| | | = | +| | | Can also be set in = | +| | | ``libvirt.conf`` as = | +| | | ``remote_mode`` = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``mode=3Ddirect`` = | ++-------------------------+-------------------------+---------------------= ----+ +| ``proxy`` | auto, netcat, native | ``auto`` = | +| | | try native, fallb= ack | +| | | to netcat = | +| | | ``netcat`` = | +| | | only use netcat = | +| | | ``native`` = | +| | | only use native = | +| | | = | +| | | Can also be set in = | +| | | ``libvirt.conf`` as = | +| | | ``remote_proxy`` = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``proxy=3Dnative`` = | ++-------------------------+-------------------------+---------------------= ----+ +| ``command`` | ssh, ext | The external command= . | +| | | For ext transport th= is | +| | | is required. For ssh= | +| | | the default is ``ssh= ``. | +| | | The PATH is searched= | +| | | for the command. = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``command = | +| | | =3D/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, t= his | +| | | is passed to the rem= ote | +| | | netcat command (see = | +| | | next). = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | `` = | +| | | socket=3D/opt/libvir= t/run | +| | | /libvirt/libvirt-soc= k`` | ++-------------------------+-------------------------+---------------------= ----+ +| ``netcat`` | ssh, libssh2, libssh | The name of the netc= at | +| | | command on the remot= e | +| | | 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*, *hostnam= e* | +| | | can be specified as = | +| | | part of the remote U= RI, | +| | | and *command*, *netc= at* | +| | | and *socket* come fr= om | +| | | extra parameters (or= | +| | | sensible defaults). = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``netc = | +| | | at=3D/opt/netcat/bin= /nc`` | ++-------------------------+-------------------------+---------------------= ----+ +| ``keyfile`` | ssh, libssh2, libssh | The name of the priv= ate | +| | | key file to use to = | +| | | authentication to th= e | +| | | remote machine. If t= his | +| | | option is not used t= he | +| | | default keys are use= d. | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``keyfile=3D/ = | +| | | root/.ssh/example_ke= y`` | ++-------------------------+-------------------------+---------------------= ----+ +| ``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 chec= ks | +| | | of the server's = | +| | | certificate. Note th= at | +| | | to disable server = | +| | | checks of the client= 's | +| | | certificate or IP = | +| | | address you must = | +| | | `change the libvirtd= | +| | | conf = | +| | | iguration <#Remote_l= ibv | +| | | irtd_configuration>`= __. | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``no_verify=3D1`` = | ++-------------------------+-------------------------+---------------------= ----+ +| ``no_tty`` | ssh | If set to a non-zero= | +| | | value, this stops ss= h | +| | | from asking for a = | +| | | password if it canno= t | +| | | log in to the remote= | +| | | machine automaticall= y | +| | | (eg. using ssh-agent= | +| | | etc.). Use this when= | +| | | you don't have acces= s | +| | | to a terminal - for = | +| | | example in graphical= | +| | | programs which use = | +| | | libvirt. = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: ``no_tty=3D= 1`` | ++-------------------------+-------------------------+---------------------= ----+ +| ``pkipath`` | tls | Specifies x509 = | +| | | certificates path fo= r | +| | | the client. If any o= f | +| | | the CA certificate, = | +| | | client certificate, = or | +| | | client key is missin= g, | +| | | the connection will = | +| | | fail with a fatal = | +| | | error. = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``pk = | +| | | ipath=3D/tmp/pki/cli= ent`` | ++-------------------------+-------------------------+---------------------= ----+ +| ``known_hosts`` | libssh2, libssh | Path to the known_ho= sts | +| | | file to verify the h= ost | +| | | key against. LibSSH2= | +| | | and libssh support = | +| | | OpenSSH-style = | +| | | known_hosts files, = | +| | | although LibSSH2 doe= s | +| | | not support all key = | +| | | types, so using file= s | +| | | created by the OpenS= SH | +| | | binary may result in= to | +| | | truncating the = | +| | | known_hosts file. Th= us, | +| | | with LibSSH2 it's = | +| | | recommended to use t= he | +| | | default known_hosts = | +| | | file is located in = | +| | | libvirt's client loc= al | +| | | configuration direct= ory | +| | | e.g.: = | +| | | ~/.conf = | +| | | ig/libvirt/known_hos= ts. | +| | | Note: Use absolute = | +| | | paths. = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``known_hosts=3D/ = | +| | | root/.ssh/known_host= s`` | ++-------------------------+-------------------------+---------------------= ----+ +| ``known_hosts_verify`` | libssh2, libssh | If set to ``normal``= | +| | | (default), then the = | +| | | user will be asked t= o | +| | | accept new host keys= . | +| | | If set to ``auto``, = new | +| | | host keys will be = | +| | | auto-accepted, but = | +| | | existing host keys w= ill | +| | | still be validated. = If | +| | | set to ``ignore``, t= his | +| | | disables client's = | +| | | strict host key = | +| | | checking. = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | ``know = | +| | | n_hosts_verify=3Dign= ore`` | ++-------------------------+-------------------------+---------------------= ----+ +| ``sshauth`` | libssh2, libssh | A comma separated li= st | +| | | of authentication = | +| | | methods to use. Defa= ult | +| | | (is = | +| | | "agent,privkey,passw= ord | +| | | ,keyboard-interactiv= e". | +| | | The order of the = | +| | | methods is preserved= . | +| | | Some methods may = | +| | | require additional = | +| | | parameters. = | ++-------------------------+-------------------------+---------------------= ----+ +| | | Example: = | +| | | `` = | +| | | sshauth=3Dprivkey,ag= ent`` | ++-------------------------+-------------------------+---------------------= ----+ + +test:///... Test URIs +--------------------- + +The test driver is a dummy hypervisor for test purposes. The URIs supporte= d 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 definiti= ons + 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 \ufffd\= ufffd\ufffdconnect to +the local Xen hypervisor\ufffd\ufffd?. However in future this may change t= o mean \ufffd\ufffd\ufffdconnect to +the best available hypervisor\ufffd\ufffd?. + +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`` a= s a +default choice, but should always allow the user to override the URI, eith= er by +constructing one or by allowing the user to type a URI in directly (if tha= t 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. --=20 2.35.1