docs/acl.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>Client access control</h1>
   6     <p>
   7       Libvirt's client access control framework allows administrators
   8       to setup fine grained permission rules across client users,
   9       managed objects and API operations. This allows client connections
  10       to be locked down to a minimal set of privileges.
  11     </p>
  12
  13     <ul id="toc"></ul>
  14
  15     <h2><a name="intro">Access control introduction</a></h2>
  16
  17     <p>
  18       In a default configuration, the libvirtd daemon has three levels
  19       of access control. All connections start off in an unauthenticated
  20       state, where the only API operations allowed are those required
  21       to complete authentication. After successful authentication, a
  22       connection either has full, unrestricted access to all libvirt
  23       API calls, or is locked down to only "read only" operations,
  24       according to what socket a client connection originated on.
  25     </p>
  26
  27     <p>
  28       The access control framework allows authenticated connections to
  29       have fine grained permission rules to be defined by the administrator.
  30       Every API call in libvirt has a set of permissions that will
  31       be validated against the object being used. For example, the
  32       <code>virDomainSetSchedulerParametersFlags</code> method will
  33       check whether the client user has the <code>write</code>
  34       permission on the <code>domain</code> object instance passed
  35       in as a parameter. Further permissions will also be checked
  36       if certain flags are set in the API call. In addition to
  37       checks on the object passed in to an API call, some methods
  38       will filter their results. For example the <code>virConnectListAllDomains</code>
  39       method will check the <code>search_domains</code> on the <code>connect</code>
  40       object, but will also filter the returned <code>domain</code>
  41       objects to only those on which the client user has the
  42       <code>getattr</code> permission.
  43     </p>
  44
  45     <h2><a name="drivers">Access control drivers</a></h2>
  46
  47     <p>
  48       The access control framework is designed as a pluggable
  49       system to enable future integration with arbitrary access
  50       control technologies. By default, the <code>none</code>
  51       driver is used, which does no access control checks at
  52       all. At this time, libvirt ships with support for using
  53       <a href="http://www.freedesktop.org/wiki/Software/polkit/">polkit</a> as a real access
  54       control driver. To learn how to use the polkit access
  55       driver consult <a href="aclpolkit.html">the configuration
  56       docs</a>.
  57     </p>
  58
  59     <p>
  60       The access driver is configured in the <code>libvirtd.conf</code>
  61       configuration file, using the <code>access_drivers</code>
  62       parameter. This parameter accepts an array of access control
  63       driver names. If more than one access driver is requested,
  64       then all must succeed in order for access to be granted.
  65       To enable 'polkit' as the driver:
  66     </p>
  67
  68     <pre>
  69 # augtool -s set '/files/etc/libvirt/libvirtd.conf/access_drivers[1]' polkit
  70     </pre>
  71
  72     <p>
  73       And to reset back to the default (no-op) driver
  74     </p>
  75
  76
  77     <pre>
  78 # augtool -s rm /files/etc/libvirt/libvirtd.conf/access_drivers
  79     </pre>
  80
  81     <p>
  82       <strong>Note:</strong> changes to libvirtd.conf require that
  83       the libvirtd daemon be restarted.
  84     </p>
  85
  86     <h2><a name="perms">Objects and permissions</a></h2>
  87
  88     <p>
  89       Libvirt applies access control to all the main object
  90       types in its API. Each object type, in turn, has a set
  91       of permissions defined. To determine what permissions
  92       are checked for specific API call, consult the
  93       <a href="html/libvirt-libvirt.html">API reference manual</a>
  94       documentation for the API in question.
  95     </p>
  96
  97     <div id="include" filename="aclperms.htmlinc"/>
  98
  99   </body>
 100 </html>