From nobody Mon Feb 9 01:21:43 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.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 63.128.21.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=1615830069; cv=none; d=zohomail.com; s=zohoarc; b=JQ+kKmlejrVuTu04KqtMG+vV6eEoI9TbNmhRlgMea6GNLsME9YOe7EANhaJtW6mSl5N3zWLQl6rGfOpB5fDTSK0n6aRg0F91cEjFYNwYAeaNT/CDguEmwGuDV5JGfsC542t3j2Fzrqi/R0OCzAdo4x3Pr/sqznWzUZtFky3STYQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615830069; h=Content-Type:Content-Transfer-Encoding:Cc: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=MtTbCcLQSuRubQqoKJtC4cDbJVxynOt51K9tcLEoZrc=; b=dfZcLqnlmosfdkPYhPMqj7PUQ1M/7wtWhpzFj1ysPPoLgJN9A87u5NreTfesnNfJonwigR8ZTjUp7m0ty16ukVxWcvr6mks+tFplloKGoxchndA73g2nmF9BfZQmUkMC6tc64ZkFOX5kj/habqANO5Aru3yIXOnU6uwKghMWyl0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1615830069599464.22166903759523; Mon, 15 Mar 2021 10:41:09 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-196-0nrCL-HSOM-76EelrgM4bQ-1; Mon, 15 Mar 2021 13:40:10 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 1B00684B9A8; Mon, 15 Mar 2021 17:40:03 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E43A0100F49F; Mon, 15 Mar 2021 17:40:02 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 91FAE1800B99; Mon, 15 Mar 2021 17:40:02 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12FHduSQ003448 for ; Mon, 15 Mar 2021 13:39:56 -0400 Received: by smtp.corp.redhat.com (Postfix) id 74A32620DE; Mon, 15 Mar 2021 17:39:56 +0000 (UTC) Received: from nautilus.local (unknown [10.40.192.76]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9CC3D19EF2; Mon, 15 Mar 2021 17:39:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615830068; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=MtTbCcLQSuRubQqoKJtC4cDbJVxynOt51K9tcLEoZrc=; b=iNHDqP5IXHMCmlywkNW6V+O2dO0hEMpdE/UqTQCc2usMFWaOKI90r1LLGhiQyBuNMVGARv eKy1CiXqN+dmuvnqcm9uEgjX/C19xG03L8DRR9jvXB3hHRmXTSQpipr5uPjqOTEeu4EpAZ 8A2CT5QLzTmn9j7HQWyrnVzDapmtOd4= X-MC-Unique: 0nrCL-HSOM-76EelrgM4bQ-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH v2 2/3] docs: html.in: Convert auth to rst Date: Mon, 15 Mar 2021 18:39:45 +0100 Message-Id: <3fd45b094e93e9baf1ad5c9e9b76b3a7611b92c2.1615829966.git.eskultet@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 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) Content-Type: text/plain; charset="utf-8" There was one external reference to this page's section which was fixed manually. Signed-off-by: Erik Skultety --- docs/auth.html.in | 368 --------------------------------- docs/auth.rst | 343 ++++++++++++++++++++++++++++++ docs/kbase/locking-sanlock.rst | 2 +- docs/meson.build | 2 +- 4 files changed, 345 insertions(+), 370 deletions(-) delete mode 100644 docs/auth.html.in create mode 100644 docs/auth.rst diff --git a/docs/auth.html.in b/docs/auth.html.in deleted file mode 100644 index 9b940a8598..0000000000 --- a/docs/auth.html.in +++ /dev/null @@ -1,368 +0,0 @@ - - - - -

Connection authentication

-

- When connecting to libvirt, some connections may require client - authentication before allowing use of the APIs. The set of possible - authentication mechanisms is administrator controlled, independent - of applications using libvirt. Once authenticated, libvirt can apply - fine grained access control to the operatio= ns - performed by a client. -

