You can use Synapse with a forward or outbound proxy. An example of when
-this is necessary is in corporate environments behind a DMZ (demilitarized zone).
-Synapse supports routing outbound HTTP(S) requests via a proxy. Only HTTP(S)
-proxy is supported, not SOCKS proxy or anything else.
The http_proxy, https_proxy, no_proxy environment variables are used to
-specify proxy settings. The environment variable is not case sensitive.
-
-
http_proxy: Proxy server to use for HTTP requests.
-
https_proxy: Proxy server to use for HTTPS requests.
-
no_proxy: Comma-separated list of hosts, IP addresses, or IP ranges in CIDR
-format which should not use the proxy. Synapse will directly connect to these hosts.
-
-
The http_proxy and https_proxy environment variables have the form: [scheme://][<username>:<password>@]<host>[:<port>]
-
-
-
Supported schemes are http:// and https://. The default scheme is http://
-for compatibility reasons; it is recommended to set a scheme. If scheme is set
-to https:// the connection uses TLS between Synapse and the proxy.
-
NOTE: Synapse validates the certificates. If the certificate is not
-valid, then the connection is dropped.
-
-
-
Default port if not given is 1080.
-
-
-
Username and password are optional and will be used to authenticate against
-the proxy.
NOTE:
-Synapse does not apply the IP blacklist to connections through the proxy (since
-the DNS resolution is done by the proxy). It is expected that the proxy or firewall
-will apply blacklisting of IP addresses.
If a proxy server is used with TLS (HTTPS) and no connections are established,
-it is most likely due to the proxy's certificates. To test this, the validation
-in Synapse can be deactivated.
-
NOTE: This has an impact on security and is for testing purposes only!
-
To deactivate the certificate validation, the following setting must be made in
-homserver.yaml.
It is important to choose the name for your server before you install Synapse,
-because it cannot be changed later.
-
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 user@example.com rather than
-user@email.example.com) - but doing so may require more advanced setup: see
-Setting up Federation.
There is an official synapse image available at
-https://hub.docker.com/r/matrixdotorg/synapse which can be used with
-the docker-compose file available at
-contrib/docker.
-Further information on this including configuration options is available in the README
-on hub.docker.com.
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, Element, coturn,
-ma1sd, SSL support, etc.).
-For more details, see
-https://github.com/spantaleev/matrix-docker-ansible-deploy
The fingerprint of the repository signing key (as shown by gpg /usr/share/keyrings/matrix-org-archive-keyring.gpg) is
-AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058.
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 or from buster-backports. Please
-see the Debian documentation
-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:
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.
pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):
-
sudo pip install --upgrade pip
-
-
If you encounter an error with lib bcrypt causing an Wrong ELF Class:
-ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly
-compile it under the right architecture. (This should not be needed if
-installing under virtualenv):
As of OpenBSD 6.7 Synapse is available as a pre-compiled binary. The filesystem
-underlying the homeserver directory (defaults to /var/synapse) has to be
-mounted with wxallowed (cf. mount(8)), so creating a separate filesystem
-and mounting it to /var/synapse should be taken into consideration.
This will download Synapse from PyPI
-and install it, along with the python libraries it uses, into a virtual environment
-under ~/synapse/env. Feel free to pick a different directory if you
-prefer.
-
This Synapse installation can then be later upgraded by using pip again with the
-update flag:
... substituting an appropriate value for --server-name.
-
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 homeserver to
-identify itself to other homeserver, 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 homeserver's keys, you may find that other homeserver 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).
-
To actually run your new homeserver, pick a working directory for Synapse to
-run (e.g. ~/synapse), and:
-
cd ~/synapse
-source env/bin/activate
-synctl start
-
Synapse is written in Python but some of the libraries it uses are written in
-C. So before we can install Synapse itself we need a working C compiler and the
-header files for Python C extensions.
A port of Synapse is available under net/synapse. The filesystem
-underlying the homeserver directory (defaults to /var/synapse) has to be
-mounted with wxallowed (cf. mount(8)), so creating a separate filesystem
-and mounting it to /var/synapse should be taken into consideration.
-
To be able to build Synapse's dependency on python the WRKOBJDIR
-(cf. bsd.port.mk(5)) for building python, too, needs to be on a filesystem
-mounted with wxallowed (cf. mount(8)).
-
Creating a WRKOBJDIR for building python under /usr/local (which on a
-default OpenBSD installation is mounted with wxallowed):
-
doas mkdir /usr/local/pobj_wxallowed
-
-
Assuming PORTS_PRIVSEP=Yes (cf. bsd.port.mk(5)) and SUDO=doas are
-configured in /etc/mk.conf:
-
doas chown _pbuild:_pbuild /usr/local/pobj_wxallowed
-
By default Synapse uses an SQLite database and in doing so trades
-performance for convenience. Almost all installations should opt to use PostgreSQL
-instead. 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 in Synapse, please see
-Using Postgres
-
SQLite is only acceptable for testing purposes. SQLite should not be used in
-a production server. Synapse will perform poorly when using
-SQLite, especially when participating in large rooms.
The default configuration exposes a single HTTP port on the local
-interface: http://localhost:8008. It is suitable for local testing,
-but for any practical use, you will need Synapse's APIs to be served
-over HTTPS.
-
The recommended way to do so is to set up a reverse proxy on port
-8448. You can find documentation on doing so in
-the reverse proxy documentation.
-
Alternatively, you can configure Synapse to expose an HTTPS port. To do
-so, you will need to edit homeserver.yaml, as follows:
-
-
First, under the listeners section, uncomment the configuration for the
-TLS-enabled listener. (Remove the hash sign (#) at the start of
-each line). The relevant lines are like this:
You will also need to uncomment the tls_certificate_path and
-tls_private_key_path lines under the TLS section. You will need to manage
-provisioning of these certificates yourself.
-
If you are using your own certificate, be sure to use a .pem file that
-includes the full certificate chain including any intermediate certificates
-(for instance, if using certbot, use fullchain.pem as your certificate, not
-cert.pem).
-
-
-
For a more detailed guide to configuring your server for federation, see
-Federation.
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.
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.
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.
It is desirable for Synapse to have the capability to send email. This allows
-Synapse to send password reset emails, send verifications when an email address
-is added to a user's account, and send email notifications to users when they
-receive new messages.
-
To configure an SMTP server for Synapse, modify the configuration section
-headed email, and be sure to have at least the smtp_host, smtp_port
-and notif_from fields filled out. You may also need to set smtp_user,
-smtp_pass, and require_transport_security.
-
If email is not configured, password reset, registration and notifications via
-email will be disabled.
The easiest way to create a new user is to do so from a client like Element.
-
Alternatively, you can do so from the command line. This can be done as follows:
-
-
If synapse was installed via pip, activate the virtualenv as follows (if Synapse was
-installed via a prebuilt package, register_new_matrix_user should already be
-on the search path):
-
cd ~/synapse
-source env/bin/activate
-synctl start # if not already running
-
This will prompt you to add details for the new user, and will then connect to
-the running Synapse to create the new user. For example:
-
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, including admin accounts,
-on your server even if enable_registration is false.
Synapse includes support for previewing URLs, which is disabled by default. To
-turn it on you must enable the url_preview_enabled: True config parameter
-and explicitly specify the IP ranges that Synapse is not allowed to spider for
-previewing in the url_preview_ip_range_blacklist configuration parameter.
-This is critical from a security perspective to stop arbitrary Matrix users
-spidering 'internal' URLs on your network. At the very least we recommend that
-your loopback and RFC1918 IP addresses are blacklisted.
-
This also requires the optional lxml python dependency to be installed. This
-in turn requires the libxml2 library to be available - on Debian/Ubuntu this
-means apt-get install libxml2-dev, or equivalent for your OS.
pip seems to leak lots of memory during installation. For instance, a Linux
-host with 512MB of RAM may run out of memory whilst installing Twisted. If this
-happens, you will have to individually install the dependencies which are
-failing, e.g.: