libvirt: Client access control
Description: libvirt, virtualization, virtualization API

# Client access control

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.

- Access control introduction
- Access control drivers
- Objects and permissions

## Access control introduction

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.

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 `virDomainSetSchedulerParametersFlags` method will check whether the client user has the `write` permission on the `domain` 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 `virConnectListAllDomains` method will check the `search_domains` on the `connect` object, but will also filter the returned `domain` objects to only those on which the client user has the `getattr` permission.

## Access control drivers

The access control framework is designed as a pluggable system to enable future integration with arbitrary access control technologies. By default, the `none` driver is used, which does no access control checks at all. At this time, libvirt ships with support for using polkit as a real access control driver. To learn how to use the polkit access driver consult the configuration docs.

The access driver is configured in the `libvirtd.conf` configuration file, using the `access_drivers` 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:

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

And to reset back to the default (no-op) driver

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

Note: changes to libvirtd.conf require that the libvirtd daemon be restarted.

## Objects and permissions

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 API reference manual documentation for the API in question.

### virConnectPtr

Permission | Description
--- | ---
detect-storage-pools | Detect storage pools
getattr | Access connection
interface-transaction | Interface transactions
pm-control | Use host power management
read | Read host
search-domains | List domains
search-interfaces | List interfaces
search-networks | List networks
search-node-devices | List node devices
search-nwfilters | List network filters
search-secrets | List secrets
search-storage-pools | List storage pools
write | Write host

### virDomainPtr

Permission | Description
--- | ---
block-read | Read domain block
block-write | Write domain block
core-dump | Dump domain
delete | Delete domain
fs-trim | Trim domain filesystems
getattr | Access domain
hibernate | Hibernate domain
init-control | Domain init control
inject-nmi | Inject domain NMI
mem-read | Read domain memory
migrate | Migrate domain
open-device | Open domain device
open-graphics | Open domain graphics
open-namespace | Open domain namespace
pm-control | Use domain power management
read | Read domain
read-secure | Read secure domain
reset | Reset domain
save | Save domain
screenshot | Take domain screenshot
send-input | Send domain input
send-signal | Send domain signal
snapshot | Snapshot domain
start | Start domain
stop | Stop domain
suspend | Suspend domain
write | Write domain

### virInterfacePtr

Permission | Description
--- | ---
delete | Delete interface
getattr | Access interface
read | Read interface
save | Save interface
start | Start interface
stop | Stop interface
write | Write interface

### virNetworkPtr

Permission | Description
--- | ---
delete | Delete network
getattr | Access network
read | Read network
save | Save network
start | Start network
stop | Stop network
write | Write network

### virNodeDevicePtr

Permission | Description
--- | ---
detach | Detach node device
getattr | Access node device
read | Read node device
start | Start node device
stop | Stop node device
write | Write node device

### virNWFilterPtr

Permission | Description
--- | ---
delete | Delete network filter
getattr | Access network filter
read | Read network filter
save | Save network filter
write | Write network filter

### virSecretPtr

Permission | Description
--- | ---
delete | Delete secret
getattr | Access secret
read | Read secret
read-secure | Read secure secret
save | Save secret
write | Write secret

### virStoragePoolPtr

Permission | Description
--- | ---
delete | Delete storage pool
format | Format storage pool
getattr | Access storage pool
read | Read storage pool
refresh | Refresh storage pool
save | Save storage pool
search-storage-vols | List storage pool volumes
start | Start storage pool
stop | Stop storage pool
write | Write storage pool

### virStorageVolPtr

Permission | Description
--- | ---
create | Create storage volume
data-read | Read storage volume data
data-write | Write storage volume data
delete | Delete storage volume
format | Format storage volume
getattr | Access storage volume
read | Read storage volume
resize | Resize storage volume