Skip to main content

Synapse Section

Synapse is the Matrix homeserver that powers ESS, in this section you will be customising settings relating to your homeserver, analogous with settings you'd set in the homeserver.yml if configuring Synapse manually. For settings not configurable via the UI, you can configure via the Additional Config section, which allows directly copying and pasting config from the Configuration Manual.

All settings configured via the UI in this section will be saved to your deployment.yml, with the contents of secrets being saved to secrets.yml. You will find specific config examples under each respective section.

  • deployment.yml 
    metadata:
annotations:
  ui.element.io/layer: |
    components:
      synapse:
spec:
  components:
    synapse:
  • secrets.yml 
    kind: Secret
metadata:
  name: synapse
  namespace: element-onprem
data:

Profile

metadata:
  annotations:
    ui.element.io/profile: |
      components:
        synapse:
          _subvalues:
            fed: closed
            # fed: limited
            # fed: open
            mau: 500
            # mau: 2500
            # mau: 10000

Need breakdown of exactly what profiles do

Config

Accept Invites

spec:
  components:
    synapse:
      config:
        acceptInvites: manual
        # acceptInvites: auto
        # acceptInvites: auto_dm_only

how does this work - what is the synapse configuration manual equivalent... is there one?

  • Manual
  • Auto
  • Auto DM Only

Max MAU Users

spec:
  components:
    synapse:
      config:
        maxMauUsers: 250

does this set both the below, only the max? If so, why? etc.

Registration

enable_registration

spec:
  components:
    synapse:
      config:
        registration: open
        # registration: custom
        # registration: closed

Open enables registration for new users, users will be able create an account via Matrix clients that support it, i.e. Element Web. Closed disabled registration for new users, users will only be presented the option to login to the homeserver.

  • Custom
    • to confirm, Allows you to completely customise your configuration of Registration via the Additional Config section found under Advanced.

Open or Closed registration will not affect the creation of new Matrix Accounts via Delegated Authenication. New users via Delegated Authentication i.e. LDAP, SAML or OIDC, who have yet to login to the homeserver and technically do not yet have a created Matrix ID, will still have one created when they successfully authenticate regardless of if registration is Closed.

Admin Password

  • deployment.yml 
    spec:
  components:
    synapse:
      config:
        adminPasswordSecretKey: adminPassword
  • secrets.yml 
    data:
  adminPassword: ExampleAdminPasswordBase64EncodedString

Password for the @onprem-admin-donotdelete user, a Synapse Admin user automatically created to allow you to use the Admin Console. You should use this account to promote Matrix accounts you setup to Synapse Admins. When using the Admin Console via the Installer (:8443), you should auto-login as this account, no password required.

If you are experiencing issues with accessing the Admin Console following a wipe and reinstall, ensure you do not have the previous install credentials cached. You can clear them via your browsers' settings, then refresh the page (you will be provided with a new link via the Installer CLI) to resolve.

Log

spec:
  components:
    synapse:
      config:
        log:

Unlike with most other sections, logging values set here are analogous to creating a <SERVERNAME>.log.config instead of the homeserver.yml. See the Logging Sample Config File for further reference.

Root Level

spec:
  components:
    synapse:
      config:
        log:
          rootLevel: Info
          # rootLevel: Debug
          # rootLevel: Warning
          # rootLevel: Error
          # rootLevel: Critical

As defined under the Configuration file format section of the Python docs, the available options presented by the Installer are DEBUG, INFO, WARNING, ERROR and CRITICAL. These represent different severity levels for log messages and help control the verbosity of log output which help to filter messages based on their importance.

  • DEBUG: Detailed information, typically used for debugging purposes. Messages at this level provide the most fine-grained and detailed logging.
  • INFO: General information about the program's operation. This level is used to confirm that things are working as expected.
  • WARNING: Indicates a potential issue or something that might cause problems in the future. It doesn't necessarily mean an error has occurred, but it's a warning about a possible concern.
  • ERROR: Indicates a more serious issue or error in the program. When an error occurs, it might impact the functionality of the application.
  • CRITICAL: Indicates a very severe error that may lead to the program's termination. Critical messages suggest a problem that should be addressed immediately.

When troubleshooting, increasing the log level and redeploying can help narrow down where you're experiencing issues. By defualt, DEBUG is a good option to include everything allowing you to identify a problem.

