mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-10 07:20:02 +00:00
a4fb88b5c9
* src/util/virauth.c, src/util/virauth.h: Add virAuthGetConfigFilePath * include/libvirt/virterror.h, src/util/virterror.c: Add VIR_FROM_AUTH error domain Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
289 lines
12 KiB
XML
289 lines
12 KiB
XML
<?xml version="1.0"?>
|
|
<html>
|
|
<body>
|
|
<h1 >Authentication & access control</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.
|
|
</p>
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
<h2><a name="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 $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</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
|
|
list some 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-esx-dev1.example.com]
|
|
credentials=dev</pre>
|
|
|
|
<p>
|
|
The following service types are known to libvirt
|
|
</p>
|
|
|
|
<ol>
|
|
<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 Phyp server
|
|
over SSH</li>
|
|
<li><code>esx</code> - used for connections to an ESX or
|
|
VirtualCenter server</li>
|
|
<li><code>xen</code> - used for connections to a Xen Enterprise
|
|
sever using XenAPI</li>
|
|
</ol>
|
|
|
|
<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 name="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 name="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 name="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>unix_sock_auth</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
|
|
local override directory <code>/etc/polkit-1/localauthority/50-local.d/</code>.
|
|
Policy files should have a unique name ending with .pkla. Using reverse DNS
|
|
naming works well. Information on the options available can be found by
|
|
reading the pklocalauthority man page. The two libvirt daemon actions
|
|
available 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, 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>
|
|
<p>
|
|
Further examples of PolicyKit setup can be found on the
|
|
<a href="http://wiki.libvirt.org/page/SSHPolicyKitSetup">wiki page</a>.
|
|
</p>
|
|
<h2><a name="ACL_server_username">Username/password auth</a></h2>
|
|
<p>
|
|
The plain TCP socket of the libvirt daemon defaults to using SASL for authentication.
|
|
The SASL mechanism configured by default is DIGEST-MD5, which provides a basic
|
|
username+password style authentication. It also provides for encryption of the data
|
|
stream, so the security of the plain TCP socket is on a par with that of the TLS
|
|
socket. If desired the UNIX socket and TLS socket can also have SASL enabled by
|
|
setting the <code>auth_unix_ro</code>, <code>auth_unix_rw</code>, <code>auth_tls</code>
|
|
config params in <code>libvirt.conf</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>
|
|
<h2><a name="ACL_server_kerberos">Kerberos auth</a></h2>
|
|
<p>
|
|
The plain TCP socket of the libvirt daemon defaults to using SASL for authentication.
|
|
The SASL mechanism configured by default is DIGEST-MD5, which provides a basic
|
|
username+password style authentication. To enable Kerberos single-sign-on instead,
|
|
the libvirt SASL configuration file must be changed. This is <code>/etc/sasl2/libvirt.conf</code>.
|
|
The <code>mech_list</code> parameter must first be changed to <code>gssapi</code>
|
|
instead of the default <code>digest-md5</code>. If SASL is enabled on the UNIX
|
|
and/or TLS sockets, Kerberos will also be used for them. Like DIGEST-MD5, the Kerberos
|
|
mechanism provides data encryption of the session.
|
|
</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,eg:
|
|
</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 principle
|
|
for the libvirt server. There needs to be one principle per host running the libvirt
|
|
daemon. The principle 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 principles.
|
|
Once created, the principle 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 principle. This may well
|
|
be done automatically when a user logs into a desktop session, if PAM is setup
|
|
to authenticate against Kerberos.
|
|
</p>
|
|
</body>
|
|
</html>
|