Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration Reference

Venator uses YAML v1.2.2 for configuration. While not the prettiest option for configuration, other languages have been tried before and found to be even worse, so you’ll live (and likely also already know the syntax anyway).

The default configuration is generated at ./config.yaml (i.e. in the directory venatorctl is executed in), unless Venator is being executed by systemd, in which case it will reside under /etc/matrix-venator/config.yaml. The default configuration does not contain all possible values, but will contain all required values with at least a placeholder value.

This reference will list every config option available, with a description, and an example.

Required keys:

Debug mode

debug: Enable or disable debug mode.

While you can still get debug logs and whatnot with this option disabled, setting debug: true will enable additional runtime checks that may affect how the server operates. It is designed to be used with a step-through debugger in mind, so sometimes some conditions that would usually be handled by logging an error will instead cause actual panics and potentially crashes. An example of a side effect of enabling this option is that request handlers that don’t write a response body will cause a crash - with debug disabled, this will log an error instead.

Enabling debug mode also exposes additional information that would otherwise be obfuscated or only available in logs. This means enabling debug mode may also weaken your server’s security.

You usually only want to enable this if you are actively debugging Venator.

Example:

debug: true

Default room version

default_room_version: Defines the default room version for new rooms.

While clients can specify the room version they want to create when calling /createRoom, if they do not, the room version specified here will be used instead.

Note

You probably don’t need to set this - the latest version that Venator fully supports is used by default, meaning generally you should just update your server if the default version is not new enough. Overriding the default value may have unintended consequences.

Example:

default_room_version: 12

Dont expose metrics

dont_expose_metrics (boolean, optional): If true, don’t expose /metrics.

Disables the Prometheus metrics exporter route. The admin API route, /_venator/v0/admin/metrics, remains available.

Example:

dont_expose_metrics: true

Listeners

listeners (sequence mapping, required): Configures the addresses that Venator will listen to.

Both TCP and unix listeners are supported. You can even mix and match them! All listeners will listen for HTTP 1.0, 1.1, and 2.0 (including h2c).

TCP listener:

  • host (optional): The host to listen on. Usually 127.0.0.1 or ::1, or 0.0.0.0 & :: for all addresses. Defaults to an empty string, which implicitly means all addresses, both IPv4 and IPv6.
  • port (required): The port to listen on. Must be between 1 and 65536.

Unix listener:

  • socket (required): The path to the socket file. Venator must be able to create, read, write, and delete this path. Can be relative or absolute.

Both listeners can enable native TLS by setting tls: true.

Note

Native TLS is primarily only included for running the test suite. TLS should normally be terminated by your reverse proxy, unless you have an advanced use case.

Tip

All routes (client-to-server, appservices, key-server, server-to-server) are handled by all listeners. If you are used to the Synapse style of having to define which listeners handle which routes, you need not do that here. 127.0.0.1:8008 and 127.0.0.2:8448 both run through the same router, for example.

Example:

listeners:
  # tcp://*:8008 (any IPv4 address)
  - host: 0.0.0.0
    port: 8008

  # tcp://[*]:8008 (any IPv6 address)
  - host: "::"
    port: 8008

  # tcp+tls://*:8008 (any IPv4 address, with TLS)
  - host: 0.0.0.0
    port: 8448
    tls: true

  # tcp+tls://[*]:8448 (any IPv6 address, with TLS)
  - host: "::"
    port: 8448
    tls: true

  # tcp+tls://@:8448 (any IPv4 or IPv6 address, with TLS)
  - port: 8998
    tls: true

  # unix:/tmp/venator.sock (unix socket at /tmp/venator.sock)
  - socket: /tmp/venator.sock

Logging

logging: The configuration for zerolog using zeroconfig.

See zeroconfig for the full schema.

If there are no loggers configured, a coloured “pretty” stdout logger will be configured for you. If you are in debug mode (or Venator was built with a dirty working tree), an additional trace-level JSON logger will be configured for you too.

Example:

logging:
  writers:
    # - type: journald  # uncomment if you're using journald.
    - type: stdout
      format: pretty-colored
      min_level: info
    - type: file
      format: json
      min_level: debug
      filename: venator.log  # JSON-line file
      max_size: 100
      max_age: 30
      max_backups: 3
      compress: true

Max request bytes