- -
    - -

    Client configuration

    - -

    - When connecting to a remote hypervisor which requires authentication, -most libvirt applications will prompt the user for the credentials. It is -also possible to provide a client configuration file containing all the -authentication credentials, avoiding any interaction. Libvirt will look -for the authentication file using the following sequence: -

    -
      -
    1. The file path specified by the $LIBVIRT_AUTH_FILE environment - variable.
      2. -
    2. The file path specified by the "authfile=3D/some/file" URI - query parameter
      3. -
    3. The file $XDG_CONFIG_HOME/libvirt/auth.conf
      4. -
    4. The file /etc/libvirt/auth.conf
      5. -
    - -

    - The auth configuration file uses the traditional ".ini" - style syntax. There are two types of groups that can be present in - the config. First there are one or more credential - sets, which provide the actual authentication credentials. The keys - within the group may be: -

    - -
      -
    • username: the user login name to act as. This - is relevant for ESX, Xen, HyperV and SSH, but probably not - the one you want to libvirtd with SASL.
      • -
    • authname: the name to authorize as. This is - what is commonly required for libvirtd with SASL.
      • -
    • password: the secret password
      • -
    • realm: the domain realm for SASL, mostly - unused
      • -
    - -

    - Each set of credentials has a name, which is part of the group - entry name. Overall the syntax is -

    - - 
    -[credentials-$NAME]
-credname1=3Dvalue1
-credname2=3Dvalue2
    - -

    - For example, to define two sets of credentials used for production - and test machines, using libvirtd, and a further ESX server for dev: -

    -
    -[credentials-test]
-authname=3Dfred
-password=3D123456
-
-[credentials-prod]
-authname=3Dbar
-password=3Dletmein
-
-[credentials-dev]
-username=3Djoe
-password=3Dhello
-
-[credentials-defgrp]
-username=3Ddefuser
-password=3Ddefpw
    - -

    - The second set of groups provide mappings of credentials to - specific machine services. The config file group names compromise - the service type and host: -

    - - 
    -[auth-$SERVICE-$HOSTNAME]
-credentials=3D$CREDENTIALS
    - -

    - For example, following the previous example, here is how to - map some machines. For convenience libvirt supports a default - mapping of credentials to machines: -

    - - 
    -[auth-libvirt-test1.example.com]
-credentials=3Dtest
-
-[auth-libvirt-test2.example.com]
-credentials=3Dtest
-
-[auth-libvirt-demo3.example.com]
-credentials=3Dtest
-
-[auth-libvirt-prod1.example.com]
-credentials=3Dprod
-
-[auth-libvirt-default]
-credentials=3Ddefgrp
-
-[auth-esx-dev1.example.com]
-credentials=3Ddev
-
-[auth-esx-default]
-credentials=3Ddefgrp
    - - -

    - The following service types are known to libvirt: -

    - -
      -
    • esx - used for connections to an ESX or - VirtualCenter server
      • -
    • hyperv - used for connections to an HyperV - server
      • -
    • libvirt - used for connections to a libvirtd - server, which is configured with SASL auth
      • -
    • ssh - used for connections to a remote QEMU driver - over SSH
      • -
    - -

    - Applications using libvirt are free to use this same configuration - file for storing other credentials. For example, it can be used - to storage VNC or SPICE login credentials -

    - -

    Server configuration

    -

    -The libvirt daemon allows the administrator to choose the authentication -mechanisms used for client connections on each network socket independentl= y. -This is primarily controlled via the libvirt daemon master config file in -/etc/libvirt/libvirtd.conf. Each of the libvirt sockets can -have its authentication mechanism configured independently. There is -currently a choice of none, polkit, and sa= sl. -The SASL scheme can be further configured to choose between a large -number of different mechanisms. -

    -

    UNIX socket permissions/group<= /h2> -

    -If libvirt does not contain support for PolicyKit, then access control for -the UNIX domain socket is done using traditional file user/group ownership -and permissions. There are 2 sockets, one for full read-write access, the -other for read-only access. The RW socket will be restricted (mode 0700) to -only allow the root user to connect. The read-only socket will -be open access (mode 0777) to allow any user to connect. -

    -

    -To allow non-root users greater access, the libvirtd.conf file -can be edited to change the permissions via the unix_sock_rw_perms, -config parameter and to set a user group via the unix_sock_group -parameter. For example, setting the former to mode 0770 and t= he -latter wheel would let any user in the wheel group connect to -the libvirt daemon. -

    -

    UNIX socket PolicyKit auth

    -

    -If libvirt contains support for PolicyKit, then access control options are -more advanced. The auth_unix_rw parameter will default to -polkit, and the file permissions will default to 0777 -even on the RW socket. Upon connecting to the socket, the client applicati= on -will be required to identify itself with PolicyKit. The default policy for= the -RW daemon socket will require any application running in the current deskt= op -session to authenticate using the user's password. This is akin to s= udo -auth, but does not require that the client application ultimately run as r= oot. -Default policy will still allow any application to connect to the RO socke= t. -

    -

    -The default policy can be overridden by creating a new policy file in the -/etc/polkit-1/rules.d directory. Information on the options -available can be found by reading the polkit(8) man page. The -two libvirt actions are named org.libvirt.unix.manage for full -management access, and org.libvirt.unix.monitor for read-only -access. -

    -

    -As an example, creating /etc/polkit-1/rules.d/80-libvirt-manage.rule= s -with the following gives the user fred full management access -when accessing from an active local session: -

    -
    polkit.addRule(function(action, subject) {
-  if (action.id =3D=3D "org.libvirt.unix.manage" &&
-      subject.local && subject.active && subject.user =3D=
=3D "fred") {
-      return polkit.Result.YES;
-  }
-});
    -

    -Older versions of PolicyKit used policy files ending with .pkla in the -local override directory /etc/polkit-1/localauthority/50-local.d/. -Compatibility with this older format is provided by polkit-pkla-compat. As an -example, this gives the user fred full management access: -

    -
    [Allow fred libvirt management permissions]
