@@ -1,10 +1,12 @@ | |||
- [Choosing your server name](#choosing-your-server-name) | |||
- [Picking a database engine](#picking-a-database-engine) | |||
- [Installing Synapse](#installing-synapse) | |||
- [Installing from source](#installing-from-source) | |||
- [Platform-Specific Instructions](#platform-specific-instructions) | |||
- [Prebuilt packages](#prebuilt-packages) | |||
- [Setting up Synapse](#setting-up-synapse) | |||
- [TLS certificates](#tls-certificates) | |||
- [Client Well-Known URI](#client-well-known-uri) | |||
- [Email](#email) | |||
- [Registering a user](#registering-a-user) | |||
- [Setting up a TURN server](#setting-up-a-turn-server) | |||
@@ -27,6 +29,25 @@ that your email address is probably `user@example.com` rather than | |||
`user@email.example.com`) - but doing so may require more advanced setup: see | |||
[Setting up Federation](docs/federate.md). | |||
# Picking a database engine | |||
Synapse offers two database engines: | |||
* [PostgreSQL](https://www.postgresql.org) | |||
* [SQLite](https://sqlite.org/) | |||
Almost all installations should opt to use PostgreSQL. Advantages include: | |||
* significant performance improvements due to the superior threading and | |||
caching model, smarter query optimiser | |||
* allowing the DB to be run on separate hardware | |||
For information on how to install and use PostgreSQL, please see | |||
[docs/postgres.md](docs/postgres.md) | |||
By default Synapse uses SQLite and in doing so trades performance for convenience. | |||
SQLite is only recommended in Synapse for testing purposes or for servers with | |||
light workloads. | |||
# Installing Synapse | |||
## Installing from source | |||
@@ -234,9 +255,9 @@ for a number of platforms. | |||
There is an offical synapse image available at | |||
https://hub.docker.com/r/matrixdotorg/synapse which can be used with | |||
the docker-compose file available at [contrib/docker](contrib/docker). Further information on | |||
this including configuration options is available in the README on | |||
hub.docker.com. | |||
the docker-compose file available at [contrib/docker](contrib/docker). Further | |||
information on this including configuration options is available in the README | |||
on hub.docker.com. | |||
Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a | |||
Dockerfile to automate a synapse server in a single Docker image, at | |||
@@ -244,7 +265,8 @@ https://hub.docker.com/r/avhost/docker-matrix/tags/ | |||
Slavi Pantaleev has created an Ansible playbook, | |||
which installs the offical Docker image of Matrix Synapse | |||
along with many other Matrix-related services (Postgres database, riot-web, coturn, mxisd, SSL support, etc.). | |||
along with many other Matrix-related services (Postgres database, Element, coturn, | |||
ma1sd, SSL support, etc.). | |||
For more details, see | |||
https://github.com/spantaleev/matrix-docker-ansible-deploy | |||
@@ -277,22 +299,27 @@ The fingerprint of the repository signing key (as shown by `gpg | |||
/usr/share/keyrings/matrix-org-archive-keyring.gpg`) is | |||
`AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058`. | |||
#### Downstream Debian/Ubuntu packages | |||
#### Downstream Debian packages | |||
For `buster` and `sid`, Synapse is available in the Debian repositories and | |||
it should be possible to install it with simply: | |||
We do not recommend using the packages from the default Debian `buster` | |||
repository at this time, as they are old and suffer from known security | |||
vulnerabilities. You can install the latest version of Synapse from | |||
[our repository](#matrixorg-packages) or from `buster-backports`. Please | |||
see the [Debian documentation](https://backports.debian.org/Instructions/) | |||
for information on how to use backports. | |||
If you are using Debian `sid` or testing, Synapse is available in the default | |||
repositories and it should be possible to install it simply with: | |||
``` | |||
sudo apt install matrix-synapse | |||
``` | |||
There is also a version of `matrix-synapse` in `stretch-backports`. Please see | |||
the [Debian documentation on | |||
backports](https://backports.debian.org/Instructions/) for information on how | |||
to use them. | |||
#### Downstream Ubuntu packages | |||
We do not recommend using the packages in downstream Ubuntu at this time, as | |||
they are old and suffer from known security vulnerabilities. | |||
We do not recommend using the packages in the default Ubuntu repository | |||
at this time, as they are old and suffer from known security vulnerabilities. | |||
The latest version of Synapse can be installed from [our repository](#matrixorg-packages). | |||
### Fedora | |||
@@ -419,6 +446,60 @@ so, you will need to edit `homeserver.yaml`, as follows: | |||
For a more detailed guide to configuring your server for federation, see | |||
[federate.md](docs/federate.md). | |||
## Client Well-Known URI | |||
Setting up the client Well-Known URI is optional but if you set it up, it will | |||
allow users to enter their full username (e.g. `@user:<server_name>`) into clients | |||
which support well-known lookup to automatically configure the homeserver and | |||
identity server URLs. This is useful so that users don't have to memorize or think | |||
about the actual homeserver URL you are using. | |||
The URL `https://<server_name>/.well-known/matrix/client` should return JSON in | |||
the following format. | |||
``` | |||
{ | |||
"m.homeserver": { | |||
"base_url": "https://<matrix.example.com>" | |||
} | |||
} | |||
``` | |||
It can optionally contain identity server information as well. | |||
``` | |||
{ | |||
"m.homeserver": { | |||
"base_url": "https://<matrix.example.com>" | |||
}, | |||
"m.identity_server": { | |||
"base_url": "https://<identity.example.com>" | |||
} | |||
} | |||
``` | |||
To work in browser based clients, the file must be served with the appropriate | |||
Cross-Origin Resource Sharing (CORS) headers. A recommended value would be | |||
`Access-Control-Allow-Origin: *` which would allow all browser based clients to | |||
view it. | |||
In nginx this would be something like: | |||
``` | |||
location /.well-known/matrix/client { | |||
return 200 '{"m.homeserver": {"base_url": "https://<matrix.example.com>"}}'; | |||
add_header Content-Type application/json; | |||
add_header Access-Control-Allow-Origin *; | |||
} | |||
``` | |||
You should also ensure the `public_baseurl` option in `homeserver.yaml` is set | |||
correctly. `public_baseurl` should be set to the URL that clients will use to | |||
connect to your server. This is the same URL you put for the `m.homeserver` | |||
`base_url` above. | |||
``` | |||
public_baseurl: "https://<matrix.example.com>" | |||
``` | |||
@@ -437,7 +518,7 @@ email will be disabled. | |||
## Registering a user | |||
The easiest way to create a new user is to do so from a client like [Riot](https://riot.im). | |||
The easiest way to create a new user is to do so from a client like [Element](https://element.io/). | |||
Alternatively you can do so from the command line if you have installed via pip. | |||
@@ -45,7 +45,7 @@ which handle: | |||
- Eventually-consistent cryptographically secure synchronisation of room | |||
state across a global open network of federated servers and services | |||
- Sending and receiving extensible messages in a room with (optional) | |||
end-to-end encryption[1] | |||
end-to-end encryption | |||
- Inviting, joining, leaving, kicking, banning room members | |||
- Managing user accounts (registration, login, logout) | |||
- Using 3rd Party IDs (3PIDs) such as email addresses, phone numbers, | |||
@@ -82,9 +82,6 @@ at the `Matrix spec <https://matrix.org/docs/spec>`_, and experiment with the | |||
Thanks for using Matrix! | |||
[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>`_. | |||
Support | |||
======= | |||
@@ -115,12 +112,11 @@ Unless you are running a test instance of Synapse on your local machine, in | |||
general, you will need to enable TLS support before you can successfully | |||
connect from a client: see `<INSTALL.md#tls-certificates>`_. | |||
An easy way to get started is to login or register via Riot at | |||
https://riot.im/app/#/login or https://riot.im/app/#/register respectively. | |||
An easy way to get started is to login or register via Element at | |||
https://app.element.io/#/login or https://app.element.io/#/register respectively. | |||
You will need to change the server you are logging into from ``matrix.org`` | |||
and instead specify a Homeserver URL of ``https://<server_name>:8448`` | |||
(or just ``https://<server_name>`` if you are using a reverse proxy). | |||
(Leave the identity server as the default - see `Identity servers`_.) | |||
If you prefer to use another client, refer to our | |||
`client breakdown <https://matrix.org/docs/projects/clients-matrix>`_. | |||
@@ -137,7 +133,7 @@ it, specify ``enable_registration: true`` in ``homeserver.yaml``. (It is then | |||
recommended to also set up CAPTCHA - see `<docs/CAPTCHA_SETUP.md>`_.) | |||
Once ``enable_registration`` is set to ``true``, it is possible to register a | |||
user via `riot.im <https://riot.im/app/#/register>`_ or other Matrix clients. | |||
user via a Matrix client. | |||
Your new user name will be formed partly from the ``server_name``, and partly | |||
from a localpart you specify when you create the account. Your name will take | |||
@@ -183,30 +179,6 @@ versions of synapse. | |||
.. _UPGRADE.rst: UPGRADE.rst | |||
Using PostgreSQL | |||
================ | |||
Synapse offers two database engines: | |||
* `PostgreSQL <https://www.postgresql.org>`_ | |||
* `SQLite <https://sqlite.org/>`_ | |||
Almost all installations should opt to use PostgreSQL. Advantages include: | |||
* significant performance improvements due to the superior threading and | |||
caching model, smarter query optimiser | |||
* allowing the DB to be run on separate hardware | |||
* allowing basic active/backup high-availability with a "hot spare" synapse | |||
pointing at the same DB master, as well as enabling DB replication in | |||
synapse itself. | |||
For information on how to install and use PostgreSQL, please see | |||
`docs/postgres.md <docs/postgres.md>`_. | |||
By default Synapse uses SQLite and in doing so trades performance for convenience. | |||
SQLite is only recommended in Synapse for testing purposes or for servers with | |||
light workloads. | |||
.. _reverse-proxy: | |||
Using a reverse proxy with Synapse | |||
@@ -255,10 +227,9 @@ email address. | |||
Password reset | |||
============== | |||
If a user has registered an email address to their account using an identity | |||
server, they can request a password-reset token via clients such as Riot. | |||
A manual password reset can be done via direct database access as follows. | |||
Users can reset their password through their client. Alternatively, a server admin | |||
can reset a users password using the `admin API <docs/admin_api/user_admin_api.rst#reset-password>`_ | |||
or by directly editing the database as shown below. | |||
First calculate the hash of the new password:: | |||
@@ -0,0 +1 @@ | |||
Document how to set up a Client Well-Known file and fix several pieces of outdated documentation. |
@@ -1,3 +1,13 @@ | |||
matrix-synapse-py3 (1.xx.0) stable; urgency=medium | |||
[ Synapse Packaging team ] | |||
* New synapse release 1.xx.0. | |||
[ Aaron Raimist ] | |||
* Fix outdated documentation for SYNAPSE_CACHE_FACTOR | |||
-- Synapse Packaging team <packages@matrix.org> XXXXX | |||
matrix-synapse-py3 (1.17.0) stable; urgency=medium | |||
* New synapse release 1.17.0. | |||
@@ -1,2 +1,2 @@ | |||
# Specify environment variables used when running Synapse | |||
# SYNAPSE_CACHE_FACTOR=1 (default) | |||
# SYNAPSE_CACHE_FACTOR=0.5 (default) |
@@ -46,19 +46,20 @@ Configuration file may be generated as follows: | |||
## ENVIRONMENT | |||
* `SYNAPSE_CACHE_FACTOR`: | |||
Synapse's architecture is quite RAM hungry currently - a lot of | |||
recent room data and metadata is deliberately cached in RAM in | |||
order to speed up common requests. This will be improved in | |||
future, but for now the easiest way to either reduce the RAM usage | |||
(at the risk of slowing things down) is to set the | |||
SYNAPSE_CACHE_FACTOR environment variable. Roughly speaking, a | |||
SYNAPSE_CACHE_FACTOR of 1.0 will max out at around 3-4GB of | |||
resident memory - this is what we currently run the 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 | |||
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. | |||
Synapse's architecture is quite RAM hungry currently - we deliberately | |||
cache a lot of recent room data and metadata in RAM in order to speed up | |||
common requests. We'll improve this in the future, but for now the easiest | |||
way to either reduce the RAM usage (at the risk of slowing things down) | |||
is to set the almost-undocumented ``SYNAPSE_CACHE_FACTOR`` environment | |||
variable. The default is 0.5, which can be decreased to reduce RAM usage | |||
in memory constrained enviroments, or increased if performance starts to | |||
degrade. | |||
However, degraded performance due to a low cache factor, common on | |||
machines with slow disks, often leads to explosions in memory use due | |||
backlogged requests. In this case, reducing the cache factor will make | |||
things worse. Instead, try increasing it drastically. 2.0 is a good | |||
starting value. | |||
## COPYRIGHT | |||
@@ -10,5 +10,16 @@ | |||
# homeserver.yaml. Instead, if you are starting from scratch, please generate | |||
# a fresh config using Synapse by following the instructions in INSTALL.md. | |||
# Configuration options that take a time period can be set using a number | |||
# followed by a letter. Letters have the following meanings: | |||
# s = second | |||
# m = minute | |||
# h = hour | |||
# d = day | |||
# w = week | |||
# y = year | |||
# For example, setting redaction_retention_period: 5m would remove redacted | |||
# messages from the database after 5 minutes, rather than 5 months. | |||
################################################################################ | |||
@@ -188,6 +188,9 @@ to do step 2. | |||
It is safe to at any time kill the port script and restart it. | |||
Note that the database may take up significantly more (25% - 100% more) | |||
space on disk after porting to Postgres. | |||
### Using the port script | |||
Firstly, shut down the currently running synapse server and copy its | |||
@@ -10,6 +10,17 @@ | |||
# homeserver.yaml. Instead, if you are starting from scratch, please generate | |||
# a fresh config using Synapse by following the instructions in INSTALL.md. | |||
# Configuration options that take a time period can be set using a number | |||
# followed by a letter. Letters have the following meanings: | |||
# s = second | |||
# m = minute | |||
# h = hour | |||
# d = day | |||
# w = week | |||
# y = year | |||
# For example, setting redaction_retention_period: 5m would remove redacted | |||
# messages from the database after 5 minutes, rather than 5 months. | |||
################################################################################ | |||
# Configuration file for Synapse. | |||
@@ -1149,24 +1160,6 @@ account_validity: | |||
# | |||
#default_identity_server: https://matrix.org | |||
# The list of identity servers trusted to verify third party | |||
# identifiers by this server. | |||
# | |||
# Also defines the ID server which will be called when an account is | |||
# deactivated (one will be picked arbitrarily). | |||
# | |||
# Note: This option is deprecated. Since v0.99.4, Synapse has tracked which identity | |||
# server a 3PID has been bound to. For 3PIDs bound before then, Synapse runs a | |||
# background migration script, informing itself that the identity server all of its | |||
# 3PIDs have been bound to is likely one of the below. | |||
# | |||
# As of Synapse v1.4.0, all other functionality of this option has been deprecated, and | |||
# it is now solely used for the purposes of the background migration script, and can be | |||
# removed once it has run. | |||
#trusted_third_party_id_servers: | |||
# - matrix.org | |||
# - vector.im | |||
# Handle threepid (email/phone etc) registration and password resets through a set of | |||
# *trusted* identity servers. Note that this allows the configured identity server to | |||
# reset passwords for accounts! | |||
@@ -333,24 +333,6 @@ class RegistrationConfig(Config): | |||
# | |||
#default_identity_server: https://matrix.org | |||
# The list of identity servers trusted to verify third party | |||
# identifiers by this server. | |||
# | |||
# Also defines the ID server which will be called when an account is | |||
# deactivated (one will be picked arbitrarily). | |||
# | |||
# Note: This option is deprecated. Since v0.99.4, Synapse has tracked which identity | |||
# server a 3PID has been bound to. For 3PIDs bound before then, Synapse runs a | |||
# background migration script, informing itself that the identity server all of its | |||
# 3PIDs have been bound to is likely one of the below. | |||
# | |||
# As of Synapse v1.4.0, all other functionality of this option has been deprecated, and | |||
# it is now solely used for the purposes of the background migration script, and can be | |||
# removed once it has run. | |||
#trusted_third_party_id_servers: | |||
# - matrix.org | |||
# - vector.im | |||
# Handle threepid (email/phone etc) registration and password resets through a set of | |||
# *trusted* identity servers. Note that this allows the configured identity server to | |||
# reset passwords for accounts! | |||