max_request_bytes: The maximum size of a request (in bytes) to read before aborting. Defaults to 100MiB (104857600).

Since request bodies are buffered into memory (including media) before they’re worked on, it is generally necessary to limit the size of request bodies that will be read. If a request sends a body larger than this, it will only be partially read, and then rejected when the server realises it’s too large (at least one byte over the limit).

Caution

Setting this value too high will either result in the OOM reaper coming knocking, and terminating the server process, or potentially undefined behaviour ranging from catchable alloc failures, to critical panics.

Examples:

max_request_bytes: 26214400  # 25MiB

max_request_bytes: 52428800  # 50MiB

max_request_bytes: 104857600  # 100MiB (higher values are typically excessive and unsafe)

max_request_bytes: 536870912  # 512MiB

max_request_bytes: 1073741824  # 1GiB

Extra signing keys

extra_signing_key_paths: An array of paths to Synapse-formatted signing keys.

Venator manages its own signing key(s) in the database, however the option to use external signing keys is possible through this mechanism.

Venator will not manage these signing keys whatsoever. Only the first discovered signing key will be used (typically an existing key in the database) for event & request signing, the other keys will only be advertised.

If Venator does not find an active signing key in the database, but external signing keys are provided, it will not generate an internal key, and will instead rely on the external keys.

Example:

extra_signing_key_paths:
  - /var/lib/matrix-venator/signing-key-1.txt
  - /var/lib/matrix-venator/signing-key-2.txt

Old verify keys

old_verify_keys: A mapping of previous signing key IDs to when they expired.

A map of old signature keys that can be used to verify events. You should prefer to import the keys via the command venatorctl signing-key import, but if you do not have the private key any more you can advertise it here instead.

The keys of the map are the key IDs (e.g. ed25519:foo), and the value has two required keys:

  • key: The full public signing key of this key.
  • expired_ts: The unix timestamp (milliseconds) when this key expired.

Example:

old_verify_keys:
  - ed25519:auto:
      key: Noi6WqcDj0QmPxCNQqgezwTlBKrfqehY1u2FyWP9uYw
      expired_ts: 1576767829750

Room directory

admin_only: If enabled, only server admins are able to publish to the room directory.

When enabled, only admin users can publish rooms to the public room directory (i.e. room list). Note that when enabled, users can still create and use aliases, they just cannot publish them.

Example:

room_directory:
  admin_only: true

Server name

server_name: The name of this server.

This is not necessarily your domain name - it is the part of the ID that appears at the end of user IDs, and room aliases. For example, @user:matrix.example would have the server name matrix.example, even if traffic was ultimately served from venator.matrix.example.

The server name can be an IP address (not recommended) or DNS name, optionally with a port. Typically, you will use a DNS name without a port here (you configure the port later).

Caution

You cannot change the server name after registering the first user.

Examples:

server_name: matrix.example

server_name: matrix.example:8448  # not recommended

Static room directory

static_room_directory: Configures the “static room directory”.

Defines all the rooms and their metadata that can be used to serve room queries over federation. Allows you to define resolvable aliases for rooms the server is not yet in. See also: https://github.com/tulir/mauliasproxy.

Important

This option has no effect if experiments.federation is not enabled!

static_room_directory is a mapping of { localpart: {room_id: '...', via: ['...']} }. The localpart here is the part after #, but before : (like with user IDs). room_id is the underlying room ID, like !example:example.net, and via is a list of server names that can help prospective members join the room.

Example:

static_room_directory:
  main:
    room_id: '!hammerhead-1:nexy7574.co.uk'
    via: ["nexy7574.co.uk", "synapse.nexy7574.co.uk", "asgard.chat", "corellia.timedout.uk", "starstruck.systems"]

In this example, #main:SERVER_NAME will resolve to !hammerhead-1:nexy7574.co.uk, and will tell remote servers asking about this room to join through any of the provided servers.

TLS

tls: Configures TLS options for TLS listeners.

Configures the certificate file and key file for serving TLS directly from listeners. You can generate a self-signed certificate with mkcert:

mkcert -install && mkcert localhost '*.localhost'

Or with openssl, which is usually pre-installed everywhere:

openssl req -newkey rsa:4096 -nodes -keyout key.pem -x509 -days 365 -out cert.pem

Example:

tls:
  cert_file: path/to/cert.pem
  key_file: path/to/key.pem