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.
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 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 passwordrealm: the domain realm for SASL, mostly
unusedEach 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
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
libvirt - used for connections to a libvirtd
server, which is configured with SASL authssh - used for connections to a Phyp server
over SSHesx - used for connections to an ESX or
VirtualCenter serverxen - used for connections to a Xen Enterprise
sever using XenAPIApplications 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
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.
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.
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. 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
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:
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.
Other SASL mechanisms, not listed above, can only be used when the libvirtd TLS or UNIX socket listeners.
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 rquired to enable plain password auth. This is done by
editting /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
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,eg:
# 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 setup
to authenticate against Kerberos.