From nobody Sun Feb 8 17:41:25 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=1650630283; cv=none; d=zohomail.com; s=zohoarc; b=cF2/S0UKk2hAdaJ5rCt7yOk3W31hOeMRdaWyHDV+tAt5tG9XFzAJiFbauMSZef4y1xeeeOsNbS4uu5KDYtIoL02lKcCa6p41hDxeWQYKeZNTONu105eeNWcS6xNDhP+4C7vpuTc0sHEtitXCXeTSz12uogB28frjl3vx2z202TU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1650630283; 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=2ZgSty3lo49O1A4HwFw44e2/+FX+ZGGpTOx19pPhmgg=; b=Sp5n2miOhKeGrmwfWaiDqdiScztZihRcKpnkyQBmHFjwKGkK+/sT1W9AYcZKYcZQtI8ZWFSg/1AWLt0d3OM61owkDAhPS7gOSYMg3NkenaoJFgXt0gNNwByAe+7ViAWwM9SyUAKcIaHVOD0MKnQB/n2Fu1W0aYa0bc7mqAXiFBc= 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 1650630283903653.2274323141705; Fri, 22 Apr 2022 05:24:43 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-450-UBPYvvRdMoy358FVyQ495A-1; Fri, 22 Apr 2022 08:23:45 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 74CE01C00AD9; Fri, 22 Apr 2022 12:23:40 +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 25C7040885A8; Fri, 22 Apr 2022 12:23:40 +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 BFDA31940370; Fri, 22 Apr 2022 12:23:38 +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 07B921940361 for ; Fri, 22 Apr 2022 12:23:38 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id EC827416364; Fri, 22 Apr 2022 12:23:37 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.36]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6854741617F for ; Fri, 22 Apr 2022 12:23:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1650630282; 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=2ZgSty3lo49O1A4HwFw44e2/+FX+ZGGpTOx19pPhmgg=; b=AbDekPxRxSaCOJKk054xZIeX72H0Zq2O0hLaoccdqjRgTn1LdZDamzu8vkwSGpFDFQ2SCn A/Eiig5IlVTTviZkp80q+Ubur6VVdHXhZ34dcyAMRFhPE/2m14k1BPC85RKyHnxf9hQIUs wEG3hidDkULgl7XvP/ua3jKBacBMnro= X-MC-Unique: UBPYvvRdMoy358FVyQ495A-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 05/15] docs: Convert 'remote' page to rst Date: Fri, 22 Apr 2022 14:23:21 +0200 Message-Id: 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.2 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: 1650630284163100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa --- docs/kbase/tlscerts.rst | 4 +- docs/meson.build | 2 +- docs/remote.html.in | 297 ---------------------------------------- docs/remote.rst | 219 +++++++++++++++++++++++++++++ 4 files changed, 222 insertions(+), 300 deletions(-) delete mode 100644 docs/remote.html.in create mode 100644 docs/remote.rst diff --git a/docs/kbase/tlscerts.rst b/docs/kbase/tlscerts.rst index c6636770e6..962253e853 100644 --- a/docs/kbase/tlscerts.rst +++ b/docs/kbase/tlscerts.rst @@ -89,7 +89,7 @@ clients. There are two distinct checks involved: - The server should know that only permitted clients are connecting. This= can be done based on client's IP address, or on client's IP address and cli= ent's certificate. Checking done by the server. May be enabled and disabled i= n the - `libvirtd.conf file `__. + `libvirtd.conf file `__. For full certificate checking you will need to have certificates issued by= a recognised `Certificate Authority @@ -99,7 +99,7 @@ CA, you can set up your own CA and tell your server(s) an= d clients to trust certificates issues by your own CA. Follow the instructions in the next se= ction. Be aware that the `default configuration for -libvirtd `__ allows any client = to +libvirtd `__ allows any client to connect provided they have a valid certificate issued by the CA for their = own IP address. You may want to change this to make it less (or more) permissive, depending on your needs. diff --git a/docs/meson.build b/docs/meson.build index a18def58a4..aa866bec51 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -19,7 +19,6 @@ docs_assets =3D [ docs_html_in_files =3D [ 'index', - 'remote', 'uri', ] @@ -97,6 +96,7 @@ docs_rst_files =3D [ 'platforms', 'programming-languages', 'python', + 'remote', 'securityprocess', 'storage', 'strategy', diff --git a/docs/remote.html.in b/docs/remote.html.in deleted file mode 100644 index 3a5258a0d5..0000000000 --- a/docs/remote.html.in +++ /dev/null @@ -1,297 +0,0 @@ - - - - -

