Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
docs/auth.html.in | 368 ----------------------------------------------
docs/auth.rst | 350 +++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 351 insertions(+), 369 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 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Connection authentication</h1>
- <p>
- 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 <a href="acl.html">access control</a> to the operations
- performed by a client.
- </p>
-
- <ul id="toc"></ul>
-
- <h2><a id="Auth_client_config">Client configuration</a></h2>
-
- <p>
- 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:
- </p>
- <ol>
- <li>The file path specified by the $LIBVIRT_AUTH_FILE environment
- variable.</li>
- <li>The file path specified by the "authfile=/some/file" URI
- query parameter</li>
- <li>The file $XDG_CONFIG_HOME/libvirt/auth.conf</li>
- <li>The file /etc/libvirt/auth.conf</li>
- </ol>
-
- <p>
- The auth configuration file uses the traditional <code>".ini"</code>
- style syntax. There are two types of groups that can be present in
- the config. First there are one or more <strong>credential</strong>
- sets, which provide the actual authentication credentials. The keys
- within the group may be:
- </p>
-
- <ul>
- <li><code>username</code>: 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.</li>
- <li><code>authname</code>: the name to authorize as. This is
- what is commonly required for libvirtd with SASL.</li>
- <li><code>password</code>: the secret password</li>
- <li><code>realm</code>: the domain realm for SASL, mostly
- unused</li>
- </ul>
-
- <p>
- Each set of credentials has a name, which is part of the group
- entry name. Overall the syntax is
- </p>
-
- <pre>
-[credentials-$NAME]
-credname1=value1
-credname2=value2</pre>
-
- <p>
- For example, to define two sets of credentials used for production
- and test machines, using libvirtd, and a further ESX server for dev:
- </p>
-<pre>
-[credentials-test]
-authname=fred
-password=123456
-
-[credentials-prod]
-authname=bar
-password=letmein
-
-[credentials-dev]
-username=joe
-password=hello
-
-[credentials-defgrp]
-username=defuser
-password=defpw</pre>
-
- <p>
- The second set of groups provide mappings of credentials to
- specific machine services. The config file group names compromise
- the service type and host:
- </p>
-
- <pre>
-[auth-$SERVICE-$HOSTNAME]
-credentials=$CREDENTIALS</pre>
-
- <p>
- For example, following the previous example, here is how to
- map some machines. For convenience libvirt supports a default
- mapping of credentials to machines:
- </p>
-
- <pre>
-[auth-libvirt-test1.example.com]
-credentials=test
-
-[auth-libvirt-test2.example.com]
-credentials=test
-
-[auth-libvirt-demo3.example.com]
-credentials=test
-
-[auth-libvirt-prod1.example.com]
-credentials=prod
-
-[auth-libvirt-default]
-credentials=defgrp
-
-[auth-esx-dev1.example.com]
-credentials=dev
-
-[auth-esx-default]
-credentials=defgrp</pre>
-
-
- <p>
- The following service types are known to libvirt:
- </p>
-
- <ul>
- <li><code>esx</code> - used for connections to an ESX or
- VirtualCenter server</li>
- <li><code>hyperv</code> - used for connections to an HyperV
- server</li>
- <li><code>libvirt</code> - used for connections to a libvirtd
- server, which is configured with SASL auth</li>
- <li><code>ssh</code> - used for connections to a remote QEMU driver
- over SSH</li>
- </ul>
-
- <p>
- 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
- </p>
-
- <h2><a id="ACL_server_config">Server configuration</a></h2>
- <p>
-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
-<code>/etc/libvirt/libvirtd.conf</code>. Each of the libvirt sockets can
-have its authentication mechanism configured independently. There is
-currently a choice of <code>none</code>, <code>polkit</code>, and <code>sasl</code>.
-The SASL scheme can be further configured to choose between a large
-number of different mechanisms.
-</p>
- <h2><a id="ACL_server_unix_perms">UNIX socket permissions/group</a></h2>
- <p>
-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 <code>root</code> user to connect. The read-only socket will
-be open access (mode 0777) to allow any user to connect.
-</p>
- <p>
-To allow non-root users greater access, the <code>libvirtd.conf</code> file
-can be edited to change the permissions via the <code>unix_sock_rw_perms</code>,
-config parameter and to set a user group via the <code>unix_sock_group</code>
-parameter. For example, setting the former to mode <code>0770</code> and the
-latter <code>wheel</code> would let any user in the wheel group connect to
-the libvirt daemon.
-</p>
- <h2><a id="ACL_server_polkit">UNIX socket PolicyKit auth</a></h2>
- <p>
-If libvirt contains support for PolicyKit, then access control options are
-more advanced. The <code>auth_unix_rw</code> parameter will default to
-<code>polkit</code>, and the file permissions will default to <code>0777</code>
-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 <code>sudo</code>
-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.
-</p>
- <p>
-The default policy can be overridden by creating a new policy file in the
-<code>/etc/polkit-1/rules.d</code> directory. Information on the options
-available can be found by reading the <code>polkit(8)</code> man page. The
-two libvirt actions are named <code>org.libvirt.unix.manage</code> for full
-management access, and <code>org.libvirt.unix.monitor</code> for read-only
-access.
-</p>
- <p>
-As an example, creating <code>/etc/polkit-1/rules.d/80-libvirt-manage.rules</code>
-with the following gives the user <code>fred</code> full management access
-when accessing from an active local session:
- </p>
-<pre>polkit.addRule(function(action, subject) {
- if (action.id == "org.libvirt.unix.manage" &&
- subject.local && subject.active && subject.user == "fred") {
- return polkit.Result.YES;
- }
-});</pre>
- <p>
-Older versions of PolicyKit used policy files ending with .pkla in the
-local override directory <code>/etc/polkit-1/localauthority/50-local.d/</code>.
-Compatibility with this older format is provided by <a
-href="https://pagure.io/polkit-pkla-compat">polkit-pkla-compat</a>. As an
-example, this gives the user <code>fred</code> full management access:
- </p>
-<pre>[Allow fred libvirt management permissions]
-Identity=unix-user:fred
-Action=org.libvirt.unix.manage
-ResultAny=yes
-ResultInactive=yes
-ResultActive=yes</pre>
- <h2><a id="ACL_server_sasl">SASL pluggable authentication</a></h2>
-
- <p>
-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:
- </p>
-
- <dl>
- <dt>GSSAPI</dt>
- <dd><strong>This is the current default mechanism to use with libvirtd</strong>.
- 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.</dd>
-
- <dt>DIGEST-MD5</dt>
- <dd>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.
- <a href="https://tools.ietf.org/html/rfc6331">RFC 6331</a>, however,
- documents a number of serious security flaws with DIGEST-MD5 and as a
- result marks it as <code>OBSOLETE</code>. 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.
- </dd>
-
- <dt>PASSDSS-3DES-1</dt>
- <dd>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.</dd>
-
- <dt>KERBEROS_V4</dt>
- <dd>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.</dd>
- </dl>
-
- <p>
- Other SASL mechanisms, not listed above, can only be used when the libvirtd
- TLS or UNIX socket listeners.
- </p>
-
- <h3><a id="ACL_server_username">Username/password auth</a></h3>
- <p>
-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 <code>auth_unix_ro</code>, <code>auth_unix_rw</code>,
-<code>auth_tls</code> config params in <code>libvirt.conf</code> can be used
-to turn on SASL auth in these listeners.
- </p>
- <p>
-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 <code>/etc/sasl2/libvirt.conf</code> to set the <code>mech_list</code>
-parameter to <code>scram-sha-1</code>.
- </p>
- <p>
-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 <code>saslpasswd2</code>
-command. When running this command it is important to tell it that the appname is <code>libvirt</code>.
-As an example, to add a user <code>fred</code>, run
-</p>
- <pre>
-# saslpasswd2 -a libvirt fred
-Password: xxxxxx
-Again (for verification): xxxxxx
-</pre>
- <p>
-To see a list of all accounts the <code>sasldblistusers2</code> command can be used.
-This command expects to be given the path to the libvirt user database, which is kept
-in <code>/etc/libvirt/passwd.db</code>
-</p>
- <pre>
-# sasldblistusers2 -f /etc/libvirt/passwd.db
-fred@t60wlan.home.berrange.com: userPassword
-</pre>
- <p>
-Finally, to disable a user's access, the <code>saslpasswd2</code> command can be used
-again:
-</p>
- <pre>
-# saslpasswd2 -a libvirt -d fred
-</pre>
- <h3><a id="ACL_server_kerberos">GSSAPI/Kerberos auth</a></h3>
- <p>
-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
-</p>
- <p>
-Some operating systems do not install the SASL kerberos plugin by default. It
-may be necessary to install a sub-package such as <code>cyrus-sasl-gssapi</code>.
-To check whether the Kerberos plugin is installed run the <code>pluginviewer</code>
-program and verify that <code>gssapi</code> is listed, e.g.:
-</p>
- <pre>
-# pluginviewer
-...snip...
-Plugin "gssapiv2" [loaded], API version: 4
- SASL mechanism: GSSAPI, best SSF: 56
- security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH
- features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
-</pre>
- <p>
-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 <code>libvirt/full.hostname@KERBEROS.REALM</code>. This is
-typically done by running the <code>kadmin.local</code> 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 <code>/etc/libvirt/krb5.tab</code>
-</p>
- <pre>
-# 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, encryption 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, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-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
-</pre>
- <p>
-Any client application wishing to connect to a Kerberos enabled libvirt server
-merely needs to run <code>kinit</code> 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.
-</p>
- </body>
-</html>
diff --git a/docs/auth.rst b/docs/auth.rst
new file mode 100644
index 0000000000..506e6b5c13
--- /dev/null
+++ b/docs/auth.rst
@@ -0,0 +1,350 @@
+=========================
+Connection authentication
+=========================
+
+.. contents::
+
+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 <acl.html>`_ to the operations
+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:
+
+* The file path specified by the ``$LIBVIRT_AUTH_FILE`` environment
+ variable.
+* The file path specified by the ``authfile=/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=value1
+ credname2=value2
+
+
+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=fred
+ password=123456
+
+ [credentials-prod]
+ authname=bar
+ password=letmein
+
+ [credentials-dev]
+ username=joe
+ password=hello
+
+ [credentials-defgrp]
+ username=defuser
+ password=defpw
+
+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=$CREDENTIALS</pre>
+
+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=test
+
+ [auth-libvirt-test2.example.com]
+ credentials=test
+
+ [auth-libvirt-demo3.example.com]
+ credentials=test
+
+ [auth-libvirt-prod1.example.com]
+ credentials=prod
+
+ [auth-libvirt-default]
+ credentials=defgrp
+
+ [auth-esx-dev1.example.com]
+ credentials=dev
+
+ [auth-esx-default]
+ credentials=defgrp
+
+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 == "org.libvirt.unix.manage" &&
+ subject.local && subject.active &&; subject.user == "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 <https://pagure.io/polkit-pkla-compat>`_. As an
+example, this gives the user ``fred`` full management access:
+
+::
+
+ [Allow fred libvirt management permissions]
+ Identity=unix-user:fred
+ Action=org.libvirt.unix.manage
+ ResultAny=yes
+ ResultInactive=yes
+ ResultActive=yes
+
+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 required 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` <https://tools.ietf.org/html/rfc6331>, 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_CREDENTIALS|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, encryption 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, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
+ Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
+ Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-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 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/meson.build b/docs/meson.build
index 5536005125..cb4ab676d6 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -38,7 +38,6 @@ docs_html_in_files = [
'apps',
'architecture',
'auditlog',
- 'auth',
'bindings',
'bugs',
'cgroups',
@@ -107,6 +106,7 @@ docs_html_in_files = [
docs_rst_files = [
'advanced-tests',
+ 'auth',
'best-practices',
'ci',
'coding-style',
--
2.29.2
On Thu, Mar 04, 2021 at 06:10:12PM +0000, Daniel P. Berrangé wrote:
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
> docs/auth.html.in | 368 ----------------------------------------------
> docs/auth.rst | 350 +++++++++++++++++++++++++++++++++++++++++++
> docs/meson.build | 2 +-
> 3 files changed, 351 insertions(+), 369 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 @@
> -<?xml version="1.0" encoding="UTF-8"?>
> -<!DOCTYPE html>
> -<html xmlns="http://www.w3.org/1999/xhtml">
> - <body>
> - <h1>Connection authentication</h1>
> - <p>
> - 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 <a href="acl.html">access control</a> to the operations
> - performed by a client.
> - </p>
> -
> - <ul id="toc"></ul>
> -
> - <h2><a id="Auth_client_config">Client configuration</a></h2>
> -
> - <p>
> - 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:
> - </p>
> - <ol>
> - <li>The file path specified by the $LIBVIRT_AUTH_FILE environment
> - variable.</li>
> - <li>The file path specified by the "authfile=/some/file" URI
> - query parameter</li>
> - <li>The file $XDG_CONFIG_HOME/libvirt/auth.conf</li>
> - <li>The file /etc/libvirt/auth.conf</li>
> - </ol>
> -
> - <p>
> - The auth configuration file uses the traditional <code>".ini"</code>
> - style syntax. There are two types of groups that can be present in
> - the config. First there are one or more <strong>credential</strong>
> - sets, which provide the actual authentication credentials. The keys
> - within the group may be:
> - </p>
> -
> - <ul>
> - <li><code>username</code>: 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.</li>
> - <li><code>authname</code>: the name to authorize as. This is
> - what is commonly required for libvirtd with SASL.</li>
> - <li><code>password</code>: the secret password</li>
> - <li><code>realm</code>: the domain realm for SASL, mostly
> - unused</li>
> - </ul>
> -
> - <p>
> - Each set of credentials has a name, which is part of the group
> - entry name. Overall the syntax is
> - </p>
> -
> - <pre>
> -[credentials-$NAME]
> -credname1=value1
> -credname2=value2</pre>
> -
> - <p>
> - For example, to define two sets of credentials used for production
> - and test machines, using libvirtd, and a further ESX server for dev:
> - </p>
> -<pre>
> -[credentials-test]
> -authname=fred
> -password=123456
> -
> -[credentials-prod]
> -authname=bar
> -password=letmein
> -
> -[credentials-dev]
> -username=joe
> -password=hello
> -
> -[credentials-defgrp]
> -username=defuser
> -password=defpw</pre>
> -
> - <p>
> - The second set of groups provide mappings of credentials to
> - specific machine services. The config file group names compromise
> - the service type and host:
> - </p>
> -
> - <pre>
> -[auth-$SERVICE-$HOSTNAME]
> -credentials=$CREDENTIALS</pre>
> -
> - <p>
> - For example, following the previous example, here is how to
> - map some machines. For convenience libvirt supports a default
> - mapping of credentials to machines:
> - </p>
> -
> - <pre>
> -[auth-libvirt-test1.example.com]
> -credentials=test
> -
> -[auth-libvirt-test2.example.com]
> -credentials=test
> -
> -[auth-libvirt-demo3.example.com]
> -credentials=test
> -
> -[auth-libvirt-prod1.example.com]
> -credentials=prod
> -
> -[auth-libvirt-default]
> -credentials=defgrp
> -
> -[auth-esx-dev1.example.com]
> -credentials=dev
> -
> -[auth-esx-default]
> -credentials=defgrp</pre>
> -
> -
> - <p>
> - The following service types are known to libvirt:
> - </p>
> -
> - <ul>
> - <li><code>esx</code> - used for connections to an ESX or
> - VirtualCenter server</li>
> - <li><code>hyperv</code> - used for connections to an HyperV
> - server</li>
> - <li><code>libvirt</code> - used for connections to a libvirtd
> - server, which is configured with SASL auth</li>
> - <li><code>ssh</code> - used for connections to a remote QEMU driver
> - over SSH</li>
> - </ul>
> -
> - <p>
> - 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
> - </p>
> -
> - <h2><a id="ACL_server_config">Server configuration</a></h2>
> - <p>
> -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
> -<code>/etc/libvirt/libvirtd.conf</code>. Each of the libvirt sockets can
> -have its authentication mechanism configured independently. There is
> -currently a choice of <code>none</code>, <code>polkit</code>, and <code>sasl</code>.
> -The SASL scheme can be further configured to choose between a large
> -number of different mechanisms.
> -</p>
> - <h2><a id="ACL_server_unix_perms">UNIX socket permissions/group</a></h2>
> - <p>
> -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 <code>root</code> user to connect. The read-only socket will
> -be open access (mode 0777) to allow any user to connect.
> -</p>
> - <p>
> -To allow non-root users greater access, the <code>libvirtd.conf</code> file
> -can be edited to change the permissions via the <code>unix_sock_rw_perms</code>,
> -config parameter and to set a user group via the <code>unix_sock_group</code>
> -parameter. For example, setting the former to mode <code>0770</code> and the
> -latter <code>wheel</code> would let any user in the wheel group connect to
> -the libvirt daemon.
> -</p>
> - <h2><a id="ACL_server_polkit">UNIX socket PolicyKit auth</a></h2>
> - <p>
> -If libvirt contains support for PolicyKit, then access control options are
> -more advanced. The <code>auth_unix_rw</code> parameter will default to
> -<code>polkit</code>, and the file permissions will default to <code>0777</code>
> -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 <code>sudo</code>
> -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.
> -</p>
> - <p>
> -The default policy can be overridden by creating a new policy file in the
> -<code>/etc/polkit-1/rules.d</code> directory. Information on the options
> -available can be found by reading the <code>polkit(8)</code> man page. The
> -two libvirt actions are named <code>org.libvirt.unix.manage</code> for full
> -management access, and <code>org.libvirt.unix.monitor</code> for read-only
> -access.
> -</p>
> - <p>
> -As an example, creating <code>/etc/polkit-1/rules.d/80-libvirt-manage.rules</code>
> -with the following gives the user <code>fred</code> full management access
> -when accessing from an active local session:
> - </p>
> -<pre>polkit.addRule(function(action, subject) {
> - if (action.id == "org.libvirt.unix.manage" &&
> - subject.local && subject.active && subject.user == "fred") {
> - return polkit.Result.YES;
> - }
> -});</pre>
> - <p>
> -Older versions of PolicyKit used policy files ending with .pkla in the
> -local override directory <code>/etc/polkit-1/localauthority/50-local.d/</code>.
> -Compatibility with this older format is provided by <a
> -href="https://pagure.io/polkit-pkla-compat">polkit-pkla-compat</a>. As an
> -example, this gives the user <code>fred</code> full management access:
> - </p>
> -<pre>[Allow fred libvirt management permissions]
> -Identity=unix-user:fred
> -Action=org.libvirt.unix.manage
> -ResultAny=yes
> -ResultInactive=yes
> -ResultActive=yes</pre>
> - <h2><a id="ACL_server_sasl">SASL pluggable authentication</a></h2>
> -
> - <p>
> -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:
> - </p>
> -
> - <dl>
> - <dt>GSSAPI</dt>
> - <dd><strong>This is the current default mechanism to use with libvirtd</strong>.
> - 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.</dd>
> -
> - <dt>DIGEST-MD5</dt>
> - <dd>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.
> - <a href="https://tools.ietf.org/html/rfc6331">RFC 6331</a>, however,
> - documents a number of serious security flaws with DIGEST-MD5 and as a
> - result marks it as <code>OBSOLETE</code>. 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.
> - </dd>
> -
> - <dt>PASSDSS-3DES-1</dt>
> - <dd>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.</dd>
> -
> - <dt>KERBEROS_V4</dt>
> - <dd>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.</dd>
> - </dl>
> -
> - <p>
> - Other SASL mechanisms, not listed above, can only be used when the libvirtd
> - TLS or UNIX socket listeners.
> - </p>
> -
> - <h3><a id="ACL_server_username">Username/password auth</a></h3>
> - <p>
> -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 <code>auth_unix_ro</code>, <code>auth_unix_rw</code>,
> -<code>auth_tls</code> config params in <code>libvirt.conf</code> can be used
> -to turn on SASL auth in these listeners.
> - </p>
> - <p>
> -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 <code>/etc/sasl2/libvirt.conf</code> to set the <code>mech_list</code>
> -parameter to <code>scram-sha-1</code>.
> - </p>
> - <p>
> -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 <code>saslpasswd2</code>
> -command. When running this command it is important to tell it that the appname is <code>libvirt</code>.
> -As an example, to add a user <code>fred</code>, run
> -</p>
> - <pre>
> -# saslpasswd2 -a libvirt fred
> -Password: xxxxxx
> -Again (for verification): xxxxxx
> -</pre>
> - <p>
> -To see a list of all accounts the <code>sasldblistusers2</code> command can be used.
> -This command expects to be given the path to the libvirt user database, which is kept
> -in <code>/etc/libvirt/passwd.db</code>
> -</p>
> - <pre>
> -# sasldblistusers2 -f /etc/libvirt/passwd.db
> -fred@t60wlan.home.berrange.com: userPassword
> -</pre>
> - <p>
> -Finally, to disable a user's access, the <code>saslpasswd2</code> command can be used
> -again:
> -</p>
> - <pre>
> -# saslpasswd2 -a libvirt -d fred
> -</pre>
> - <h3><a id="ACL_server_kerberos">GSSAPI/Kerberos auth</a></h3>
> - <p>
> -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
> -</p>
> - <p>
> -Some operating systems do not install the SASL kerberos plugin by default. It
> -may be necessary to install a sub-package such as <code>cyrus-sasl-gssapi</code>.
> -To check whether the Kerberos plugin is installed run the <code>pluginviewer</code>
> -program and verify that <code>gssapi</code> is listed, e.g.:
> -</p>
> - <pre>
> -# pluginviewer
> -...snip...
> -Plugin "gssapiv2" [loaded], API version: 4
> - SASL mechanism: GSSAPI, best SSF: 56
> - security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH
> - features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
> -</pre>
> - <p>
> -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 <code>libvirt/full.hostname@KERBEROS.REALM</code>. This is
> -typically done by running the <code>kadmin.local</code> 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 <code>/etc/libvirt/krb5.tab</code>
> -</p>
> - <pre>
> -# 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, encryption 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, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
> -Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
> -Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-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
> -</pre>
> - <p>
> -Any client application wishing to connect to a Kerberos enabled libvirt server
> -merely needs to run <code>kinit</code> 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.
> -</p>
> - </body>
> -</html>
> diff --git a/docs/auth.rst b/docs/auth.rst
> new file mode 100644
> index 0000000000..506e6b5c13
> --- /dev/null
> +++ b/docs/auth.rst
> @@ -0,0 +1,350 @@
> +=========================
> +Connection authentication
> +=========================
> +
> +.. contents::
> +
> +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 <acl.html>`_ to the operations
> +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:
> +
> +* The file path specified by the ``$LIBVIRT_AUTH_FILE`` environment
> + variable.
> +* The file path specified by the ``authfile=/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.
s/want to/want for
...
> +For example, to define two sets of credentials used for production
> +and test machines, using libvirtd, and a further ESX server for dev:
s/dev/development/
...
> + polkit.addRule(function(action, subject) {
> + if (action.id == "org.libvirt.unix.manage" &&
> + subject.local && subject.active &&; subject.user == "fred") {
s/amp;//g
s/; subject/ subject/
...
> +
> +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
s/libvirt.conf/libvirtd.conf/
All of the nits are pre-existing...please fix them in a trivial patch before
pushing.
Reviewed-by: Erik Skultety <eskultet@redhat.com>
© 2016 - 2026 Red Hat, Inc.