From d2d9645a32a0eb7b5b97db02ebab27105974e050 Mon Sep 17 00:00:00 2001 From: erikjohnston Date: Tue, 6 Feb 2024 16:35:44 +0000 Subject: deploy: 7c805f00a787b53b0eacddb9cb4b5470b9c8d135 --- v1.101/setup/forward_proxy.html | 279 +++++++++++++++++ v1.101/setup/installation.html | 643 ++++++++++++++++++++++++++++++++++++++++ v1.101/setup/turn/coturn.html | 366 +++++++++++++++++++++++ v1.101/setup/turn/eturnal.html | 339 +++++++++++++++++++++ 4 files changed, 1627 insertions(+) create mode 100644 v1.101/setup/forward_proxy.html create mode 100644 v1.101/setup/installation.html create mode 100644 v1.101/setup/turn/coturn.html create mode 100644 v1.101/setup/turn/eturnal.html (limited to 'v1.101/setup') diff --git a/v1.101/setup/forward_proxy.html b/v1.101/setup/forward_proxy.html new file mode 100644 index 0000000000..e66e901857 --- /dev/null +++ b/v1.101/setup/forward_proxy.html @@ -0,0 +1,279 @@ + + + + + + Configuring a Forward/Outbound Proxy - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + +
+
+ +
+ +
+ +

Using a forward proxy with Synapse

+

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.

+

Configure

+

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.

    +
  • +
+

Examples

+
    +
  • HTTP_PROXY=http://USERNAME:PASSWORD@10.0.1.1:8080/
  • +
  • HTTPS_PROXY=http://USERNAME:PASSWORD@proxy.example.com:8080/
  • +
  • NO_PROXY=master.hostname.example.com,10.1.0.0/16,172.30.0.0/16
  • +
+

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.

+

Connection types

+

The proxy will be used for:

+
    +
  • push
  • +
  • url previews
  • +
  • phone-home stats
  • +
  • recaptcha validation
  • +
  • CAS auth validation
  • +
  • OpenID Connect
  • +
  • Outbound federation
  • +
  • Federation (checking public key revocation)
  • +
  • Fetching public keys of other servers
  • +
  • Downloading remote media
  • +
+

It will not be used for:

+
    +
  • Application Services
  • +
  • Identity servers
  • +
  • In worker configurations +
      +
    • connections between workers
    • +
    • connections from workers to Redis
    • +
    +
  • +
+

Troubleshooting

+

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 added to +your homserver.yaml.

+
use_insecure_ssl_client_just_for_testing_do_not_use: true
+
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + diff --git a/v1.101/setup/installation.html b/v1.101/setup/installation.html new file mode 100644 index 0000000000..810df5c0f3 --- /dev/null +++ b/v1.101/setup/installation.html @@ -0,0 +1,643 @@ + + + + + + Installation - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + +
+
+ +
+ +
+ +

Installation Instructions

+

Choosing your server name

+

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.

+

Installing Synapse

+

Prebuilt packages

+

Prebuilt packages are available for a number of platforms. These are recommended +for most users.

+

Docker images and Ansible playbooks

+

There is an official synapse image available at +https://hub.docker.com/r/vectorim/synapse or at ghcr.io/element-hq/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.

+

Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a +Dockerfile to automate a synapse server in a single Docker image, at +https://hub.docker.com/r/avhost/docker-matrix/tags/

+

Slavi Pantaleev has created an Ansible playbook, +which installs the official 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

+

Debian/Ubuntu

+
Matrix.org packages
+

Matrix.org provides Debian/Ubuntu packages of Synapse, for the amd64 +architecture via https://packages.matrix.org/debian/.

+

To install the latest release:

+

TODO UPDATE ALL THIS

+
sudo apt install -y lsb-release wget apt-transport-https
+sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
+echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" |
+    sudo tee /etc/apt/sources.list.d/matrix-org.list
+sudo apt update
+sudo apt install matrix-synapse-py3
+
+

Packages are also published for release candidates. To enable the prerelease +channel, add prerelease to the sources.list line. For example:

+
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
+echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main prerelease" |
+    sudo tee /etc/apt/sources.list.d/matrix-org.list
+sudo apt update
+sudo apt install matrix-synapse-py3
+
+

