matrix-spec/data/event-schemas/schema/m.room.server_acl.yaml

---
title: Server ACL
description: |-
  An event to indicate which servers are permitted to participate in the
  room. Server ACLs may allow or deny groups of hosts. All servers participating
  in the room, including those that are denied, are expected to uphold the
  server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts
  list in order for the ACLs to remain effective.

  The `allow` and `deny` lists are lists of globs supporting `?` and `*`
  as wildcards. When comparing against the server ACLs, the suspect server's port
  number must not be considered. Therefore `evil.com`, `evil.com:8448`, and
  `evil.com:1234` would all match rules that apply to `evil.com`, for example.

  The ACLs are applied to servers when they make requests, and are applied in
  the following order:

  1. If there is no `m.room.server_acl` event in the room state, allow.
  2. If the server name is an IP address (v4 or v6) literal, and `allow_ip_literals`
     is present and `false`, deny.
  3. If the server name matches an entry in the `deny` list, deny.
  4. If the server name matches an entry in the `allow` list, allow.
  5. Otherwise, deny.

  **Note:**
  Server ACLs do not restrict the events relative to the room DAG via authorisation
  rules, but instead act purely at the network layer to determine which servers are
  allowed to connect and interact with a given room.

  **Warning:**
  Failing to provide an `allow` rule of some kind will prevent **all**
  servers from participating in the room, including the sender. This renders
  the room unusable. A common allow rule is `[ "*" ]` which would still
  permit the use of the `deny` list without losing the room.

  **Warning:**
  All compliant servers must implement server ACLs.  However, legacy or noncompliant
  servers exist which do not uphold ACLs, and these MUST be manually appended to
  the denied hosts list when setting an ACL to prevent them from leaking events from
  banned servers into a room. Currently, the only way to determine noncompliant hosts is
  to check the `prev_events` of leaked events, therefore detecting servers which
  are not upholding the ACLs. Server versions can also be used to try to detect hosts that
  will not uphold the ACLs, although this is not comprehensive. Server ACLs were added
  in Synapse v0.32.0, although other server implementations and versions exist in the world.
allOf:
  - $ref: core-event-schema/state_event.yaml
type: object
properties:
  content:
    properties:
      allow_ip_literals:
        type: boolean
        description: |-
          True to allow server names that are IP address literals. False to
          deny. Defaults to true if missing or otherwise not a boolean.

          This is strongly recommended to be set to `false` as servers running
          with IP literal names are strongly discouraged in order to require
          legitimate homeservers to be backed by a valid registered domain name.
      allow:
        type: array
        description: |-
          The server names to allow in the room, excluding any port information.
          Wildcards may be used to cover a wider range of hosts, where `*`
          matches zero or more characters and `?` matches exactly one character.

          **This defaults to an empty list when not provided, effectively disallowing
          every server.**
        items:
          type: string
      deny:
        type: array
        description: |-
          The server names to disallow in the room, excluding any port information.
          Wildcards may be used to cover a wider range of hosts, where `*`
          matches zero or more characters and `?` matches exactly one character.

          This defaults to an empty list when not provided.
        items:
          type: string
    type: object
  state_key:
    description: A zero-length string.
    pattern: '^$'
    type: string
  type:
    enum: ['m.room.server_acl']
    type: string