docs/auth.html.in

   1 <?xml version="1.0"?>
   2 <html>
   3   <body>
   4     <h1 >Access control</h1>
   5     <p>
   6       When connecting to libvirt, some connections may require client
   7       authentication before allowing use of the APIs. The set of possible
   8       authentication mechanisms is administrator controlled, independent
   9       of applications using libvirt.
  10     </p>
  11
  12     <ul id="toc"></ul>
  13
  14     <h2><a name="ACL_server_config">Server configuration</a></h2>
  15     <p>
  16 The libvirt daemon allows the administrator to choose the authentication
  17 mechanisms used for client connections on each network socket independently.
  18 This is primarily controlled via the libvirt daemon master config file in
  19 <code>/etc/libvirt/libvirtd.conf</code>. Each of the libvirt sockets can
  20 have its authentication mechanism configured independently. There is
  21 currently a choice of <code>none</code>, <code>polkit</code>, and <code>sasl</code>.
  22 The SASL scheme can be further configured to choose between a large
  23 number of different mechanisms.
  24 </p>
  25     <h2><a name="ACL_server_unix_perms">UNIX socket permissions/group</a></h2>
  26     <p>
  27 If libvirt does not contain support for PolicyKit, then access control for
  28 the UNIX domain socket is done using traditional file user/group ownership
  29 and permissions. There are 2 sockets, one for full read-write access, the
  30 other for read-only access. The RW socket will be restricted (mode 0700) to
  31 only allow the <code>root</code> user to connect. The read-only socket will
  32 be open access (mode 0777) to allow any user to connect.
  33 </p>
  34     <p>
  35 To allow non-root users greater access, the <code>libvirtd.conf</code> file
  36 can be edited to change the permissions via the <code>unix_sock_rw_perms</code>,
  37 config parameter and to set a user group via the <code>unix_sock_group</code>
  38 parameter. For example, setting the former to mode <code>0770</code> and the
  39 latter <code>wheel</code> would let any user in the wheel group connect to
  40 the libvirt daemon.
  41 </p>
  42     <h2><a name="ACL_server_polkit">UNIX socket PolicyKit auth</a></h2>
  43     <p>
  44 If libvirt contains support for PolicyKit, then access control options are
  45 more advanced. The <code>unix_sock_auth</code> parameter will default to
  46 <code>polkit</code>, and the file permissions will default to <code>0777</code>
  47 even on the RW socket. Upon connecting to the socket, the client application
  48 will be required to identify itself with PolicyKit. The default policy for the
  49 RW daemon socket will require any application running in the current desktop
  50 session to authenticate using the user's password. This is akin to <code>sudo</code>
  51 auth, but does not require that the client application ultimately run as root.
  52 Default policy will still allow any application to connect to the RO socket.
  53 </p>
  54     <p>
  55 The default policy can be overridden by creating a new policy file in the
  56 local override directory <code>/etc/polkit-1/localauthority/50-local.d/</code>.
  57 Policy files should have a unique name ending with .pkla.  Using reverse DNS
  58 naming works well. Information on the options available can be found by
  59 reading the pklocalauthority man page. The two libvirt daemon actions
  60 available are named <code>org.libvirt.unix.manage</code> for full management
  61 access, and <code>org.libvirt.unix.monitor</code> for read-only access.
  62     </p>
  63     <p>
  64 As an example, this gives the user <code>fred</code> full management access:
  65     </p>
  66 <pre>[Allow fred libvirt management permissions]
  67 Identity=unix-user:fred
  68 Action=org.libvirt.unix.manage
  69 ResultAny=yes
  70 ResultInactive=yes
  71 ResultActive=yes</pre>
  72     <p>
  73 Further examples of PolicyKit setup can be found on the
  74 <a href="http://wiki.libvirt.org/page/SSHPolicyKitSetup">wiki page</a>.
  75     </p>
  76     <h2><a name="ACL_server_username">Username/password auth</a></h2>
  77     <p>
  78 The plain TCP socket of the libvirt daemon defaults to using SASL for authentication.
  79 The SASL mechanism configured by default is DIGEST-MD5, which provides a basic
  80 username+password style authentication. It also provides for encryption of the data
  81 stream, so the security of the plain TCP socket is on a par with that of the TLS
  82 socket. If desired the UNIX socket and TLS socket can also have SASL enabled by
  83 setting the <code>auth_unix_ro</code>, <code>auth_unix_rw</code>, <code>auth_tls</code>
  84 config params in <code>libvirt.conf</code>.
  85 </p>
  86     <p>
  87 Out of the box, no user accounts are defined, so no clients will be able to authenticate
  88 on the TCP socket. Adding users and setting their passwords is done with the <code>saslpasswd2</code>
  89 command. When running this command it is important to tell it that the appname is <code>libvirt</code>.
  90 As an example, to add a user <code>fred</code>, run
  91 </p>
  92     <pre>
  93 # saslpasswd2 -a libvirt fred
  94 Password: xxxxxx
  95 Again (for verification): xxxxxx
  96 </pre>
  97     <p>
  98 To see a list of all accounts the <code>sasldblistusers2</code> command can be used.
  99 This command expects to be given the path to the libvirt user database, which is kept
 100 in <code>/etc/libvirt/passwd.db</code>
 101 </p>
 102     <pre>
 103 # sasldblistusers2 -f /etc/libvirt/passwd.db
 104 fred@t60wlan.home.berrange.com: userPassword
 105 </pre>
 106     <p>
 107 Finally, to disable a user's access, the <code>saslpasswd2</code> command can be used
 108 again:
 109 </p>
 110     <pre>
 111 # saslpasswd2 -a libvirt -d fred
 112 </pre>
 113     <h2><a name="ACL_server_kerberos">Kerberos auth</a></h2>
 114     <p>
 115 The plain TCP socket of the libvirt daemon defaults to using SASL for authentication.
 116 The SASL mechanism configured by default is DIGEST-MD5, which provides a basic
 117 username+password style authentication. To enable Kerberos single-sign-on instead,
 118 the libvirt SASL configuration file must be changed. This is <code>/etc/sasl2/libvirt.conf</code>.
 119 The <code>mech_list</code> parameter must first be changed to <code>gssapi</code>
 120 instead of the default <code>digest-md5</code>. If SASL is enabled on the UNIX
 121 and/or TLS sockets, Kerberos will also be used for them. Like DIGEST-MD5, the Kerberos
 122 mechanism provides data encryption of the session.
 123 </p>
 124     <p>
 125 Some operating systems do not install the SASL kerberos plugin by default. It
 126 may be necessary to install a sub-package such as <code>cyrus-sasl-gssapi</code>.
 127 To check whether the Kerberos plugin is installed run the <code>pluginviewer</code>
 128 program and verify that <code>gssapi</code> is listed,eg:
 129 </p>
 130     <pre>
 131 # pluginviewer
 132 ...snip...
 133 Plugin "gssapiv2" [loaded],     API version: 4
 134         SASL mechanism: GSSAPI, best SSF: 56
 135         security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH
 136         features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
 137 </pre>
 138     <p>
 139 Next it is necessary for the administrator of the Kerberos realm to issue a principle
 140 for the libvirt server. There needs to be one principle per host running the libvirt
 141 daemon. The principle should be named <code>libvirt/full.hostname@KERBEROS.REALM</code>.
 142 This is typically done by running the <code>kadmin.local</code> command on the Kerberos
 143 server, though some Kerberos servers have alternate ways of setting up service principles.
 144 Once created, the principle should be exported to a keytab, copied to the host running
 145 the libvirt daemon and placed in <code>/etc/libvirt/krb5.tab</code>
 146 </p>
 147     <pre>
 148 # kadmin.local
 149 kadmin.local: add_principal libvirt/foo.example.com
 150 Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
 151 Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
 152 Principal "libvirt/foo.example.com@EXAMPLE.COM" created.
 153
 154 kadmin.local:  ktadd -k /root/libvirt-foo-example.tab libvirt/foo.example.com@EXAMPLE.COM
 155 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.
 156 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.
 157 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.
 158 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.
 159
 160 kadmin.local: quit
 161
 162 # scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5.tab
 163 # rm /root/libvirt-foo-example.tab
 164 </pre>
 165     <p>
 166 Any client application wishing to connect to a Kerberos enabled libvirt server
 167 merely needs to run <code>kinit</code> to gain a user principle. This may well
 168 be done automatically when a user logs into a desktop session, if PAM is setup
 169 to authenticate against Kerberos.
 170 </p>
 171   </body>
 172 </html>