Registration

registration: The registration settings for this server.

Controls the registration requirements for the server. If omitted, registration is disabled, and there is no pre-shared admin secret.

Example:

registration:
  enabled: true
  require_token: true
  password_requirements:
    min_entropy: 70
  admin_pre_shared_secret: 38d7630f8c5bdb50df2d99e65fd0e60f

Enabled

enabled: Whether registration is enabled at all. Defaults to false.

If registration is disabled, no new accounts can be created without the admin API, even if requirements like a token are set.

Example:

registration:
  enabled: true

Enable unsafe registration

i_have_a_very_good_reason_or_i_am_stupid_and_want_to_allow_unsafe_open_registration: If set to true, registration will be enabled without any requirements.

Enables registration without any registration requirements. This is dangerous, as this means your only defence against automated bots mass-registering on your server is rate-limits, and you have no way to prevent untrusted users registering and potentially being abusive. You should never need to enable this!

Example:

registration:
  i_have_a_very_good_reason_or_i_am_stupid_and_want_to_allow_unsafe_open_registration: false

Requires token

requires_token: If true, registering on the server requires an invite token.

Example:

registration:
  requires_token: true

Password requirements

password_requirements: Controls the requirements for passwords on this server.

Allows you to set minimum password length and entropy requirements. Not applied to accounts created via the admin API.

Example:

registration:
  password_requirements:
    min_entropy: 50  # require at least 50 bits of entropy
    min_length: 0  # disable length requirements

Argon2id config

argon2id: Controls the parameters passed to the Argon2id password hashing algorithm.

Allows you to change the time cost, memory cost, and parallelism values of the Argon2id algorithm. When a field is omitted, it defaults to whatever is recommended by RFC9106 § 7.4. It is not recommended you adjust this unless you have a very good reason to.

Venator does not validate that you set “secure” values, in case the definition of “secure values” differs in the future. As such, you can shoot yourself in the foot with this. Furthermore, hashes are immutable once created - if you set an insane memory cost (like the recommended 2 gigabytes), the generated hash will always use that value during verification.

Fields:

t (32-bit unsigned integer): the T parameter (time cost). Must be at least 1 (0 uses default value).
m (32-bit unsigned integer): the M parameter (memory cost, in kibibytes). Note that this is normalised to at least 8*p (per RFC 9106). Consequently, cannot be lower than 8 (0 uses default value).
p (8-bit unsigned integer): the parallelism degree. Must be at least 1 (0 uses default value).

Admin pre-shared secret

admin_pre_shared_secret: A pre-generated authentication token that can only be used with the admin API.

See: pre-shared secret authentication (Admin API)

Warning

A pre-shared secret is required to use venatorctl, and also create the first user.

Example:

registration:
  admin_pre_shared_secret: 38d7630f8c5bdb50df2d99e65fd0e60f

curl -H 'Authorization: Bearer 38d7630f8c5bdb50df2d99e65fd0e60f' \
    --json '{"localpart":"admin","admin": true}' \
    http://localhost:8008/_venator/v0/admin/users/create

Admin pre-shared secret file

admin_pre_shared_secret_file: The file path to where the full admin pre-shared secret can be found.

This path, if provided, should point to a plain text file containing solely the PSK. This is provided as an alternative to admin_pre_shared_secret to avoid embedding secrets into the configuration file directly.

admin_pre_shared_secret takes priority over admin_pre_shared_secret_file. If admin_pre_shared_secret_file cannot be loaded at startup, Venator will crash.

Only the first 4096 bytes of the secrets file will be read, so secrets cannot be >4096 bytes (4KiB). Leading and trailing whitespace around the secret will also be removed after reading.

welcome_message

welcome_message: Configures the welcome message sent to new users.

Venator can be configured to read a file and send its contents to users when they register on the server through the server notices system.

It has one key, file, which is a file path to the file that will be read every time a new user registers. If the file cannot be read, the registration will not be prevented, but an error will be logged.

file must end in either .md, .json, or .txt. If the filepath ends in .txt, the file’s contents are interpreted as plain text, and sent as such (with no formatting applied). If the file ends in .md, the file’s contents are parsed with the Markdown parser (goldmark), including allowing HTML. If you want to have total control over the message that is sent, you can supply a .json file, with a m.room.message object (don’t forget to specify the msgtype!).

Examples:

registration:
  welcome_message:
    file: /etc/matrix-venator/welcome.md

Markdown file:

# Welcome to Server Name Here!

Lorem ipsum or whatever

Text file:

Welcome to Server Name Here! Lorem ipsum or whatever

JSON file:

{
  "msgtype": "m.text",
  "body": "Welcome to Server Name Here! Lorem ipsum or whatever",
  "format": "org.matrix.custom.html",
  "formatted_body": "<h1>Welcome to <strong>Server Name Here</strong>!</h1><p><span data-mx-color=\"#FF0000\">Lorem</span> <span data-mx-color=\"#00FF00\">ipsum</span> or whatever</p>"
}

auto_join_rooms

auto_join_rooms: A list of room references to automatically add new users to upon registration.

After registering, the user will be automatically joined to the rooms listed here, in the order they are listed. You can use both room aliases and room IDs, however if the alias cannot be resolved, the room is skipped. Likewise, if the room cannot be loaded, the join is skipped.

You can put non-public rooms here too. Venator will attempt to satisfy restricted join rules where possible, but where not possible, it will instead try to find a user in the room who can issue an invite to the newly registered user. Then, the existing user will be controlled by the server to issue an invite to the newly registered user, at which point the newly registered user will automatically accept.

In order to disambiguate between regular invites and joins, and server-controlled ones, the server will force a reason in the membership events.

If Venator cannot join the user to the room and also cannot invite them, or there is an error at any part of the process, the auto join room is skipped, and an error is logged.

Examples:

registration:
  auto_join_rooms:
    - '#space:example.com'
    - '!restricted-room:example.com'

Keyboard shortcuts

Venator