# Access configuration

WirePlumber includes a "client access" policy which defines access control rules for PipeWire clients. This page documents the configuration sections that the policy reads; for how the policy itself works, see Client Access Control.

## Permission strings

Permissions are written as chmod-like strings, e.g. `"rwx"` or `"r-xm"`, built out of any combination of:

> - `r`: client is allowed to read objects, i.e. "see" them on the registry and list their properties

> - `w`: client is allowed to write objects, i.e. call methods that modify their state

> - `x`: client is allowed to execute methods on objects; the `w` flag must also be present to call methods that modify the object

> - `m`: client is allowed to set metadata on objects

> - `l`: nodes of this client are allowed to link to other nodes that the client can't "see" (i.e. the client doesn't have `r` permission on them)

The `-` character is ignored and only serves to make the string more readable when a flag is omitted. The special value `all` is also supported and is a synonym for `rwxm`; note that it does not include `l`.

## access.rules

`access.rules` matches clients and applies default permissions to them. In addition to the client's own properties, the constraints can match on `access`, which is the client's access category as derived from the `pipewire.access`, `pipewire.client.access` and `pipewire.sec.flatpak` properties.

Example:

    access.rules = [
      {
        matches = [
          {
            access = "flatpak"
            media.category = "Manager"
          }
        ]
        actions = {
          update-props = {
            access = "flatpak-manager"
            default_permissions = "all",
          }
        }
      }
      {
        matches = [
          {
            access = "flatpak"
          }
        ]
        actions = {
          update-props = {
            default_permissions = "rx"
          }
        }
      }
    ]

The `update-props` action understands the following properties:

> - `access`: the effective access category to record for the client. It is published on the client as the `pipewire.access.effective` property.

> - `default_permissions`: permissions to apply directly to the client as its fallback for all objects.

> - `permission_manager_name`: the name of a permission manager declared in `access.permission-managers` to attach to the client.

When both `default_permissions` and `permission_manager_name` are set, `default_permissions` takes precedence and the permission manager is ignored.

## access.permission-managers

For more advanced use cases, WirePlumber supports permission managers that can apply per-object permissions dynamically based on rules and object interests. Permission managers are defined in the `access.permission-managers` section and then referenced by name from `access.rules`.

Example:

    access.permission-managers = [
      {
        name = "custom"
        default_permissions = "all"
        core_permissions = "rx"
        rules = [
          {
            matches = [
              {
                media.class = "Audio/Source"
              }
            ]
            actions = {
              set-permissions = "-"
            }
          }
        ]
      }
    ]

    access.rules = [
      {
        matches = [
          {
            application.name = "paplay"
          }
        ]
        actions = {
          update-props = {
            permission_manager_name = "custom"
          }
        }
      }
    ]

Each permission manager supports the following properties:

> - `name`: (required) a unique name used to reference the manager from `access.rules`

> - `default_permissions`: the fallback permissions applied to all objects that don't match any rule (applied as `PW_ID_ANY`)

> - `core_permissions`: permissions applied specifically to the PipeWire core object (`PW_ID_CORE`, ID 0). This is useful when you want to allow a client to interact with the core (e.g. enumerate objects, subscribe to events) while restricting access to individual objects. If not set, the `default_permissions` value is used for the core as well.

> - `rules`: a list of match rules with `set-permissions` actions that grant specific permissions to objects matching the given constraints

Permissions from all matching rules are combined, and objects that match no rule fall back to `default_permissions`. See Permission managers for the details.

## Going further

Decisions that cannot be expressed as rules require a script. See Client Access Control for how to hook into the policy and Permissions API for the permission manager Lua API.