tileradotorg/synapse
1
0
Fork 0
forked from MirrorHub/synapse
Code Pull requests Activity

README: review comments

Browse source 
Minor updates post-review
This commit is contained in:
Richard van der Hoff 2016-12-02 17:11:58 +00:00
parent 3f23154088
commit 9df84dd22d
1 changed files with 54 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

86
README.rst
View file

@ -53,10 +53,10 @@ generation of fully open and interoperable messaging and VoIP apps for the
internet. internet.
Synapse is a reference "homeserver" implementation of Matrix from the core Synapse is a reference "homeserver" implementation of Matrix from the core
development team at matrix.org, written in Python/Twisted for clarity and development team at matrix.org, written in Python/Twisted. It is intended to
simplicity. It is intended to showcase the concept of Matrix and let folks see showcase the concept of Matrix and let folks see the spec in the context of a
the spec in the context of a codebase and let you run your own homeserver and codebase and let you run your own homeserver and generally help bootstrap the
generally help bootstrap the ecosystem. ecosystem.
In Matrix, every user runs one or more Matrix clients, which connect through to In Matrix, every user runs one or more Matrix clients, which connect through to
a Matrix homeserver. The homeserver stores all their personal chat history and a Matrix homeserver. The homeserver stores all their personal chat history and
@ -69,13 +69,13 @@ etc.
We'd like to invite you to join #matrix:matrix.org (via We'd like to invite you to join #matrix:matrix.org (via
https://matrix.org/docs/projects/try-matrix-now), run a homeserver, take a look https://matrix.org/docs/projects/try-matrix-now), run a homeserver, take a look
at the Matrix spec at https://matrix.org/docs/spec and API docs at at the `Matrix spec <https://matrix.org/docs/spec>`_, and experiment with the
https://matrix.org/docs/api, experiment with the APIs and the demo clients, and `APIs <https://matrix.org/docs/api>`_ and `Client SDKs
report any bugs via github. <http://matrix.org/docs/projects/try-matrix-now.html#client-sdks>`_.
Thanks for using Matrix! Thanks for using Matrix!
[1] End-to-end encryption is currently in beta. [1] End-to-end encryption is currently in beta: `blog post <https://matrix.org/blog/2016/11/21/matrixs-olm-end-to-end-encryption-security-assessment-released-and-implemented-cross-platform-on-riot-at-last>`.
Synapse Installation Synapse Installation
@ -172,25 +172,34 @@ 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 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 matrix-specific hostname here (in the same way that your email address is
probably ``user@example.com`` rather than ``user@email.example.com``) - but probably ``user@example.com`` rather than ``user@email.example.com``) - but
doing so may require more advanced setup - see `Setting up Federation`_. 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 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 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 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 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 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 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. 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 TCP ports: 8008 and 8448. Port 8008 is .. __: `key_management`_
The default configuration exposes two HTTP ports: 8008 and 8448. Port 8008 is
configured without TLS; it is not recommended this be exposed outside your configured without TLS; it is not recommended this be exposed outside your
local network. Port 8448 is configured to use TLS with a self-signed local network. Port 8448 is configured to use TLS with a self-signed
certificate. This is fine for testing with but you will almost certainly want certificate. This is fine for testing with but, to avoid your clients
to use another certificate for production purposes. You can do so by changing complaining about the certificate, you will almost certainly want to use
another certificate for production purposes. (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`` ``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 in ``homeserver.yaml``; alternatively, you can use a reverse-proxy, but be sure
to read `Using a reverse proxy with Synapse`_ when doing so. 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 Registering a user
------------------ ------------------
@ -200,7 +209,7 @@ commandline script.
.. __: `client-user-reg`_ .. __: `client-user-reg`_
To get started, is easiest to use the command line to register new users:: To get started, it is easiest to use the command line to register new users::
$ source ~/.synapse/bin/activate $ source ~/.synapse/bin/activate
$ synctl start # if not already running $ synctl start # if not already running
@ -239,11 +248,11 @@ Connecting to Synapse from a client
=================================== ===================================
The easiest way to try out your new Synapse installation is by connecting to it The easiest way to try out your new Synapse installation is by connecting to it
from a web client. We recommend the one at http://riot.im/app. You will need to from a web client. The easiest option is probably the one at
specify a "Custom server" when you log on or register: set this to http://riot.im/app. You will need to specify a "Custom server" when you log on
``https://localhost:8448`` - remember to specify the port (``:8448``) unless or register: set this to ``https://localhost:8448`` - remember to specify the
you changed the configuration. (Leave the identity server as the default - see port (``:8448``) unless you changed the configuration. (Leave the identity
`Identity servers`_.) server as the default - see `Identity servers`_.)
If all goes well you should at least be able to log in, create a room, and If all goes well you should at least be able to log in, create a room, and
start sending messages. start sending messages.
@ -268,9 +277,9 @@ Your new user name will be formed partly from the ``server_name`` (see
`Configuring synapse`_), and partly from a localpart you specify when you `Configuring synapse`_), and partly from a localpart you specify when you
create the account. Your name will take the form of:: create the account. Your name will take the form of::
@localpart:my.domain.here @localpart:my.domain.name
(pronounced "at localpart on my dot domain dot here"). (pronounced "at localpart on my dot domain dot name").
As when logging in, you will need to specify a "Custom server". Specify your As when logging in, you will need to specify a "Custom server". Specify your
desired ``localpart`` in the 'User name' box. desired ``localpart`` in the 'User name' box.
@ -494,7 +503,7 @@ 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 provided you set the ``server_name`` to match your machine's public DNS
hostname. hostname.
For a more flexible conversation, you can set up a DNS SRV record. This allows 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 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 domain name. For example, you might want to run your server at
``synapse.example.com``, but have your Matrix user-ids look like ``synapse.example.com``, but have your Matrix user-ids look like
@ -522,11 +531,13 @@ 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 in your ``homeserver.yaml`` file. If you've already started Synapse and a
database has been created, you will have to recreate the database. 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, 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 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 step. "Matrix HQ"'s sheer size and activity level tends to make even the
largest boxes pause for thought.) largest boxes pause for thought.)
.. __: `Connecting to Synapse from a client`_
Troubleshooting Troubleshooting
--------------- ---------------
The typical failure mode with federation is that when you try to join a room, The typical failure mode with federation is that when you try to join a room,
@ -587,9 +598,9 @@ Matrix clients without needing to run Synapse with root privileges.
The most important thing to know here is that Matrix clients and other Matrix The most important thing to know here is that Matrix clients and other Matrix
servers do not necessarily need to connect to your server via the same servers do not necessarily need to connect to your server via the same
port. Indeed, clients will use port 443 by default, whereas other servers port. Indeed, clients will use port 443 by default, whereas servers default to
default to port 8448. Where these are different, we refer to the 'client port' port 8448. Where these are different, we refer to the 'client port' and the
and the 'federation port'. 'federation port'.
The next most important thing to know is that using a reverse-proxy on the The next most important thing to know is that using a reverse-proxy on the
federation port has a number of pitfalls. It is possible, but be sure to read federation port has a number of pitfalls. It is possible, but be sure to read
@ -626,9 +637,10 @@ There are two issues to consider before using a reverse-proxy on the federation
port: port:
* Due to the way SSL certificates are managed in the Matrix federation protocol * Due to the way SSL certificates are managed in the Matrix federation protocol
(see `spec <https://matrix.org/docs/spec/server_server/unstable.html#retrieving-server-keys>`_), (see `spec`__), Synapse needs to be configured with the path to the SSL
Synapse needs to be configured with the path to the SSL certificate, *even if certificate, *even if you do not terminate SSL at Synapse*.
you do not terminate SSL at Synapse*.
.. __: `key_management`_
* Synapse does not currently support SNI on the federation protocol * Synapse does not currently support SNI on the federation protocol
(`bug #1491 <https://github.com/matrix-org/synapse/issues/1491>`_), which (`bug #1491 <https://github.com/matrix-org/synapse/issues/1491>`_), which
@ -652,8 +664,12 @@ caveats, you will need to do the following:
certificate file used by your reverse-proxy, and set ``no_tls`` to ``True``. certificate file used by your reverse-proxy, and set ``no_tls`` to ``True``.
(``tls_private_key_path`` will be ignored if ``no_tls`` is ``True``.) (``tls_private_key_path`` will be ignored if ``no_tls`` is ``True``.)
* In your reverse-proxy configuration, if there are other virtual hosts on the * In your reverse-proxy configuration:
same port, make sure that Synapse is the default.
* If there are other virtual hosts on the same port, make sure that the
*default* one uses the certificate configured above.
* Forward ``/_matrix`` to Synapse.
* If your reverse-proxy is not listening on port 8448, publish a SRV record to * If your reverse-proxy is not listening on port 8448, publish a SRV record to
tell other servers how to find you. See `Setting up Federation`_. tell other servers how to find you. See `Setting up Federation`_.
@ -679,6 +695,9 @@ Identity servers have the job of mapping email addresses and other 3rd Party
IDs (3PIDs) to Matrix user IDs, as well as verifying the ownership of 3PIDs IDs (3PIDs) to Matrix user IDs, as well as verifying the ownership of 3PIDs
before creating that mapping. before creating that mapping.
**They are not where accounts or credentials are stored - these live on home
servers. Identity Servers are just for mapping 3rd party IDs to matrix IDs.**
This process is very security-sensitive, as there is obvious risk of spam if it This process is very security-sensitive, as there is obvious risk of spam if it
is too easy to sign up for Matrix accounts or harvest 3PID data. In the longer is too easy to sign up for Matrix accounts or harvest 3PID data. In the longer
term, we hope to create a decentralised system to manage it (`matrix-doc #712 term, we hope to create a decentralised system to manage it (`matrix-doc #712
@ -797,3 +816,6 @@ matrix.org on. The default setting is currently 0.1, which is probably
around a ~700MB footprint. You can dial it down further to 0.02 if around a ~700MB footprint. You can dial it down further to 0.02 if
desired, which targets roughly ~512MB. Conversely you can dial it up if desired, which targets roughly ~512MB. Conversely you can dial it up if
you need performance for lots of users and have a box with a lot of RAM. you need performance for lots of users and have a box with a lot of RAM.
.. _`key_management`: https://matrix.org/docs/spec/server_server/unstable.html#retrieving-server-keys