2007-12-05 19:16:13 +00:00
<?xml version="1.0" encoding="ISO-8859-1"?>
2008-04-25 16:23:51 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2008-04-23 17:08:31 +00:00
< html xmlns = "http://www.w3.org/1999/xhtml" >
<!--
This file is autogenerated from auth.html.in
Do not edit this file. Changes will be lost.
-->
< head >
< meta http-equiv = "Content-Type" content = "text/html; charset=ISO-8859-1" / >
< link rel = "stylesheet" type = "text/css" href = "main.css" / >
< link rel = "SHORTCUT ICON" href = "32favicon.png" / >
< title > libvirt: Access control< / title >
< meta name = "description" content = "libvirt, virtualization, virtualization API" / >
< / head >
< body >
< div id = "header" >
< div id = "headerLogo" > < / div >
< div id = "headerSearch" >
2008-04-25 16:23:51 +00:00
< form action = "search.php" enctype = "application/x-www-form-urlencoded" method = "get" > < div >
< input id = "query" name = "query" type = "text" size = "12" value = "" / >
< input id = "submit" name = "submit" type = "submit" value = "Search" / >
< / div > < / form >
2008-04-23 17:08:31 +00:00
< / div >
< / div >
< div id = "body" >
2008-04-25 16:23:51 +00:00
< div id = "menu" >
< ul class = "l0" > < li >
< div >
< a title = "Front page of the libvirt website" class = "inactive" href = "index.html" > Home< / a >
< / div >
< / li > < li >
< div >
< a title = "Details of new features and bugs fixed in each release" class = "inactive" href = "news.html" > News< / a >
< / div >
< / li > < li >
< div >
< a title = "Get the latest source releases, binary builds and get access to the source repository" class = "inactive" href = "downloads.html" > Downloads< / a >
< / div >
< / li > < li >
< div >
< a title = "Information for users, administrators and developers" class = "active" href = "docs.html" > Documentation< / a >
< ul class = "l1" > < li >
< div >
< a title = "Information about deploying and using libvirt" class = "active" href = "deployment.html" > Deployment< / a >
< ul class = "l2" > < li >
< div >
< a title = "The URI formats used for connecting to libvirt" class = "inactive" href = "uri.html" > URI format< / a >
< / div >
< / li > < li >
< div >
< a title = "Enable remote access over TCP" class = "inactive" href = "remote.html" > Remote access< / a >
< / div >
< / li > < li >
< div >
< span class = "active" > Authentication< / span >
< / div >
< / li > < li >
< div >
< a title = "Access the libvirt daemon from a native Windows client" class = "inactive" href = "windows.html" > Windows port< / a >
< / div >
< / li > < / ul >
< / div >
< / li > < li >
< div >
< a title = "Overview of the logical subsystems in the libvirt API" class = "inactive" href = "intro.html" > Architecture< / a >
< / div >
< / li > < li >
< div >
< a title = "Description of the XML formats used in libvirt" class = "inactive" href = "format.html" > XML format< / a >
< / div >
< / li > < li >
< div >
< a title = "Hypervisor specific driver information" class = "inactive" href = "drivers.html" > Drivers< / a >
< / div >
< / li > < li >
< div >
< a title = "Reference manual for the C public API" class = "inactive" href = "html/index.html" > API reference< / a >
< / div >
< / li > < li >
< div >
< a title = "Bindings of the libvirt API for other languages" class = "inactive" href = "bindings.html" > Language bindings< / a >
< / div >
< / li > < / ul >
< / div >
< / li > < li >
< div >
< a title = "User contributed content" class = "inactive" href = "http://wiki.libvirt.org" > Wiki< / a >
< / div >
< / li > < li >
< div >
< a title = "Frequently asked questions" class = "inactive" href = "FAQ.html" > FAQ< / a >
< / div >
< / li > < li >
< div >
< a title = "How and where to report bugs and request features" class = "inactive" href = "bugs.html" > Bug reports< / a >
< / div >
< / li > < li >
< div >
< a title = "How to contact the developers via email and IRC" class = "inactive" href = "contact.html" > Contact< / a >
< / div >
< / li > < li >
< div >
< a title = "Miscellaneous links of interest related to libvirt" class = "inactive" href = "relatedlinks.html" > Related Links< / a >
< / div >
< / li > < li >
< div >
< a title = "Overview of all content on the website" class = "inactive" href = "sitemap.html" > Sitemap< / a >
< / div >
< / li > < / ul >
< / div >
2008-04-23 17:08:31 +00:00
< div id = "content" >
< h1 > Access control< / h1 >
< p >
2007-12-05 19:16:13 +00:00
When connecting to libvirt, some connections may require client
authentication before allowing use of the APIs. The set of possible
2008-04-04 07:58:29 +00:00
authentication mechanisms is administrator controlled, independent
2007-12-05 19:16:13 +00:00
of applications using libvirt.
2008-04-23 17:08:31 +00:00
< / p >
< ul > < li >
< a href = "#ACL_server_config" > Server configuration< / a >
< / li > < li >
< a href = "#ACL_server_unix_perms" > UNIX socket permissions/group< / a >
< / li > < li >
< a href = "#ACL_server_polkit" > UNIX socket PolicyKit auth< / a >
< / li > < li >
< a href = "#ACL_server_username" > Username/password auth< / a >
< / li > < li >
< a href = "#ACL_server_kerberos" > Kerberos auth< / a >
< / li > < / ul >
< h3 >
< a name = "ACL_server_config" id = "ACL_server_config" > Server configuration< / a >
< / h3 >
< p >
2008-03-17 10:27:31 +00:00
The libvirt daemon allows the administrator to choose the authentication
mechanisms used for client connections on each network socket independently.
2007-12-05 19:16:13 +00:00
This is primarily controlled via the libvirt daemon master config file in
< code > /etc/libvirt/libvirtd.conf< / code > . Each of the libvirt sockets can
2008-03-17 10:27:31 +00:00
have its authentication mechanism configured independently. There is
2007-12-05 19:16:13 +00:00
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.
2008-04-23 17:08:31 +00:00
< / p >
< h3 >
< a name = "ACL_server_unix_perms" id = "ACL_server_unix_perms" > UNIX socket permissions/group< / a >
< / h3 >
< p >
2007-12-05 19:16:13 +00:00
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.
2008-04-23 17:08:31 +00:00
< / p >
< p >
2007-12-05 19:16:13 +00:00
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.
2008-04-23 17:08:31 +00:00
< / p >
< h3 >
< a name = "ACL_server_polkit" id = "ACL_server_polkit" > UNIX socket PolicyKit auth< / a >
< / h3 >
< p >
2007-12-05 19:16:13 +00:00
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.
2008-04-23 17:08:31 +00:00
< / p >
< p >
2008-04-04 07:58:29 +00:00
The default policy can be overridden by the administrator using the PolicyKit
2007-12-05 19:16:13 +00:00
master configuration file in < code > /etc/PolicyKit/PolicyKit.conf< / code > . The
< code > PolicyKit.conf(5)< / code > manual page provides details on the syntax
available. The two libvirt daemon actions available are named < code > org.libvirt.unix.monitor< / code >
for the RO socket, and < code > org.libvirt.unix.manage< / code > for the RW socket.
2008-04-23 17:08:31 +00:00
< / p >
< p >
2007-12-05 19:16:13 +00:00
As an example, to allow a user < code > fred< / code > full access to the RW socket,
while requiring < code > joe< / code > to authenticate with the admin password,
would require adding the following snippet to < code > PolicyKit.conf< / code > .
2008-04-23 17:08:31 +00:00
< / p >
< pre >
2007-12-05 19:16:13 +00:00
< 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>
2008-04-23 17:08:31 +00:00
< / pre >
< h3 >
< a name = "ACL_server_username" id = "ACL_server_username" > Username/password auth< / a >
< / h3 >
< p >
2007-12-05 19:16:13 +00:00
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 > .
2008-04-23 17:08:31 +00:00
< / p >
< p >
2007-12-05 19:16:13 +00:00
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
2008-04-23 17:08:31 +00:00
< / p >
< pre >
2007-12-05 19:16:13 +00:00
# saslpasswd2 -a libvirt fred
Password: xxxxxx
Again (for verification): xxxxxx
2008-04-23 17:08:31 +00:00
< / pre >
< p >
2007-12-05 19:16:13 +00:00
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 >
2008-04-23 17:08:31 +00:00
< / p >
< pre >
2007-12-05 19:16:13 +00:00
# sasldblistusers2 -f /etc/libvirt/passwd.db
fred@t60wlan.home.berrange.com: userPassword
2008-04-23 17:08:31 +00:00
< / pre >
< p >
2007-12-05 19:16:13 +00:00
Finally, to disable a user's access, the < code > saslpasswd2< / code > command can be used
again:
2008-04-23 17:08:31 +00:00
< / p >
< pre >
2007-12-05 19:16:13 +00:00
# saslpasswd2 -a libvirt -d fred
2008-04-23 17:08:31 +00:00
< / pre >
< h3 >
< a name = "ACL_server_kerberos" id = "ACL_server_kerberos" > Kerberos auth< / a >
< / h3 >
< p >
2007-12-05 19:16:13 +00:00
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.
2008-04-23 17:08:31 +00:00
< / p >
< p >
2007-12-05 19:16:13 +00:00
Some operating systems do not install the SASL kerberos plugin by default. It
2008-03-17 10:27:31 +00:00
may be necessary to install a sub-package such as < code > cyrus-sasl-gssapi< / code > .
2007-12-05 19:16:13 +00:00
To check whether the Kerberos plugin is installed run the < code > pluginviewer< / code >
program and verify that < code > gssapi< / code > is listed,eg:
2008-04-23 17:08:31 +00:00
< / p >
< pre >
2007-12-05 19:16:13 +00:00
# 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
2008-04-23 17:08:31 +00:00
< / pre >
< p >
2008-04-04 07:58:29 +00:00
Next is is necessary for the administrator of the Kerberos realm to issue a principle
2007-12-05 19:16:13 +00:00
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 >
2008-04-23 17:08:31 +00:00
< / p >
< pre >
2007-12-05 19:16:13 +00:00
# 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
2008-04-23 17:08:31 +00:00
< / pre >
< p >
2007-12-05 19:16:13 +00:00
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.
2008-04-23 17:08:31 +00:00
< / p >
< / div >
< / div >
< div id = "footer" >
2008-04-28 08:29:35 +00:00
< p id = "sponsor" >
Sponsored by:< br / > < a href = "http://et.redhat.com/" > < img src = "et.png" alt = "Project sponsored by Red Hat Emerging Technology" / > < / a > < / p >
2008-04-23 17:08:31 +00:00
< / div >
< / body >
< / html >
