From: Daniel P. Berrange Date: Wed, 5 Dec 2007 19:16:13 +0000 (+0000) Subject: Added docs on authentication setup X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=0e5f5da3db097571c2f9d80952788f73023d46ae;p=libvirt.git Added docs on authentication setup --- diff --git a/ChangeLog b/ChangeLog index 190993b9ac..3fd97b6b93 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Wed Dec 5 14:16:00 EST 2007 Daniel P. Berrange + + * docs/libvir.html: Add page about authentication setup options + * docs/libvirt.css: Make 
 tag show scrollbars if content
+	is too wide to fit
+	* docs/*.html: Re-generated from libvir.html
+
 Wed Dec  5 14:09:00 EST 2007 Daniel P. Berrange 
 
 	* configure.in: automatically disable Xen setuid proxy if
diff --git a/docs/FAQ.html b/docs/FAQ.html
index 2f94efe309..5c3d47a00e 100644
--- a/docs/FAQ.html
+++ b/docs/FAQ.html
@@ -77,4 +77,4 @@
     via the pkg-config command line tool, like:

     
pkg-config libvirt --libs

   
-
main menu
related links
Graphics and design by Diana Fong

+
main menu
related links
Graphics and design by Diana Fong

diff --git a/docs/architecture.html b/docs/architecture.html
index cf1d784175..e9aa01af97 100644
--- a/docs/architecture.html
+++ b/docs/architecture.html
@@ -64,4 +64,4 @@ drivers present in driver.h:
  • xend_internal: implements the driver fun
 
Note that a given driver may only implement a subset of those functions,
 (for example saving a Xen domain state to disk and restoring it is only
 possible though the Xen Daemon), in that case the driver entry points for
-unsupported functions are initialized to NULL.
main menu
related links
Graphics and design by Diana Fong

+unsupported functions are initialized to NULL.
main menu
related links
Graphics and design by Diana Fong

diff --git a/docs/auth.html b/docs/auth.html
new file mode 100644
index 0000000000..6ba191aa5d
--- /dev/null
+++ b/docs/auth.html
@@ -0,0 +1,143 @@
+
+
+Access control
Access control

+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, independant
+of applications using libvirt.
+
Server configuration

+The libvirt daemon allows the adminstrator to choose the authentication
+mechanisms used for client connections on each network socket independantly.
+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 independantly. 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 unix_sock_auth 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 overriden by the adminstrator using the PolicyKit
+master configuration file in /etc/PolicyKit/PolicyKit.conf. The
+PolicyKit.conf(5) manual page provides details on the syntax
+available. The two libvirt daemon actions available are named org.libvirt.unix.monitor
+for the RO socket, and org.libvirt.unix.manage for the RW socket.
+

+As an example, to allow a user fredfull access to the RW socket,
+while requiring joe to authenticate with the admin password,
+would require adding the following snippet to PolicyKit.conf.
+
+  <match action="org.libvirt.unix.manage" user="fred">
+    <return result="yes"/>
+  </match>
+  <match action="org.libvirt.unix.manage" user="joe">
+    <return result="auth_admin"/>
+  </match>
+
Username/password auth

+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 auth_unix_ro, auth_unix_rw, auth_tls
+config params in libvirt.conf.
+

+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
+
Kerberos auth

+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 /etc/sasl2/libvirt.conf.
+The mech_list parameter must first be changed to gssapi
+instead of the default digest-md5. 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.
+

+Some operating systems do not install the SASL kerberos plugin by default. It
+may be neccessary 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 is is neccessary for the adminsitrator 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 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 principles.
+Once created, the principle 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 principle. This may well
+be done automatically when a user logs into a desktop session, if PAM is setup
+to authenticate against Kerberos.
+
main menu
related links
Graphics and design by Diana Fong

diff --git a/docs/bugs.html b/docs/bugs.html
index a25b6d11f4..89fd3128ed 100644
--- a/docs/bugs.html
+++ b/docs/bugs.html
@@ -14,4 +14,4 @@ network. Use the settings:
  • server: irc.oftc.net
    • 
   
  • port: 6667 (the usual IRC port)
    • 
   
  • channel: #virt
    • 
 
 But there is no guarantee that someone will be watching or able to reply,
-use the mailing-list if you don't get an answer there.
main menu
related links
Graphics and design by Diana Fong

+use the mailing-list if you don't get an answer there.
main menu
related links
Graphics and design by Diana Fong

diff --git a/docs/downloads.html b/docs/downloads.html
index ff074b097d..f5aad09051 100644
--- a/docs/downloads.html
+++ b/docs/downloads.html
@@ -7,4 +7,4 @@ available, first register onto the server:
cvs -d :pserver:anoncvs@l
 checkout the development tree with:
cvs -d :pserver:anoncvs@libvirt.org:2401/data/cvs co
 libvirt
Use ./autogen.sh to configure the local checkout, then make
 and make install, as usual. All normal cvs commands are now
-available except commiting to the base.
main menu
related links
Graphics and design by Diana Fong

+available except commiting to the base.
main menu
related links
Graphics and design by Diana Fong

diff --git a/docs/errors.html b/docs/errors.html
index eeede58e99..5d7bab3e79 100644
--- a/docs/errors.html
+++ b/docs/errors.html
@@ -66,4 +66,4 @@ this point, see the error.py example about it:
def handler(ctxt, err):
 
 libvirt.registerErrorHandler(handler, 'context') 
the second argument to the registerErrorHandler function is passed as the
 first argument of the callback like in the C version. The error is a tuple
-containing the same field as a virError in C, but cast to Python.
main menu
related links
Graphics and design by Diana Fong

+containing the same field as a virError in C, but cast to Python.
main menu
related links
Graphics and design by Diana Fong

diff --git a/docs/format.html b/docs/format.html
index 01946fa6a4..c3e7ec36a4 100644
--- a/docs/format.html
+++ b/docs/format.html
@@ -418,4 +418,4 @@ Xen support, you will see the os_type of xen to indicate a paravirtual
 kernel, then architecture informations and potential features.
The third block (in green) gives similar informations but when running a
 32 bit OS fully virtualized with Xen using the hvm support.
This section is likely to be updated and augmented in the future, see the
 discussion which led to the capabilities format in the mailing-list
-archives.
main menu
related links
Graphics and design by Diana Fong

+archives.
main menu
related links
Graphics and design by Diana Fong

diff --git a/docs/hvsupport.html b/docs/hvsupport.html
index f80948581f..e2b5521fad 100644
--- a/docs/hvsupport.html
+++ b/docs/hvsupport.html
@@ -392,4 +392,4 @@ first appeared in libvirt 0.2.0.
  virNetworkLookupByUUIDString   0.2.0 
  virNetworkSetAutostart   0.2.1 
  virNetworkUndefine   0.2.0 
-
main menu
related links
Graphics and design by Diana Fong

+
main menu
related links
Graphics and design by Diana Fong

diff --git a/docs/index.html b/docs/index.html
index 728c4d68b8..21b21528ca 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -68,6 +68,9 @@ virtualization mechanisms. It currently also supports Remote support
             
+            
  • 
+              Access control
+            
    • 
             
  • 
               Connection URIs
             
    • 
diff --git a/docs/intro.html b/docs/intro.html
index 1d8b40cb04..ff285d83d4 100644
--- a/docs/intro.html
+++ b/docs/intro.html
@@ -28,4 +28,4 @@ exception being domain migration between node capabilities which may need to
 be added at the libvirt level). Where possible libvirt should be extendable
 to be able to provide the same API for remote nodes, however this is not the
 case at the moment, the code currently handle only local node accesses
-(extension for remote access support is being worked on, see the mailing list discussions about it).
    main menu
    related links
    Graphics and design by Diana Fong
    
+(extension for remote access support is being worked on, see the mailing list discussions about it).
    main menu
    related links
    Graphics and design by Diana Fong
    
diff --git a/docs/libvir.html b/docs/libvir.html
index 825b251af7..f1bd743069 100644
--- a/docs/libvir.html
+++ b/docs/libvir.html
@@ -2766,6 +2766,204 @@ The protocol contains support for multiple program types and protocol
 versioning, modelled after SunRPC.
 
    
 
+
    Access control
    
+
+
    
+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, independant
+of applications using libvirt.
+
    
+
+
+
+
    Server configuration
    
+
+
    
+The libvirt daemon allows the adminstrator to choose the authentication
+mechanisms used for client connections on each network socket independantly.
+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 independantly. 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 unix_sock_auth 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 overriden by the adminstrator using the PolicyKit
+master configuration file in /etc/PolicyKit/PolicyKit.conf. The
+PolicyKit.conf(5) manual page provides details on the syntax
+available. The two libvirt daemon actions available are named org.libvirt.unix.monitor
+for the RO socket, and org.libvirt.unix.manage for the RW socket.
+
    
+
+
    
+As an example, to allow a user fredfull access to the RW socket,
+while requiring joe to authenticate with the admin password,
+would require adding the following snippet to PolicyKit.conf.
+
    
+
+
    +  <match action="org.libvirt.unix.manage" user="fred">
+    <return result="yes"/>
+  </match>
+  <match action="org.libvirt.unix.manage" user="joe">
+    <return result="auth_admin"/>
+  </match>
+
    
+
+
    Username/password auth
    
+
+
    
+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 auth_unix_ro, auth_unix_rw, auth_tls
+config params in libvirt.conf.
+
    
+
+
    
+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
+
    
+
+
+
    Kerberos auth
    
+
+
    
+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 /etc/sasl2/libvirt.conf.
+The mech_list parameter must first be changed to gssapi
+instead of the default digest-md5. 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.
+
    
+
+
    
+Some operating systems do not install the SASL kerberos plugin by default. It
+may be neccessary 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 is is neccessary for the adminsitrator 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 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 principles.
+Once created, the principle 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 principle. This may well
+be done automatically when a user logs into a desktop session, if PAM is setup
+to authenticate against Kerberos.
+
    
+
 
    Connection URIs
    
 
 
    
diff --git a/docs/libvirt.css b/docs/libvirt.css
index dcaacfe08d..bd70cf95f6 100644
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -170,6 +170,11 @@ pre.programlisting
     background:		#F0F0F0;
     }
 
+pre {
+    overflow: auto;
+    width: 100%;
+}
+
 table.top_table {
   border-collapse: collapse;
 }
diff --git a/docs/news.html b/docs/news.html
index ce42eed17c..0ae68dc16e 100644
--- a/docs/news.html
+++ b/docs/news.html
@@ -357,4 +357,4 @@ and check the ChangeLog to gauge progresses.
    0.0.1: Dec 19 2005
    • First release
      • 
   
    • Basic management of existing Xen domains
      • 
   
    • Minimal autogenerated Python bindings
      • 
-
    main menu
    related links
    Graphics and design by Diana Fong
    
+
    main menu
    related links
    Graphics and design by Diana Fong
    
diff --git a/docs/python.html b/docs/python.html
index 047949365a..b129db5580 100644
--- a/docs/python.html
+++ b/docs/python.html
@@ -62,4 +62,4 @@ from the C API, the only points to notice are:
    • the import of the modu
   
    • extracting and printing some informations about the domain using
     various methods
     associated to the virDomain class.
      • 
-
    main menu
    related links
    Graphics and design by Diana Fong
    
+
    main menu
    related links
    Graphics and design by Diana Fong
    
diff --git a/docs/remote.html b/docs/remote.html
index 17f9711c80..48ca4365bc 100644
--- a/docs/remote.html
+++ b/docs/remote.html
@@ -650,4 +650,4 @@ also possible.
 
    
 The protocol contains support for multiple program types and protocol
 versioning, modelled after SunRPC.
-
    main menu
    related links
    Graphics and design by Diana Fong
    
+
    main menu
    related links
    Graphics and design by Diana Fong
    
diff --git a/docs/site.xsl b/docs/site.xsl
index 0df321bf26..420fb19ad5 100644
--- a/docs/site.xsl
+++ b/docs/site.xsl
@@ -60,6 +60,9 @@
       
         hvsupport.html
       
+      
+        auth.html
+      
       
         windows.html
       
diff --git a/docs/uri.html b/docs/uri.html
index 7ba8f1e9c1..0bc9b2a759 100644
--- a/docs/uri.html
+++ b/docs/uri.html
@@ -168,4 +168,4 @@ connection.
 
    
 You should consider using libvirt remote support
 in future.
-
    main menu
    related links
    Graphics and design by Diana Fong
    
+
    main menu
    related links
    Graphics and design by Diana Fong
    
diff --git a/docs/windows.html b/docs/windows.html
index c0aca155be..2ba7fdec53 100644
--- a/docs/windows.html
+++ b/docs/windows.html
@@ -230,4 +230,4 @@ python
   
    
 
 
-
    main menu
    related links
    Graphics and design by Diana Fong
    
+
    main menu
    related links
    Graphics and design by Diana Fong