-Identity=3Dunix-user:fred
-Action=3Dorg.libvirt.unix.manage
-ResultAny=3Dyes
-ResultInactive=3Dyes
-ResultActive=3Dyes
    -

    SASL pluggable authentication

    - -

    -Libvirt integrates with the cyrus-sasl library to provide a pluggable auth= entication -system using the SASL protocol. SASL can be used in combination with libvi= rtd's TLS -or TCP socket listeners. When used with the TCP listener, the SASL mechani= sm is -rqeuired to provide session encryption in addition to authentication. Only= a very -few SASL mechanisms are able to do this, and of those that can do it, only= the -GSSAPI plugin is considered acceptably secure by modern standards: -

    - -
    -
    GSSAPI
    -
    This is the current default mechanism to use with libvir= td. - It uses the Kerberos v5 authentication protocol underneath, and as= suming - the Kerberos client/server are configured with modern ciphers (AES= ), - it provides strong session encryption capabilities.
    - -
    DIGEST-MD5
    -
    This was previously set as the default mechanism to use with lib= virtd. - It provides a simple username/password based authentication mechan= ism - that includes session encryption. - RFC 6331, howe= ver, - documents a number of serious security flaws with DIGEST-MD5 and a= s a - result marks it as OBSOLETE. Specific concerns are th= at - it is vulnerable to MITM attacks and the MD5 hash can be brute-for= ced - to reveal the password. A replacement is provided via the SCRAM me= chanism, - however, note that this does not provide encryption, so the SCRAM - mechanism can only be used on the libvirtd TLS listener. -
    - -
    PASSDSS-3DES-1
    -
    This provides a simple username/password based authentication - mechanism that includes session encryption. The current cyrus-sasl - implementation does not provide a way to validate the server's - public key identity, thus it is susceptible to a MITM attacker - impersonating the server. It is also not enabled in many OS - distros when building SASL libraries.
    - -
    KERBEROS_V4
    -
    This uses the obsolete Kerberos v4 protocol to provide both auth= entication - and session encryption. Kerberos v4 protocol has been obsolete sin= ce the - early 1990's and has known security vulnerabilities so this will n= ever be - used in practice.
    -
    - -

    - Other SASL mechanisms, not listed above, can only be used when the l= ibvirtd - TLS or UNIX socket listeners. -

    - -

    Username/password auth

    -

    -As noted above, the DIGEST-MD5 mechanism is considered obsolete and should -not be used anymore. To provide a simple username/password auth scheme on -the libvirt UNIX socket or TLS listeners, however, it is possible to use -the SCRAM mechanism. The auth_unix_ro, auth_unix_rw, -auth_tls config params in libvirt.conf can be us= ed -to turn on SASL auth in these listeners. -

    -

    -Since the libvirt SASL config file defaults to using GSSAPI (Kerberos), a -config change is required to enable plain password auth. This is done by -editing /etc/sasl2/libvirt.conf to set the mech_list -parameter to scram-sha-1. -

    -

    -Out of the box, no user accounts are defined, so no clients will be able t= o authenticate -on the TCP socket. Adding users and setting their passwords is done with t= he saslpasswd2 -command. When running this command it is important to tell it that the app= name is libvirt. -As an example, to add a user fred, run -

    - 
    -# saslpasswd2 -a libvirt fred