Remote support

-

-Libvirt allows you to access hypervisors running on remote -machines through authenticated and encrypted connections. -

-
    - -

    - Basic usage -

    -

    -On the remote machine, libvirtd should be running in general. -See the section -on configuring libvirtd for more information. -

    -

    - Not all hypervisors supported by libvirt require a running - libvirtd. If you want to connect to a VMware ESX/ESXi or - GSX server then libvirtd is not necessary. See the - VMware ESX page for details. -

    -

    -To tell libvirt that you want to access a remote resource, -you should supply a hostname in the normal URI th= at 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 -the system-wide QEMU daemon on a remote machine called -compute1.libvirt.org you would use -qemu://compute1.libvirt.org/system. -

    -

    -The section on remote URIs -describes in more detail these remote URIs. -

    -

    -From an API point of view, apart from the change in URI, the -API should behave the same. For example, ordinary calls -are routed over the remote connection transparently, and -values or errors from the remote side are returned to you -as if they happened locally. Some differences you may notice: -

    -
      -
    • Additional errors can be generated, specifically ones -relating to failures in the remote transport itself.
      • -
    • Remote calls are handled synchronously, so they will be -much slower than, say, direct hypervisor calls.
      • -
    -

    - Transports -

    -

    -Remote libvirt supports a range of transports: -

    -
    -
    tls
    -
    TLS - 1.0 (SSL 3.1) authenticated and encrypted TCP/IP socket, usually - listening on a public port number. To use this you will need to - gen= erate client and - server certificates. - The standard port is 16514. -
    -
    unix
    -
    Unix domain socket. Since this is only accessible on the - local machine, it is not encrypted, and uses Unix permissions or - SELinux for authentication. - The standard socket names are - /var/run/libvirt/libvirt-sock and - /var/run/libvirt/libvirt-sock-ro (the latter - for read-only connections). -
    -
    ssh
    -
    Transported over an ordinary - ssh - (secure shell) connection. - Requires Netcat (nc) - installed and libvirtd should be running - on the remote machine. You should use some sort of - ssh key management (eg. - ssh-agent) - otherwise programs which use - this transport will stop to ask for a password.
    -
    ext
    -
    Any external program which can make a connection to the - remote machine by means outside the scope of libvirt.
    -
    tcp
    -
    Unencrypted TCP/IP socket. Not recommended for production - use, this is normally disabled, but an administrator can enable - it for testing or use over a trusted network. - The standard port is 16509.
    -
    libssh2
    -
    Transport over the SSH protocol using - libssh2<= /a> instead -of the OpenSSH binary. This transport uses the libvirt authentication call= back for -all ssh authentication calls and therefore supports keyboard-interactive a= uthentication -even with graphical management applications. As with the classic ssh trans= port -netcat is required on the remote side.
    -
    libssh
    -
    Transport over the SSH protocol using - libssh= instead -of the OpenSSH binary. This transport uses the libvirt authentication call= back for -all ssh authentication calls and therefore supports keyboard-interactive a= uthentication -even with graphical management applications. As with the classic ssh trans= port -netcat is required on the remote side.
    -
    -

    - The choice of transport is determined by the URI scheme, - with tls as the default if no explicit transport is req= uested. -

    -

    - libvirtd configuration file<= /a> -

    -

    -Libvirtd (the remote daemon) is configured from a file called -/etc/libvirt/libvirtd.conf, or specified on -the command line using -f filename or ---config filename. -

    -

    -This file should contain lines of the form below. -Blank lines and comments beginning with # are ignored. -

    - 
    setting =3D value
    -

    The following settings, values and default are:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Line Default Meaning
    listen_tls [0|1] 1 (on) - Listen for secure TLS connections on the public TCP/IP port. - Note: it is also necessary to start the server in listening mode - by running it with --listen or adding a LIBVIRTD_ARGS=3D"--listen" - line to /etc/sysconfig/libvirtd. -
    listen_tcp [0|1] 0 (off) - Listen for unencrypted TCP connections on the public TCP/IP port. - Note: it is also necessary to start the server in listening mode. -
    tls_port "service" "16514" - The port number or service name to listen on for secure TLS connections. -
    tcp_port "service" "16509" - The port number or service name to listen on for unencrypted TCP connect= ions. -
    unix_sock_group "groupname" "root" - The UNIX group to own the UNIX domain socket. If the socket permissions = allow - group access, then applications running under matching group can access = the - socket. Only valid if running as root -
    unix_sock_ro_perms "octal-perms" "0777" - The permissions for the UNIX domain socket for read-only client connecti= ons. - The default allows any user to monitor domains. -
    unix_sock_rw_perms "octal-perms" "0700" - The permissions for the UNIX domain socket for read-write client connect= ions. - The default allows only root to manage domains. -
    tls_no_verify_certificate [0|1] 0 (certificates are verified) - If set to 1 then if a client certificate check fails, it is not an error. -
    tls_no_verify_address [0|1] 0 (addresses are verified) - If set to 1 then if a client IP address check fails, it is not an error. -
    key_file "filename" "/etc/pki/libvirt/ private/serverkey.pem" - Change the path used to find the server's private key. - If you set this to an empty string, then no private key is loaded. -
    cert_file "filename" "/etc/pki/libvirt/ servercert.pem" - Change the path used to find the server's certificate. - If you set this to an empty string, then no certificate is loaded. -
    ca_file "filename" "/etc/pki/CA/cacert.pem" - Change the path used to find the trusted CA certificate. - If you set this to an empty string, then no trusted CA certificate is lo= aded. -
    crl_file "filename" (no CRL file is used) - Change the path used to find the CA certificate revocation list (CRL) fi= le. - If you set this to an empty string, then no CRL is loaded. -
    tls_allowed_dn_list ["DN1", "DN2"] (none - DNs are not checked) -

    - Enable an access control list of client certificate Distinguished - Names (DNs) which can connect to the TLS port on this server. -

    -

    - The default is that DNs are not checked. -

    -

    - This list may contain wildcards such as "C=3DGB,ST=3DLondon,L=3DLo= ndon,O=3DLibvirt Project,CN=3D*" - Any * matches in the string matches any number of consecutive characters, - like a simplified glob(7). -

    -

    - Note that if this is an empty list, no client can connect. -

    -

    - Note also that GnuTLS returns DNs without spaces - after commas between the fields (and this is what we check against), - but the openssl x509 tool shows spaces. -

    - To make it easy to see the order of the fields in the DN a helper execut= able - virt-pki-query-dn is provided for this particular use case. -

    -

    -
    -

    - IPv6 support -

    -

    -The libvirtd service and libvirt remote client driver both use the -getaddrinfo() functions for name resolution and are -thus fully IPv6 enabled. ie, if a server has IPv6 address configured -the daemon will listen for incoming connections on both IPv4 and IPv6 -protocols. If a client has an IPv6 address configured and the DNS -address resolved for a service is reachable over IPv6, then an IPv6 -connection will be made, otherwise IPv4 will be used. In summary it -should just 'do the right thing(tm)'. -

    -

    - Limitations -

    -
      -
    • Fine-grained authentication: libvirt in general, -but in particular the remote case should support more -fine-grained authentication for operations, rather than -just read-write/read-only as at present. -
      • -
    -

    -Please come and discuss these issues and more on t= he mailing list. -

    - - diff --git a/docs/remote.rst b/docs/remote.rst new file mode 100644 index 0000000000..100df95e1f --- /dev/null +++ b/docs/remote.rst @@ -0,0 +1,219 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Remote support +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Libvirt allows you to access hypervisors running on remote machines through +authenticated and encrypted connections. + +.. contents:: + +Basic usage +----------- + +On the remote machine, ``libvirtd`` should be running in general. See +`libvirtd configuration file`_ section on how to configure ``libvirtd``. + +Not all hypervisors supported by libvirt require a running ``libvirtd``. I= f you +want to connect to a VMware ESX/ESXi or GSX server then ``libvirtd`` is not +necessary. See the `VMware ESX page `__ for details. + +To tell libvirt that you want to access a remote resource, you should supp= ly a +hostname in the normal `URI `__ that is passed to ``virConnectOp= en`` +(or ``virsh -c ...``). For example, if you normally use ``qemu:///system``= to +access the system-wide QEMU daemon, then to access the system-wide QEMU da= emon +on a remote machine called ``compute1.libvirt.org`` you would use +``qemu://compute1.libvirt.org/system``. + +The `section on remote URIs `__ describes in more det= ail +these remote URIs. + +From an API point of view, apart from the change in URI, the API should be= have +the same. For example, ordinary calls are routed over the remote connection +transparently, and values or errors from the remote side are returned to y= ou as +if they happened locally. Some differences you may notice: + +- Additional errors can be generated, specifically ones relating to failu= res in + the remote transport itself. +- Remote calls are handled synchronously, so they will be much slower tha= n, + say, direct hypervisor calls. + +Transports +---------- + +Remote libvirt supports a range of transports: + +``tls`` + `TLS `__ 1.0 (S= SL + 3.1) authenticated and encrypted TCP/IP socket, usually listening on a = public + port number. To use this you will need to `generate client and server + certificates `__. The standard port is 16514. +``unix`` + Unix domain socket. Since this is only accessible on the local machine,= it is + not encrypted, and uses Unix permissions or SELinux for authentication.= The + standard socket names are ``/var/run/libvirt/libvirt-sock`` and + ``/var/run/libvirt/libvirt-sock-ro`` (the latter for read-only connecti= ons). +``ssh`` + Transported over an ordinary `ssh (secure + shell) `__ connection. Requires `Netcat + (nc) `__ installed and libvirtd should = be + running on the remote machine. You should use some sort of ssh key mana= gement + (eg. `ssh-agent `__) otherwise progr= ams + which use this transport will stop to ask for a password. +``ext`` + Any external program which can make a connection to the remote machine = by + means outside the scope of libvirt. +``tcp`` + Unencrypted TCP/IP socket. Not recommended for production use, this is + normally disabled, but an administrator can enable it for testing or us= e over + a trusted network. The standard port is 16509. +``libssh2`` + Transport over the SSH protocol using `libssh2 `__ + instead of the OpenSSH binary. This transport uses the libvirt authenti= cation + callback for all ssh authentication calls and therefore supports + keyboard-interactive authentication even with graphical management + applications. As with the classic ssh transport netcat is required on t= he + remote side. +``libssh`` + Transport over the SSH protocol using `libssh `__ + instead of the OpenSSH binary. This transport uses the libvirt authenti= cation + callback for all ssh authentication calls and therefore supports + keyboard-interactive authentication even with graphical management + applications. As with the classic ssh transport netcat is required on t= he + remote side. + +The choice of transport is determined by the `URI +scheme `__, with ``tls`` as the default if no explicit +transport is requested. + +libvirtd configuration file +--------------------------- + +Libvirtd (the remote daemon) is configured from a file called +``/etc/libvirt/libvirtd.conf``, or specified on the command line using +``-f filename`` or ``--config filename``. + +This file should contain lines of the form below. Blank lines and comments +beginning with ``#`` are ignored. + +:: + + setting =3D value + +The following settings, values and default are: + +.. list-table:: + :header-rows: 1 + + * - Line + - Default + - Meaning + + * - listen_tls *[0|1]* + - 1 (on) + - Listen for secure TLS connections on the public TCP/IP port. + Note: it is also necessary to start the server in listening mode + by running it with --listen or adding a LIBVIRTD_ARGS=3D"--listen" = line to + /etc/sysconfig/libvirtd. + + * - listen_tcp *[0|1]* + - 0 (off) + - Listen for unencrypted TCP connections on the public TCP/IP port. N= ote: + it is also necessary to start the server in listening mode. + + * - tls_port *"service"* + - "16514" + - The port number or service name to listen on for secure TLS connect= ions. + + * - tcp_port *"service"* + - "16509" + - The port number or service name to listen on for unencrypted TCP + connections. + + * - unix_sock_group *"groupname"* + - "root" + - The UNIX group to own the UNIX domain socket. If the socket permiss= ions + allow group access, then applications running under matching group = can + access the socket. Only valid if running as root + + * - unix_sock_ro_perms *"octal-perms"* + - "0777" + - The permissions for the UNIX domain socket for read-only client + connections. The default allows any user to monitor domains. + + * - unix_sock_rw_perms *"octal-perms"* + - "0700" + - The permissions for the UNIX domain socket for read-write client + connections. The default allows only root to manage domains. + + * - tls_no_verify_certificate *[0|1]* + - 0 (certificates are verified) + - If set to 1 then if a client certificate check fails, it is not an + error. + + * - tls_no_verify_address *[0|1]* + - 0 (addresses are verified) + - If set to 1 then if a client IP address check fails, it is not an + error. + + * - key_file *"filename"* + - "/etc/pki/libvirt/private/serverkey.pem" + - Change the path used to find the server's private key. If you set t= his + to an empty string, then no private key is loaded. + + * - cert_file *"filename"* + - "/etc/pki/libvirt/servercert.pem" + - Change the path used to find the server's certificate. If you set t= his + to an empty string, then no certificate is loaded. + + * - ca_file *"filename"* + - "/etc/pki/CA/cacert.pem" + - Change the path used to find the trusted CA certificate. If you set= this + to an empty string, then no trusted CA certificate is loaded. + + * - crl_file *"filename"* + - (no CRL file is used) + - Change the path used to find the CA certificate revocation list (CR= L) + file. If you set this to an empty string, then no CRL is loaded. + + * - tls_allowed_dn_list ["DN1", "DN2"] + - (none - DNs are not checked) + - Enable an access control list of client certificate Distinguished N= ames + (DNs) which can connect to the TLS port on this server. + + The default is that DNs are not checked. + + This list may contain wildcards such as + ``"C=3DGB,ST=3DLondon,L=3DLondon,O=3DLibvirt Project,CN=3D*"`` + Any * matches in the string matches any number of consecutive chara= cters, + like a simplified ``glob(7)``. + + Note that if this is an empty list, *no client can connect*. + + Note also that GnuTLS returns DNs without spaces after commas betwe= en + the fields (and this is what we check against), but the ``openssl x= 509`` + tool shows spaces. + + To make it easy to see the order of the fields in the DN a helper + executable ``virt-pki-query-dn`` is provided for this particular use + case. + +IPv6 support +------------ + +The libvirtd service and libvirt remote client driver both use the +``getaddrinfo()`` functions for name resolution and are thus fully IPv6 en= abled. +ie, if a server has IPv6 address configured the daemon will listen for inc= oming +connections on both IPv4 and IPv6 protocols. If a client has an IPv6 addre= ss +configured and the DNS address resolved for a service is reachable over IP= v6, +then an IPv6 connection will be made, otherwise IPv4 will be used. In summ= ary it +should just 'do the right thing(tm)'. + +Limitations +----------- + +- Fine-grained authentication: libvirt in general, but in particular the = remote + case should support more fine-grained authentication for operations, ra= ther + than just read-write/read-only as at present. + +Please come and discuss these issues and more on `the mailing +list `__. --=20 2.35.1