mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-26 03:21:44 +03:00
1354b603ae
There are a 58 docs files, so adding an autogenerated Table Of Contents to them all will take some time. This is the first piece of the work done.
173 lines
8.4 KiB
XML
173 lines
8.4 KiB
XML
<?xml version="1.0"?>
|
|
<html>
|
|
<body>
|
|
<h1 >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="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>
|