It is not advised to leave your Logging Level at anything other than the default, as more verbose logging may expose information that should otherwise not be accessible. When sharing logs, remember to redact any sensitive information you do not wish to share.

Sentry DSN

spec:
  components:
    synapse:
      config:
        log:
          sentryDsn: https://publickey:secretkey@sentry.io/projectid

Here you can specify a Sentry Data Source Name (DSN) to connect Synapse logging to a specific project within your Sentry account. A typical Sentry DSN looks like:

https://<public_key>:<secret_key>@sentry.io/<project_id>

Level Overrides

spec:
  components:
    synapse:
      config:
        log:
          levelOverrides:
            synapse.storage.SQL: Info
            # synapse.storage.SQL: Debug
            # synapse.storage.SQL: Error
            # synapse.storage.SQL: Warning
            # synapse.storage.SQL: Critical

Need to understand how / where these are available i.e. synapse.storage.SQL How does this work, should they be formatted like: synapse.storage.SQL: DEBUG maybe?

Security

spec:
  components:
    synapse:
      config:
        security:

Default Room Encryption

spec:
  components:
    synapse:
      config:
        security:
          defaultRoomEncryption: auto_all
          # defaultRoomEncryption: auto_invite
          # defaultRoomEncryption: forced_all
          # defaultRoomEncryption: forced_invite
          # defaultRoomEncryption: not_set

need to document related to which synapse config manual option etc.

Password Policy

password_config

spec:
  components:
    synapse:
      config:
        security:
          # Not present when disabled
          # passwordPolicy: {} When enabled with default settings
          passwordPolicy: # Only configured like so when values changed from thier defaults
            minimumLength: 20 # Default: 15
            requireDigit: false # Default: true
            requireLowercase: false # Default: true
            requireSymbol: false # Default: true
            requireUppercase: false # Default: true

Turning on Password Policy will allow you to define and enforce a password policy for users' accounts on your homeserver. Options include:

  • Minimum Length
  • Require Digit
  • Require Lowercase
  • Require Symbol
  • Require Uppercase

You may notice that despite this not being enabled, users are required when registering to set secure passwords when doing do via the Element Web client. This is because the client itself enforces secure passwords, this setting is required should you wish to ensure all accounts have enforces password requirements, as other Matrix clients may not themselves enforce secure passwords.

Telemetry

spec:
  components:
    synapse:
      config:
        telemetry:
          enabled: true
          passwordSecretKey: telemetryPassword
          room: '#element-telemetry'

how does this work

URL Preview

url_preview_enabled

spec:
  components:
    synapse:
      config:
        urlPreview: {} # {} When disabled, otherwise enabled with config as detailed in sections below.

URL previews involve fetching information from a URL (e.g., a website link) and displaying a preview of the content, such as a title, description, and an image. This feature can be useful for enhancing the user experience by providing more context about shared URLs in chat messages.

Enabling or disabling URL previews can impact the amount of information displayed in the chat interface, and it can also have privacy implications as fetching URL previews involves making requests to external servers to retrieve metadata.

Config

Accept Language

url_preview_accept_language

spec:
  components:
    synapse:
      config:
        urlPreview:
          config:
            acceptLanguage:
              - en

By setting this configuration option, you can control the language preference that Matrix Synapse communicates to external servers when fetching URL previews. This can be useful if you want to influence the language of the content retrieved for URL previews based on the preferred language of your users.

To do so, specify the Localisation country subcode (e.g., en) that should be used as the Accept-Language header value that the server should send when fetching URL previews from external websites. The Accept-Language header is an HTTP header used by web browsers and other clients to indicate the preferred language(s) for the response.

Each value is a IETF language tag; a 2-3 letter identifier for a language, optionally followed by subtags separated by '-', specifying a country or region variant. Multiple values can be provided by clicking Add more Accept Langauge, and a weight can be added to each by using quality value syntax (;q=). '*' translates to any language.

IP Range Allowed

``

spec:
  components:
    synapse:
      config:
        urlPreview:
          config:
            ipRangeAllowed:
              - 10.0.0.0/24

Need to confirm exactly what this does, it is whitelist or blacklist. Blacklist is mandatory, but the wording suggests this is whitelist, what blacklist is used as config manual states it's required, and it hasd no defualts.

Back to top