<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <body>
    <h1>Client access control</h1>
    <p>
      Libvirt's client access control framework allows administrators
      to setup fine grained permission rules across client users,
      managed objects and API operations. This allows client connections
      to be locked down to a minimal set of privileges.
    </p>

    <ul id="toc"></ul>

    <h2><a name="intro">Access control introduction</a></h2>

    <p>
      In a default configuration, the libvirtd daemon has three levels
      of access control. All connections start off in an unauthenticated
      state, where the only API operations allowed are those required
      to complete authentication. After successful authentication, a
      connection either has full, unrestricted access to all libvirt
      API calls, or is locked down to only "read only" operations,
      according to what socket a client connection originated on.
    </p>

    <p>
      The access control framework allows authenticated connections to
      have fine grained permission rules to be defined by the administrator.
      Every API call in libvirt has a set of permissions that will
      be validated against the object being used. For example, the
      <code>virDomainSetSchedulerParametersFlags</code> method will
      check whether the client user has the <code>write</code>
      permission on the <code>domain</code> object instance passed
      in as a parameter. Further permissions will also be checked
      if certain flags are set in the API call. In addition to
      checks on the object passed in to an API call, some methods
      will filter their results. For example the <code>virConnectListAllDomains</code>
      method will check the <code>search_domains</code> on the <code>connect</code>
      object, but will also filter the returned <code>domain</code>
      objects to only those on which the client user has the
      <code>getattr</code> permission.
    </p>

    <h2><a name="drivers">Access control drivers</a></h2>

    <p>
      The access control framework is designed as a pluggable
      system to enable future integration with arbitrary access
      control technologies. By default, the <code>none</code>
      driver is used, which does no access control checks at
      all. At this time, libvirt ships with support for using
      <a href="http://www.freedesktop.org/wiki/Software/polkit/">polkit</a> as a real access
      control driver. To learn how to use the polkit access
      driver consult <a href="aclpolkit.html">the configuration
      docs</a>.
    </p>

    <p>
      The access driver is configured in the <code>libvirtd.conf</code>
      configuration file, using the <code>access_drivers</code>
      parameter. This parameter accepts an array of access control
      driver names. If more than one access driver is requested,
      then all must succeed in order for access to be granted.
      To enable 'polkit' as the driver:
    </p>

    <pre>
# augtool -s set '/files/etc/libvirt/libvirtd.conf/access_drivers[1]' polkit
    </pre>

    <p>
      And to reset back to the default (no-op) driver
    </p>


    <pre>
# augtool -s rm /files/etc/libvirt/libvirtd.conf/access_drivers
    </pre>

    <p>
      <strong>Note:</strong> changes to libvirtd.conf require that
      the libvirtd daemon be restarted.
    </p>

    <h2><a name="perms">Objects and permissions</a></h2>

    <p>
      Libvirt applies access control to all the main object
      types in its API. Each object type, in turn, has a set
      of permissions defined. To determine what permissions
      are checked for specific API call, consult the
      <a href="html/index.html">API reference manual</a>
      documentation for the API in question.
    </p>

    <div id="include" filename="aclperms.htmlinc"/>

  </body>
</html>
