You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
89 lines
3.9 KiB
YAML
89 lines
3.9 KiB
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
|