The fingerprint of the repository signing key (as shown by gpg /usr/share/keyrings/matrix-org-archive-keyring.gpg) is +AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058.

+

When installing with Debian packages, you might prefer to place files in +/etc/matrix-synapse/conf.d/ to override your configuration without editing +the main configuration file at /etc/matrix-synapse/homeserver.yaml. +By doing that, you won't be asked if you want to replace your configuration +file when you upgrade the Debian package to a later version.

+
Downstream Debian packages
+

Andrej Shadura maintains a +matrix-synapse package in +the Debian repositories. +For bookworm and sid, it can be installed simply with:

+
sudo apt install matrix-synapse
+
+

Synapse is also available in bullseye-backports. Please +see the Debian documentation +for information on how to use backports.

+

matrix-synapse is no longer maintained for buster and older.

+
Downstream Ubuntu packages
+

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.

+

Fedora

+

Synapse is in the Fedora repositories as +matrix-synapse:

+
sudo dnf install matrix-synapse
+
+

Additionally, Oleg Girko provides Fedora RPMs at +https://obs.infoserver.lv/project/monitor/matrix-synapse

+

OpenSUSE

+

Synapse is in the OpenSUSE repositories as +matrix-synapse:

+
sudo zypper install matrix-synapse
+
+

SUSE Linux Enterprise Server

+

Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at +https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/

+

ArchLinux

+

The quickest way to get up and running with ArchLinux is probably with the package provided by ArchLinux +https://archlinux.org/packages/extra/x86_64/matrix-synapse/, which should pull in most of +the necessary dependencies.

+

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):

+
sudo pip uninstall py-bcrypt
+sudo pip install py-bcrypt
+
+

Alpine Linux

+

6543 maintains Synapse packages for Alpine Linux in the community repository. Install with:

+
sudo apk add synapse
+
+

Void Linux

+

Synapse can be found in the void repositories as +'synapse':

+
xbps-install -Su
+xbps-install -S synapse
+
+

FreeBSD

+

Synapse can be installed via FreeBSD Ports or Packages contributed by Brendan Molloy from:

+
    +
  • Ports: cd /usr/ports/net-im/py-matrix-synapse && make install clean
  • +
  • Packages: pkg install py38-matrix-synapse
  • +
+

OpenBSD

+

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.

+

Installing Synapse:

+
doas pkg_add synapse
+
+

NixOS

+

Robin Lambertz has packaged Synapse for NixOS at: +https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/matrix/synapse.nix

+

Installing as a Python module from PyPI

+

It's also possible to install Synapse as a Python module from PyPI.

+

When following this route please make sure that the Platform-specific prerequisites are already installed.

+

System requirements:

+
    +
  • POSIX-compliant system (tested on Linux & OS X)
  • +
  • Python 3.8 or later, up to Python 3.11.
  • +
  • At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org
  • +
+

If building on an uncommon architecture for which pre-built wheels are +unavailable, you will need to have a recent Rust compiler installed. The easiest +way of installing the latest version is to use rustup.

+

To install the Synapse homeserver run:

+
mkdir -p ~/synapse
+virtualenv -p python3 ~/synapse/env
+source ~/synapse/env/bin/activate
+pip install --upgrade pip
+pip install --upgrade setuptools
+pip install matrix-synapse
+
+

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:

+
source ~/synapse/env/bin/activate
+pip install -U matrix-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 and choosing whether +or not to report usage statistics (hostname, Synapse version, uptime, total +users, etc.) to the developers via the --report-stats argument.

+

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
+
+

Platform-specific prerequisites

+

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.

+
Debian/Ubuntu/Raspbian
+

Installing prerequisites on Ubuntu or Debian:

+
sudo apt install build-essential python3-dev libffi-dev \
+                     python3-pip python3-setuptools sqlite3 \
+                     libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev
+
+
ArchLinux
+

Installing prerequisites on ArchLinux:

+
sudo pacman -S base-devel python python-pip \
+               python-setuptools python-virtualenv sqlite3 icu
+
+
CentOS/Fedora
+

Installing prerequisites on CentOS or Fedora Linux:

+
sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
+                 libwebp-devel libxml2-devel libxslt-devel libpq-devel \
+                 python3-virtualenv libffi-devel openssl-devel python3-devel \
+                 libicu-devel
+sudo dnf groupinstall "Development Tools"
+
+
macOS
+