-Password: xxxxxx
-Again (for verification): xxxxxx
-
    -

    -To see a list of all accounts the sasldblistusers2 command ca= n be used. -This command expects to be given the path to the libvirt user database, wh= ich is kept -in /etc/libvirt/passwd.db -

    - 
    -# sasldblistusers2 -f /etc/libvirt/passwd.db
-fred@t60wlan.home.berrange.com: userPassword
-
    -

    -Finally, to disable a user's access, the saslpasswd2 command = can be used -again: -

    - 
    -# saslpasswd2 -a libvirt -d fred
-
    -

    GSSAPI/Kerberos auth

    -

    -The plain TCP listener of the libvirt daemon defaults to using SASL for au= thentication. -The libvirt SASL config also defaults to GSSAPI, so there is no need to ed= it the -SASL config when using GSSAPI. If the libvirtd TLS or UNIX listeners are u= sed, -then the Kerberos session encryption will be disabled since it is not requ= ired -in these scenarios - only the plain TCP listener needs encryption -

    -

    -Some operating systems do not install the SASL kerberos plugin by default.= It -may be necessary to install a sub-package such as cyrus-sasl-gssapi<= /code>. -To check whether the Kerberos plugin is installed run the pluginview= er -program and verify that gssapi is listed, e.g.: -

    - 
    -# pluginviewer
-...snip...
-Plugin "gssapiv2" [loaded],     API version: 4
-        SASL mechanism: GSSAPI, best SSF: 56
-        security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIA=
LS|MUTUAL_AUTH
-        features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
-
    -

    -Next it is necessary for the administrator of the Kerberos realm to -issue a principal for the libvirt server. There needs to be one -principal per host running the libvirt daemon. The principal should be -named libvirt/full.hostname@KERBEROS.REALM. This is -typically done by running the kadmin.local command on the -Kerberos server, though some Kerberos servers have alternate ways of -setting up service principals. Once created, the principal should be -exported to a keytab, copied to the host running the libvirt daemon -and placed in /etc/libvirt/krb5.tab -

    - 
    -# kadmin.local
