Configuring Synapse

Configuring Synapse

Before you can start Synapse, you will need to generate a configuration file. To do this, run (in your virtualenv, as before):

cd ~/.synapse
python -m synapse.app.homeserver \
    --server-name my.domain.name \
    --config-path homeserver.yaml \
    --generate-config \
    --report-stats=[yes|no]

... substituting an appropriate value for --server-name. The server name determines the "domain" part of user-ids for users on your server: these will all be of the format @user:my.domain.name. It also determines how other matrix servers will reach yours for Federation. For a test configuration, set this to the hostname of your server. For a more production-ready setup, you will probably want to specify your domain (example.com) rather than a matrix-specific hostname here (in the same way that your email address is probably [email protected] rather than [email protected]) - but doing so may require more advanced setup - see Setting up Federation. Beware that the server name cannot be changed later.

This command will generate you a config file that you can then customise, but it will also generate a set of keys for you. These keys will allow your Home Server to identify itself to other Home Servers, so don't lose or delete them. It would be wise to back them up somewhere safe. (If, for whatever reason, you do need to change your Home Server's keys, you may find that other Home Servers have the old key cached. If you update the signing key, you should change the name of the key in the <server name>.signing.key file (the second word) to something different. See `the spec`__ for more information on key management.)

The default configuration exposes two HTTP ports: 8008 and 8448. Port 8008 is configured without TLS; it should be behind a reverse proxy for TLS/SSL termination on port 443 which in turn should be used for clients. Port 8448 is configured to use TLS with a self-signed certificate. If you would like to do initial test with a client without having to setup a reverse proxy, you can temporarly use another certificate. (Note that a self-signed certificate is fine for Federation). You can do so by changing tls_certificate_path, tls_private_key_path and tls_dh_params_path in homeserver.yaml; alternatively, you can use a reverse-proxy, but be sure to read `Using a reverse proxy with Synapse`_ when doing so.

Apart from port 8448 using TLS, both ports are the same in the default configuration.

Registering a user

You will need at least one user on your server in order to use a Matrix client. Users can be registered either `via a Matrix client`__, or via a commandline script.

To get started, it is easiest to use the command line to register new users:

$ source ~/.synapse/bin/activate
$ synctl start # if not already running
$ register_new_matrix_user -c homeserver.yaml https://localhost:8448
New user localpart: erikj
Password:
Confirm password:
Make admin [no]:
Success!

This process uses a setting registration_shared_secret in homeserver.yaml, which is shared between Synapse itself and the register_new_matrix_user script. It doesn't matter what it is (a random value is generated by --generate-config), but it should be kept secret, as anyone with knowledge of it can register users on your server even if enable_registration is false.

Setting up a TURN server

For reliable VoIP calls to be routed via this homeserver, you MUST configure a TURN server. See docs/turn-howto.rst for details.

Running Synapse

To actually run your new homeserver, pick a working directory for Synapse to run (e.g. ~/.synapse), and:

cd ~/.synapse
source ./bin/activate
synctl start

Connecting to Synapse from a client

The easiest way to try out your new Synapse installation is by connecting to it from a web client. The easiest option is probably the one at https://riot.im/app. You will need to specify a "Custom server" when you log on or register: set this to https://domain.tld if you setup a reverse proxy following the recommended setup, or https://localhost:8448 - remember to specify the port (:8448) if not :443 unless you changed the configuration. (Leave the identity server as the default - see `Identity servers`_.)

If using port 8448 you will run into errors until you accept the self-signed certificate. You can easily do this by going to https://localhost:8448 directly with your browser and accept the presented certificate. You can then go back in your web client and proceed further.

If all goes well you should at least be able to log in, create a room, and start sending messages.

(The homeserver runs a web client by default at https://localhost:8448/, though as of the time of writing it is somewhat outdated and not really recommended - https://github.com/matrix-org/synapse/issues/1527).

Registering a new user from a client

By default, registration of new users via Matrix clients is disabled. To enable it, specify enable_registration: true in homeserver.yaml. (It is then recommended to also set up CAPTCHA - see docs/CAPTCHA_SETUP.rst.)

Once enable_registration is set to true, it is possible to register a user via riot.im or other Matrix clients.

Your new user name will be formed partly from the server_name (see Configuring synapse), and partly from a localpart you specify when you create the account. Your name will take the form of:

@localpart:my.domain.name

(pronounced "at localpart on my dot domain dot name").

As when logging in, you will need to specify a "Custom server". Specify your desired localpart in the 'User name' box.

Setting up Federation

Federation is the process by which users on different servers can participate in the same room. For this to work, those other servers must be able to contact yours to send messages.

As explained in Configuring synapse, the server_name in your homeserver.yaml file determines the way that other servers will reach yours. By default, they will treat it as a hostname and try to connect to port 8448. This is easy to set up and will work with the default configuration, provided you set the server_name to match your machine's public DNS hostname.

For a more flexible configuration, you can set up a DNS SRV record. This allows you to run your server on a machine that might not have the same name as your domain name. For example, you might want to run your server at synapse.example.com, but have your Matrix user-ids look like @user:example.com. (A SRV record also allows you to change the port from the default 8448. However, if you are thinking of using a reverse-proxy on the federation port, which is not recommended, be sure to read `Reverse-proxying the federation port`_ first.)

To use a SRV record, first create your SRV record and publish it in DNS. This should have the format _matrix._tcp.<yourdomain.com> <ttl> IN SRV 10 0 <port> <synapse.server.name>. The DNS record should then look something like:

$ dig -t srv _matrix._tcp.example.com
_matrix._tcp.example.com. 3600    IN      SRV     10 0 8448 synapse.example.com.

Note that the server hostname cannot be an alias (CNAME record): it has to point directly to the server hosting the synapse instance.

You can then configure your homeserver to use <yourdomain.com> as the domain in its user-ids, by setting server_name:

python -m synapse.app.homeserver \
    --server-name <yourdomain.com> \
    --config-path homeserver.yaml \
    --generate-config
python -m synapse.app.homeserver --config-path homeserver.yaml

If you've already generated the config file, you need to edit the server_name in your homeserver.yaml file. If you've already started Synapse and a database has been created, you will have to recreate the database.

If all goes well, you should be able to `connect to your server with a client`__, and then join a room via federation. (Try #matrix-dev:matrix.org as a first step. "Matrix HQ"'s sheer size and activity level tends to make even the largest boxes pause for thought.)

Troubleshooting

You can use the federation tester to check if your homeserver is all set: https://matrix.org/federationtester/api/report?server_name=<your_server_name> If any of the attributes under "checks" is false, federation won't work.

The typical failure mode with federation is that when you try to join a room, it is rejected with "401: Unauthorized". Generally this means that other servers in the room couldn't access yours. (Joining a room over federation is a complicated dance which requires connections in both directions).

So, things to check are:

• If you are trying to use a reverse-proxy, read `Reverse-proxying the federation port`_.
• If you are not using a SRV record, check that your server_name (the part of your user-id after the :) matches your hostname, and that port 8448 on that hostname is reachable from outside your network.
• If you are using a SRV record, check that it matches your server_name (it should be _matrix._tcp.<server_name>), and that the port and hostname it specifies are reachable from outside your network.