Installing prerequisites on macOS:

+

You may need to install the latest Xcode developer tools:

+
xcode-select --install
+
+

Some extra dependencies may be needed. You can use Homebrew (https://brew.sh) for them.

+

You may need to install icu, and make the icu binaries and libraries accessible. +Please follow the official instructions of PyICU to do so.

+

If you're struggling to get icu discovered, and see:

+
  RuntimeError:
+  Please install pkg-config on your system or set the ICU_VERSION environment
+  variable to the version of ICU you have installed.
+
+

despite it being installed and having your PATH updated, you can omit this dependency by +not specifying --extras all to poetry. If using postgres, you can install Synapse via +poetry install --extras saml2 --extras oidc --extras postgres --extras opentracing --extras redis --extras sentry. +ICU is not a hard dependency on getting a working installation.

+

On ARM-based Macs you may also need to install libjpeg and libpq:

+
 brew install jpeg libpq
+
+

On macOS Catalina (10.15) you may need to explicitly install OpenSSL +via brew and inform pip about it so that psycopg2 builds:

+
brew install openssl@1.1
+export LDFLAGS="-L/usr/local/opt/openssl/lib"
+export CPPFLAGS="-I/usr/local/opt/openssl/include"
+
+
OpenSUSE
+

Installing prerequisites on openSUSE:

+
sudo zypper in -t pattern devel_basis
+sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
+               python-devel libffi-devel libopenssl-devel libjpeg62-devel \
+               libicu-devel
+
+
OpenBSD
+

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
+
+

Setting the WRKOBJDIR for building python:

+
echo WRKOBJDIR_lang/python/3.7=/usr/local/pobj_wxallowed  \\nWRKOBJDIR_lang/python/2.7=/usr/local/pobj_wxallowed >> /etc/mk.conf
+
+

Building Synapse:

+
cd /usr/ports/net/synapse
+make install
+
+
Windows
+

Running Synapse natively on Windows is not officially supported.

+

If you wish to run or develop Synapse on Windows, the Windows Subsystem for +Linux provides a Linux environment which is capable of using the Debian, Fedora, +or source installation methods. More information about WSL can be found at +https://docs.microsoft.com/en-us/windows/wsl/install for Windows 10/11 and +https://docs.microsoft.com/en-us/windows/wsl/install-on-server for +Windows Server.

+

Setting up Synapse

+

Once you have installed synapse as above, you will need to configure it.

+

Using PostgreSQL

+

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.

+

TLS certificates

+

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 option, add the configuration for the +TLS-enabled listener like so:
  • +
+
listeners:
+  - port: 8448
+    type: http
+    tls: true
+    resources:
+      - names: [client, federation]
+
+
    +
  • +

    You will also need to add the options tls_certificate_path and +tls_private_key_path. to your configuration file. You will need to manage provisioning of +these certificates yourself.

    +
  • +
  • +

    You can find more information about these options as well as how to configure synapse in the +configuration manual.

    +

    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.

+

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>"}}';
+    default_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>"
+
+

Email

+

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.

+

Registering a user

+

One way to create a new user is to do so from a client like +Element. This requires registration to be enabled via +the +enable_registration +setting.

+

Alternatively, you can create new users from the command line. This can be done as follows:

+
    +
  1. 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
    +
    +
  2. +
  3. Run the following command: +
    register_new_matrix_user -c homeserver.yaml
    +
    +
  4. +
+

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, +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.

+

Setting up a TURN server

+

For reliable VoIP calls to be routed via this homeserver, you MUST configure +a TURN server. See TURN setup for details.

+

URL previews

+

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.

+

Troubleshooting Installation

+

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.:

+
pip install twisted
+
+

If you have any other problems, feel free to ask in +#synapse:matrix.org.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + diff --git a/v1.101/setup/turn/coturn.html b/v1.101/setup/turn/coturn.html new file mode 100644 index 0000000000..bc91834882 --- /dev/null +++ b/v1.101/setup/turn/coturn.html @@ -0,0 +1,366 @@ + + + + + + coturn TURN server - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + +
+
+ +
+ +
+ +

coturn TURN server

+

The following sections describe how to install coturn (which implements the TURN REST API).

+

coturn setup

+

Initial installation

+

The TURN daemon coturn is available from a variety of sources such as native package managers, or installation from source.

+

Debian and Ubuntu based distributions

+

Just install the debian package:

+
sudo apt install coturn
+
+

This will install and start a systemd service called coturn.

+

Source installation

+
    +
  1. +

    Download the latest release from github. Unpack it and cd into the directory.

    +
  2. +
  3. +

    Configure it:

    +
    ./configure
    +
    +

    You may need to install libevent2: if so, you should do so in +the way recommended by your operating system. You can ignore +warnings about lack of database support: a database is unnecessary +for this purpose.

    +
  4. +
  5. +

    Build and install it:

    +
    make
    +sudo make install
    +
    +
  6. +
+

Configuration

+
    +
  1. +

    Create or edit the config file in /etc/turnserver.conf. The relevant +lines, with example values, are:

    +
    use-auth-secret
    +static-auth-secret=[your secret key here]
    +realm=turn.myserver.org
    +
    +

    See turnserver.conf for explanations of the options. One way to generate +the static-auth-secret is with pwgen:

    +
    pwgen -s 64 1
    +
    +

    A realm must be specified, but its value is somewhat arbitrary. (It is +sent to clients as part of the authentication flow.) It is conventional to +set it to be your server name.

    +
  2. +
  3. +

    You will most likely want to configure coturn to write logs somewhere. The +easiest way is normally to send them to the syslog:

    +
    syslog
    +
    +

    (in which case, the logs will be available via journalctl -u coturn on a +systemd system). Alternatively, coturn can be configured to write to a +logfile - check the example config file supplied with coturn.

    +
  4. +
  5. +

    Consider your security settings. TURN lets users request a relay which will +connect to arbitrary IP addresses and ports. The following configuration is +suggested as a minimum starting point:

    +
    # VoIP traffic is all UDP. There is no reason to let users connect to arbitrary TCP endpoints via the relay.
    +no-tcp-relay
    +
    +# don't let the relay ever try to connect to private IP address ranges within your network (if any)
    +# given the turn server is likely behind your firewall, remember to include any privileged public IPs too.
    +denied-peer-ip=10.0.0.0-10.255.255.255
    +denied-peer-ip=192.168.0.0-192.168.255.255
    +denied-peer-ip=172.16.0.0-172.31.255.255
    +
    +# recommended additional local peers to block, to mitigate external access to internal services.
    +# https://www.rtcsec.com/article/slack-webrtc-turn-compromise-and-bug-bounty/#how-to-fix-an-open-turn-relay-to-address-this-vulnerability
    +no-multicast-peers
    +denied-peer-ip=0.0.0.0-0.255.255.255
    +denied-peer-ip=100.64.0.0-100.127.255.255
    +denied-peer-ip=127.0.0.0-127.255.255.255
    +denied-peer-ip=169.254.0.0-169.254.255.255
    +denied-peer-ip=192.0.0.0-192.0.0.255
    +denied-peer-ip=192.0.2.0-192.0.2.255
    +denied-peer-ip=192.88.99.0-192.88.99.255
    +denied-peer-ip=198.18.0.0-198.19.255.255
    +denied-peer-ip=198.51.100.0-198.51.100.255
    +denied-peer-ip=203.0.113.0-203.0.113.255
    +denied-peer-ip=240.0.0.0-255.255.255.255
    +
    +# special case the turn server itself so that client->TURN->TURN->client flows work
    +# this should be one of the turn server's listening IPs
    +allowed-peer-ip=10.0.0.1
    +
    +# consider whether you want to limit the quota of relayed streams per user (or total) to avoid risk of DoS.
    +user-quota=12 # 4 streams per video call, so 12 streams = 3 simultaneous relayed calls per user.
    +total-quota=1200
    +
    +
  6. +
  7. +

    Also consider supporting TLS/DTLS. To do this, add the following settings +to turnserver.conf:

    +
    # TLS certificates, including intermediate certs.
    +# For Let's Encrypt certificates, use `fullchain.pem` here.
    +cert=/path/to/fullchain.pem
    +
    +# TLS private key file
    +pkey=/path/to/privkey.pem
    +
    +# Ensure the configuration lines that disable TLS/DTLS are commented-out or removed
    +#no-tls
    +#no-dtls
    +
    +

    In this case, replace the turn: schemes in the turn_uris settings below +with turns:.

    +

    We recommend that you only try to set up TLS/DTLS once you have set up a +basic installation and got it working.

    +

    NB: If your TLS certificate was provided by Let's Encrypt, TLS/DTLS will +not work with any Matrix client that uses Chromium's WebRTC library. This +currently includes Element Android & iOS; for more details, see their +respective +issues as well as the underlying +WebRTC issue. +Consider using a ZeroSSL certificate for your TURN server as a working alternative.

    +
  8. +
  9. +

    Ensure your firewall allows traffic into the TURN server on the ports +you've configured it to listen on (By default: 3478 and 5349 for TURN +traffic (remember to allow both TCP and UDP traffic), and ports 49152-65535 +for the UDP relay.)

    +
  10. +
  11. +

    If your TURN server is behind NAT, the NAT gateway must have an external, +publicly-reachable IP address. You must configure coturn to advertise that +address to connecting clients:

    +
    external-ip=EXTERNAL_NAT_IPv4_ADDRESS
    +
    +

    You may optionally limit the TURN server to listen only on the local +address that is mapped by NAT to the external address:

    +
    listening-ip=INTERNAL_TURNSERVER_IPv4_ADDRESS
    +
    +

    If your NAT gateway is reachable over both IPv4 and IPv6, you may +configure coturn to advertise each available address:

    +
    external-ip=EXTERNAL_NAT_IPv4_ADDRESS
    +external-ip=EXTERNAL_NAT_IPv6_ADDRESS
    +
    +

    When advertising an external IPv6 address, ensure that the firewall and +network settings of the system running your TURN server are configured to +accept IPv6 traffic, and that the TURN server is listening on the local +IPv6 address that is mapped by NAT to the external IPv6 address.

    +
  12. +
  13. +

    (Re)start the turn server:

    +
      +
    • +

      If you used the Debian package (or have set up a systemd unit yourself):

      +
      sudo systemctl restart coturn
      +
      +
    • +
    • +

      If you built from source:

      +
      /usr/local/bin/turnserver -o
      +
      +
    • +
    +
  14. +
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + diff --git a/v1.101/setup/turn/eturnal.html b/v1.101/setup/turn/eturnal.html new file mode 100644 index 0000000000..c59606552c --- /dev/null +++ b/v1.101/setup/turn/eturnal.html @@ -0,0 +1,339 @@ + + + + + + eturnal TURN server - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + +
+
+ +
+ +
+ +

eturnal TURN server

+

The following sections describe how to install eturnal +(which implements the TURN REST API).

+

eturnal setup

+

Initial installation

+

The eturnal TURN server implementation is available from a variety of sources +such as native package managers, binary packages, installation from source or +container image. They are +all described here.

+

Quick-Test instructions in a Linux Shell +or with Docker +are available as well.

+

Configuration

+

After installation, eturnal usually ships a default configuration file +here: /etc/eturnal.yml (and, if not found there, there is a backup file here: +/opt/eturnal/etc/eturnal.yml). It uses the (indentation-sensitive!) YAML +format. The file contains further explanations.

+

Here are some hints how to configure eturnal on your host machine +or when using e.g. Docker. +You may also further deep dive into the reference documentation.

+

eturnal runs out of the box with the default configuration. To enable TURN and +to integrate it with your homeserver, some aspects in eturnal's default configuration file +must be edited:

+
    +
  1. +

    Homeserver's turn_shared_secret +and eturnal's shared secret for authentication

    +

    Both need to have the same value. Uncomment and adjust this line in eturnal's +configuration file:

    +
    secret: "long-and-cryptic"     # Shared secret, CHANGE THIS.
    +
    +

    One way to generate a secret is with pwgen:

    +
    pwgen -s 64 1
    +
    +
  2. +
  3. +

    Public IP address

    +

    If your TURN server is behind NAT, the NAT gateway must have an external, +publicly-reachable IP address. eturnal tries to autodetect the public IP address, +however, it may also be configured by uncommenting and adjusting this line, so +eturnal advertises that address to connecting clients:

    +
    relay_ipv4_addr: "203.0.113.4" # The server's public IPv4 address.
    +
    +

    If your NAT gateway is reachable over both IPv4 and IPv6, you may +configure eturnal to advertise each available address:

    +
    relay_ipv4_addr: "203.0.113.4" # The server's public IPv4 address.
    +relay_ipv6_addr: "2001:db8::4" # The server's public IPv6 address (optional).
    +
    +

    When advertising an external IPv6 address, ensure that the firewall and +network settings of the system running your TURN server are configured to +accept IPv6 traffic, and that the TURN server is listening on the local +IPv6 address that is mapped by NAT to the external IPv6 address.

    +
  4. +
  5. +

    Logging

    +

    If eturnal was started by systemd, log files are written into the +/var/log/eturnal directory by default. In order to log to the journal +instead, the log_dir option can be set to stdout in the configuration file.

    +
  6. +
  7. +

    Security considerations

    +

    Consider your security settings. TURN lets users request a relay which will +connect to arbitrary IP addresses and ports. The following configuration is +suggested as a minimum starting point, see also the official documentation:

    +
    ## Reject TURN relaying from/to the following addresses/networks:
    +blacklist:                 # This is the default blacklist.
    +    - "127.0.0.0/8"        # IPv4 loopback.
    +    - "::1"                # IPv6 loopback.
    +    - recommended          # Expands to a number of networks recommended to be
    +                           # blocked, but includes private networks. Those
    +                           # would have to be 'whitelist'ed if eturnal serves
    +                           # local clients/peers within such networks.
    +
    +

    To whitelist IP addresses or specific (private) networks, you need to add a +whitelist part into the configuration file, e.g.:

    +
    whitelist:
    +    - "192.168.0.0/16"
    +    - "203.0.113.113"
    +    - "2001:db8::/64"
    +
    +

    The more specific, the better.

    +
  8. +
  9. +

    TURNS (TURN via TLS/DTLS)

    +

    Also consider supporting TLS/DTLS. To do this, adjust the following settings +in the eturnal.yml configuration file (TLS parts should not be commented anymore):

    +
    listen:
    +    - ip: "::"
    +      port: 3478
    +      transport: udp
    +    - ip: "::"
    +      port: 3478
    +      transport: tcp
    +    - ip: "::"
    +      port: 5349
    +      transport: tls
    +
    +## TLS certificate/key files (must be readable by 'eturnal' user!):
    +tls_crt_file: /etc/eturnal/tls/crt.pem
    +tls_key_file: /etc/eturnal/tls/key.pem
    +
    +

    In this case, replace the turn: schemes in homeserver's turn_uris settings +with turns:. More is described here.

    +

    We recommend that you only try to set up TLS/DTLS once you have set up a +basic installation and got it working.

    +

    NB: If your TLS certificate was provided by Let's Encrypt, TLS/DTLS will +not work with any Matrix client that uses Chromium's WebRTC library. This +currently includes Element Android & iOS; for more details, see their +respective +issues as well as the underlying +WebRTC issue. +Consider using a ZeroSSL certificate for your TURN server as a working alternative.

    +
  10. +
  11. +

    Firewall

    +

    Ensure your firewall allows traffic into the TURN server on the ports +you've configured it to listen on (By default: 3478 and 5349 for TURN +traffic (remember to allow both TCP and UDP traffic), and ports 49152-65535 +for the UDP relay.)

    +
  12. +
  13. +

    Reload/ restarting eturnal

    +

    Changes in the configuration file require eturnal to reload/ restart, this +can be achieved by:

    +
    eturnalctl reload
    +
    +

    eturnal performs a configuration check before actually reloading/ restarting +and provides hints, if something is not correctly configured.

    +
  14. +
+

eturnalctl opterations script

+

eturnal offers a handy operations script +which can be called e.g. to check, whether the service is up, to restart the service, +to query how many active sessions exist, to change logging behaviour and so on.

+

Hint: If eturnalctl is not part of your $PATH, consider either sym-linking it (e.g. ´ln -s /opt/eturnal/bin/eturnalctl /usr/local/bin/eturnalctl´) or call it from the default eturnal directory directly: e.g. /opt/eturnal/bin/eturnalctl info

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + -- cgit 1.4.1