-kadmin.local: add_principal libvirt/foo.example.com
-Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
-Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
-Principal "libvirt/foo.example.com@EXAMPLE.COM" created.
-
-kadmin.local:  ktadd -k /root/libvirt-foo-example.tab libvirt/foo.example.=
com@EXAMPLE.COM
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/=
libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-e=
xample.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-exam=
ple.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-f=
oo-example.tab.
-
-kadmin.local: quit
-
-# scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5=
.tab
-# rm /root/libvirt-foo-example.tab
-
    -

    -Any client application wishing to connect to a Kerberos enabled libvirt se= rver -merely needs to run kinit to gain a user principal. This may = well -be done automatically when a user logs into a desktop session, if PAM is s= et up -to authenticate against Kerberos. -

    - - diff --git a/docs/auth.rst b/docs/auth.rst new file mode 100644 index 0000000000..26fa6c950c --- /dev/null +++ b/docs/auth.rst @@ -0,0 +1,343 @@ +=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 +Connection authentication +=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 + +When connecting to libvirt, some connections may require client +authentication before allowing use of the APIs. The set of possible +authentication mechanisms is administrator controlled, independent of +applications using libvirt. Once authenticated, libvirt can apply fine +grained `access control `__ to the operations performed by a +client. + +.. contents:: + +Client configuration +-------------------- + +When connecting to a remote hypervisor which requires authentication, +most libvirt applications will prompt the user for the credentials. It +is also possible to provide a client configuration file containing all +the authentication credentials, avoiding any interaction. Libvirt will +look for the authentication file using the following sequence: + +#. The file path specified by the $LIBVIRT_AUTH_FILE environment + variable. +#. The file path specified by the "authfile=3D/some/file" URI query + parameter +#. The file $XDG_CONFIG_HOME/libvirt/auth.conf +#. The file /etc/libvirt/auth.conf + +The auth configuration file uses the traditional ``".ini"`` style +syntax. There are two types of groups that can be present in the config. +First there are one or more **credential** sets, which provide the +actual authentication credentials. The keys within the group may be: + +- ``username``: the user login name to act as. This is relevant for + ESX, Xen, HyperV and SSH, but probably not the one you want to + libvirtd with SASL. +- ``authname``: the name to authorize as. This is what is commonly + required for libvirtd with SASL. +- ``password``: the secret password +- ``realm``: the domain realm for SASL, mostly unused + +Each set of credentials has a name, which is part of the group entry +name. Overall the syntax is + +:: + + [credentials-$NAME] + credname1=3Dvalue1 + credname2=3Dvalue2 + +For example, to define two sets of credentials used for production and +test machines, using libvirtd, and a further ESX server for dev: + +:: + + [credentials-test] + authname=3Dfred + password=3D123456 + + [credentials-prod] + authname=3Dbar + password=3Dletmein + + [credentials-dev] + username=3Djoe + password=3Dhello + + [credentials-defgrp] + username=3Ddefuser + password=3Ddefpw + +The second set of groups provide mappings of credentials to specific +machine services. The config file group names compromise the service +type and host: + +:: + + [auth-$SERVICE-$HOSTNAME] + credentials=3D$CREDENTIALS + +For example, following the previous example, here is how to map some +machines. For convenience libvirt supports a default mapping of +credentials to machines: + +:: + + [auth-libvirt-test1.example.com] + credentials=3Dtest + + [auth-libvirt-test2.example.com] + credentials=3Dtest + + [auth-libvirt-demo3.example.com] + credentials=3Dtest + + [auth-libvirt-prod1.example.com] + credentials=3Dprod + + [auth-libvirt-default] + credentials=3Ddefgrp + + [auth-esx-dev1.example.com] + credentials=3Ddev + + [auth-esx-default] + credentials=3Ddefgrp + +The following service types are known to libvirt: + +- ``esx`` - used for connections to an ESX or VirtualCenter server +- ``hyperv`` - used for connections to an HyperV server +- ``libvirt`` - used for connections to a libvirtd server, which is + configured with SASL auth +- ``ssh`` - used for connections to a remote QEMU driver over SSH + +Applications using libvirt are free to use this same configuration file +for storing other credentials. For example, it can be used to storage +VNC or SPICE login credentials + +Server configuration +-------------------- + +The libvirt daemon allows the administrator to choose the authentication +mechanisms used for client connections on each network socket +independently. This is primarily controlled via the libvirt daemon +master config file in ``/etc/libvirt/libvirtd.conf``. Each of the +libvirt sockets can have its authentication mechanism configured +independently. There is currently a choice of ``none``, ``polkit``, and +``sasl``. The SASL scheme can be further configured to choose between a +large number of different mechanisms. + +UNIX socket permissions/group +----------------------------- + +If libvirt does not contain support for PolicyKit, then access control +for the UNIX domain socket is done using traditional file user/group +ownership and permissions. There are 2 sockets, one for full read-write +access, the other for read-only access. The RW socket will be restricted +(mode 0700) to only allow the ``root`` user to connect. The read-only +socket will be open access (mode 0777) to allow any user to connect. + +To allow non-root users greater access, the ``libvirtd.conf`` file can +be edited to change the permissions via the ``unix_sock_rw_perms``, +config parameter and to set a user group via the ``unix_sock_group`` +parameter. For example, setting the former to mode ``0770`` and the +latter ``wheel`` would let any user in the wheel group connect to the +libvirt daemon. + +UNIX socket PolicyKit auth +-------------------------- + +If libvirt contains support for PolicyKit, then access control options +are more advanced. The ``auth_unix_rw`` parameter will default to +``polkit``, and the file permissions will default to ``0777`` even on +the RW socket. Upon connecting to the socket, the client application +will be required to identify itself with PolicyKit. The default policy +for the RW daemon socket will require any application running in the +current desktop session to authenticate using the user's password. This +is akin to ``sudo`` auth, but does not require that the client +application ultimately run as root. Default policy will still allow any +application to connect to the RO socket. + +The default policy can be overridden by creating a new policy file in +the ``/etc/polkit-1/rules.d`` directory. Information on the options +available can be found by reading the ``polkit(8)`` man page. The two +libvirt actions are named ``org.libvirt.unix.manage`` for full +management access, and ``org.libvirt.unix.monitor`` for read-only +access. + +As an example, creating +``/etc/polkit-1/rules.d/80-libvirt-manage.rules`` with the following +gives the user ``fred`` full management access when accessing from an +active local session: + +:: + + polkit.addRule(function(action, subject) { + if (action.id =3D=3D "org.libvirt.unix.manage" && + subject.local && subject.active && subject.user =3D=3D "fred") { + return polkit.Result.YES; + } + }); + +Older versions of PolicyKit used policy files ending with .pkla in the +local override directory ``/etc/polkit-1/localauthority/50-local.d/``. +Compatibility with this older format is provided by +`polkit-pkla-compat `__. As an +example, this gives the user ``fred`` full management access: + +:: + + [Allow fred libvirt management permissions] + Identity=3Dunix-user:fred + Action=3Dorg.libvirt.unix.manage + ResultAny=3Dyes + ResultInactive=3Dyes + ResultActive=3Dyes + +SASL pluggable authentication +----------------------------- + +Libvirt integrates with the cyrus-sasl library to provide a pluggable +authentication system using the SASL protocol. SASL can be used in +combination with libvirtd's TLS or TCP socket listeners. When used with +the TCP listener, the SASL mechanism is rqeuired to provide session +encryption in addition to authentication. Only a very few SASL +mechanisms are able to do this, and of those that can do it, only the +GSSAPI plugin is considered acceptably secure by modern standards: + +GSSAPI + **This is the current default mechanism to use with libvirtd**. It + uses the Kerberos v5 authentication protocol underneath, and assuming + the Kerberos client/server are configured with modern ciphers (AES), + it provides strong session encryption capabilities. +DIGEST-MD5 + This was previously set as the default mechanism to use with + libvirtd. It provides a simple username/password based authentication + mechanism that includes session encryption. `RFC + 6331 `__, however, documents a + number of serious security flaws with DIGEST-MD5 and as a result + marks it as ``OBSOLETE``. Specific concerns are that it is vulnerable + to MITM attacks and the MD5 hash can be brute-forced to reveal the + password. A replacement is provided via the SCRAM mechanism, however, + note that this does not provide encryption, so the SCRAM mechanism + can only be used on the libvirtd TLS listener. +PASSDSS-3DES-1 + This provides a simple username/password based authentication + mechanism that includes session encryption. The current cyrus-sasl + implementation does not provide a way to validate the server's public + key identity, thus it is susceptible to a MITM attacker impersonating + the server. It is also not enabled in many OS distros when building + SASL libraries. +KERBEROS_V4 + This uses the obsolete Kerberos v4 protocol to provide both + authentication and session encryption. Kerberos v4 protocol has been + obsolete since the early 1990's and has known security + vulnerabilities so this will never be used in practice. + +Other SASL mechanisms, not listed above, can only be used when the +libvirtd TLS or UNIX socket listeners. + +Username/password auth +~~~~~~~~~~~~~~~~~~~~~~ + +As noted above, the DIGEST-MD5 mechanism is considered obsolete and +should not be used anymore. To provide a simple username/password auth +scheme on the libvirt UNIX socket or TLS listeners, however, it is +possible to use the SCRAM mechanism. The ``auth_unix_ro``, +``auth_unix_rw``, ``auth_tls`` config params in ``libvirt.conf`` can be +used to turn on SASL auth in these listeners. + +Since the libvirt SASL config file defaults to using GSSAPI (Kerberos), +a config change is required to enable plain password auth. This is done +by editing ``/etc/sasl2/libvirt.conf`` to set the ``mech_list`` +parameter to ``scram-sha-1``. + +Out of the box, no user accounts are defined, so no clients will be able +to authenticate on the TCP socket. Adding users and setting their +passwords is done with the ``saslpasswd2`` command. When running this +command it is important to tell it that the appname is ``libvirt``. As +an example, to add a user ``fred``, run + +:: + + # saslpasswd2 -a libvirt fred + Password: xxxxxx + Again (for verification): xxxxxx + +To see a list of all accounts the ``sasldblistusers2`` command can be +used. This command expects to be given the path to the libvirt user +database, which is kept in ``/etc/libvirt/passwd.db`` + +:: + + # sasldblistusers2 -f /etc/libvirt/passwd.db + fred@t60wlan.home.berrange.com: userPassword + +Finally, to disable a user's access, the ``saslpasswd2`` command can be +used again: + +:: + + # saslpasswd2 -a libvirt -d fred + +GSSAPI/Kerberos auth +~~~~~~~~~~~~~~~~~~~~ + +The plain TCP listener of the libvirt daemon defaults to using SASL for +authentication. The libvirt SASL config also defaults to GSSAPI, so +there is no need to edit the SASL config when using GSSAPI. If the +libvirtd TLS or UNIX listeners are used, then the Kerberos session +encryption will be disabled since it is not required in these scenarios +- only the plain TCP listener needs encryption + +Some operating systems do not install the SASL kerberos plugin by +default. It may be necessary to install a sub-package such as +``cyrus-sasl-gssapi``. To check whether the Kerberos plugin is installed +run the ``pluginviewer`` program and verify that ``gssapi`` is listed, +e.g.: + +:: + + # pluginviewer + ...snip... + Plugin "gssapiv2" [loaded], API version: 4 + SASL mechanism: GSSAPI, best SSF: 56 + security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDEN= TIALS|MUTUAL_AUTH + features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQ= DN + +Next it is necessary for the administrator of the Kerberos realm to +issue a principal for the libvirt server. There needs to be one +principal per host running the libvirt daemon. The principal should be +named ``libvirt/full.hostname@KERBEROS.REALM``. This is typically done +by running the ``kadmin.local`` command on the Kerberos server, though +some Kerberos servers have alternate ways of setting up service +principals. Once created, the principal should be exported to a keytab, +copied to the host running the libvirt daemon and placed in +``/etc/libvirt/krb5.tab`` + +:: + + # kadmin.local + kadmin.local: add_principal libvirt/foo.example.com + Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": + Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": + Principal "libvirt/foo.example.com@EXAMPLE.COM" created. + + kadmin.local: ktadd -k /root/libvirt-foo-example.tab libvirt/foo.examp= le.com@EXAMPLE.COM + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/ro= ot/libvirt-foo-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-fo= o-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-e= xample.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvir= t-foo-example.tab. + + kadmin.local: quit + + # scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/k= rb5.tab + # rm /root/libvirt-foo-example.tab + +Any client application wishing to connect to a Kerberos enabled libvirt +server merely needs to run ``kinit`` to gain a user principal. This may +well be done automatically when a user logs into a desktop session, if +PAM is set up to authenticate against Kerberos. diff --git a/docs/kbase/locking-sanlock.rst b/docs/kbase/locking-sanlock.rst index fece9df80e..bd85c2e36e 100644 --- a/docs/kbase/locking-sanlock.rst +++ b/docs/kbase/locking-sanlock.rst @@ -180,7 +180,7 @@ helper binary will connect to libvirtd and thus it may = need to authenticate if libvirtd was configured to require that on the read-write UNIX socket. To provide the appropriate credentials to sanlock_helper, a `client authentication -file `__ needs to contain something like +file <../auth.html#client-configuration>`__ needs to contain something like the following: =20 :: diff --git a/docs/meson.build b/docs/meson.build index fdaf369271..ab0932ceb4 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -31,7 +31,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'auth', 'bugs', 'cgroups', 'contact', @@ -103,6 +102,7 @@ docs_rst_files =3D [ 'api', 'apps', 'auditlog', + 'auth', 'bindings', 'best-practices', 'ci', --=20 2.29.2