diff options
| -rw-r--r-- | README.rst | 105 |
1 files changed, 55 insertions, 50 deletions
diff --git a/README.rst b/README.rst index de45cd6d24..a54304cd55 100644 --- a/README.rst +++ b/README.rst @@ -483,69 +483,74 @@ versions of synapse. Setting up Federation ===================== -In order for other homeservers to send messages to your server, it will need to -be publicly visible on the internet, and they will need to know its host name. -You have two choices here, which will influence the form of your Matrix user -IDs: - -1) Use the machine's own hostname as available on public DNS in the form of - its A records. This is easier to set up initially, perhaps for - testing, but lacks the flexibility of SRV. - -2) Set up a SRV record for your domain name. This requires you create a SRV - record in DNS, but gives the flexibility to run the server on your own - choice of TCP port, on a machine that might not be the same name as the - domain name. - -For the first form, simply pass the required hostname (of the machine) as the ---server-name parameter:: +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 conversation, 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, 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. + +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 machine.my.domain.name \ + --server-name <yourdomain.com> \ --config-path homeserver.yaml \ --generate-config python -m synapse.app.homeserver --config-path homeserver.yaml -Alternatively, you can run ``synctl start`` to guide you through the process. - -For the second form, first create your SRV record and publish it in DNS. This -needs to be named _matrix._tcp.YOURDOMAIN, and point at at least one hostname -and port where the server is running. (At the current time synapse does not -support clustering multiple servers into a single logical homeserver). The DNS -record would then look something like:: - - $ dig -t srv _matrix._tcp.machine.my.domain.name - _matrix._tcp IN SRV 10 0 8448 machine.my.domain.name. - - -At this point, you should then run the homeserver with the hostname of this -SRV record, as that is the name other machines will expect it to have:: - - python -m synapse.app.homeserver \ - --server-name YOURDOMAIN \ - --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 you ```homeserver.yaml``` file. If you've already started Synapse and a +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. -You may additionally want to pass one or more "-v" options, in order to -increase the verbosity of logging output; at least for initial testing. +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 +--------------- +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. Running a Demo Federation of Synapses ------------------------------------- If you want to get up and running quickly with a trio of homeservers in a -private federation (``localhost:8080``, ``localhost:8081`` and -``localhost:8082``) which you can then access through the webclient running at -http://localhost:8080. Simply run:: - - demo/start.sh - -This is mainly useful just for development purposes. +private federation, there is a script in the ``demo`` directory. This is mainly +useful just for development purposes. See `<demo/README>`_. Using PostgreSQL |