mirror of
https://git.anonymousland.org/anonymousland/synapse.git
synced 2024-12-25 12:59:22 -05:00
Improve code formatting and fix a few typos in docs (#11221)
* Labeled a lot more code blocks with the appropriate type * Fixed a couple of minor typos (missing/extraneous commas) Signed-off-by: Sumner Evans <me@sumnerevans.com>
This commit is contained in:
parent
82d2168a15
commit
ece84f2c45
1
changelog.d/11221.doc
Normal file
1
changelog.d/11221.doc
Normal file
@ -0,0 +1 @@
|
|||||||
|
Improve code formatting and fix a few typos in docs. Contributed by @sumnerevans at Beeper.
|
@ -15,12 +15,12 @@ in `homeserver.yaml`, to the list of authorized domains. If you have not set
|
|||||||
1. Agree to the terms of service and submit.
|
1. Agree to the terms of service and submit.
|
||||||
1. Copy your site key and secret key and add them to your `homeserver.yaml`
|
1. Copy your site key and secret key and add them to your `homeserver.yaml`
|
||||||
configuration file
|
configuration file
|
||||||
```
|
```yaml
|
||||||
recaptcha_public_key: YOUR_SITE_KEY
|
recaptcha_public_key: YOUR_SITE_KEY
|
||||||
recaptcha_private_key: YOUR_SECRET_KEY
|
recaptcha_private_key: YOUR_SECRET_KEY
|
||||||
```
|
```
|
||||||
1. Enable the CAPTCHA for new registrations
|
1. Enable the CAPTCHA for new registrations
|
||||||
```
|
```yaml
|
||||||
enable_registration_captcha: true
|
enable_registration_captcha: true
|
||||||
```
|
```
|
||||||
1. Go to the settings page for the CAPTCHA you just created
|
1. Go to the settings page for the CAPTCHA you just created
|
||||||
|
@ -99,7 +99,7 @@ server admin: see [Admin API](../usage/administration/admin_api).
|
|||||||
|
|
||||||
It returns a JSON body like the following:
|
It returns a JSON body like the following:
|
||||||
|
|
||||||
```jsonc
|
```json
|
||||||
{
|
{
|
||||||
"event_id": "$bNUFCwGzWca1meCGkjp-zwslF-GfVcXukvRLI1_FaVY",
|
"event_id": "$bNUFCwGzWca1meCGkjp-zwslF-GfVcXukvRLI1_FaVY",
|
||||||
"event_json": {
|
"event_json": {
|
||||||
@ -132,7 +132,7 @@ It returns a JSON body like the following:
|
|||||||
},
|
},
|
||||||
"type": "m.room.message",
|
"type": "m.room.message",
|
||||||
"unsigned": {
|
"unsigned": {
|
||||||
"age_ts": 1592291711430,
|
"age_ts": 1592291711430
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"id": <report_id>,
|
"id": <report_id>,
|
||||||
|
@ -27,7 +27,7 @@ Room state data (such as joins, leaves, topic) is always preserved.
|
|||||||
|
|
||||||
To delete local message events as well, set `delete_local_events` in the body:
|
To delete local message events as well, set `delete_local_events` in the body:
|
||||||
|
|
||||||
```
|
```json
|
||||||
{
|
{
|
||||||
"delete_local_events": true
|
"delete_local_events": true
|
||||||
}
|
}
|
||||||
|
@ -28,7 +28,7 @@ server admin: see [Admin API](../usage/administration/admin_api).
|
|||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```json
|
||||||
{
|
{
|
||||||
"room_id": "!636q39766251:server.com"
|
"room_id": "!636q39766251:server.com"
|
||||||
}
|
}
|
||||||
|
@ -87,7 +87,7 @@ GET /_synapse/admin/v1/rooms
|
|||||||
|
|
||||||
A response body like the following is returned:
|
A response body like the following is returned:
|
||||||
|
|
||||||
```jsonc
|
```json
|
||||||
{
|
{
|
||||||
"rooms": [
|
"rooms": [
|
||||||
{
|
{
|
||||||
@ -170,7 +170,7 @@ GET /_synapse/admin/v1/rooms?order_by=size
|
|||||||
|
|
||||||
A response body like the following is returned:
|
A response body like the following is returned:
|
||||||
|
|
||||||
```jsonc
|
```json
|
||||||
{
|
{
|
||||||
"rooms": [
|
"rooms": [
|
||||||
{
|
{
|
||||||
@ -208,7 +208,7 @@ A response body like the following is returned:
|
|||||||
}
|
}
|
||||||
],
|
],
|
||||||
"offset": 0,
|
"offset": 0,
|
||||||
"total_rooms": 150
|
"total_rooms": 150,
|
||||||
"next_token": 100
|
"next_token": 100
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
@ -224,7 +224,7 @@ GET /_synapse/admin/v1/rooms?order_by=size&from=100
|
|||||||
|
|
||||||
A response body like the following is returned:
|
A response body like the following is returned:
|
||||||
|
|
||||||
```jsonc
|
```json
|
||||||
{
|
{
|
||||||
"rooms": [
|
"rooms": [
|
||||||
{
|
{
|
||||||
|
@ -10,7 +10,9 @@ The necessary tools are detailed below.
|
|||||||
|
|
||||||
First install them with:
|
First install them with:
|
||||||
|
|
||||||
pip install -e ".[lint,mypy]"
|
```sh
|
||||||
|
pip install -e ".[lint,mypy]"
|
||||||
|
```
|
||||||
|
|
||||||
- **black**
|
- **black**
|
||||||
|
|
||||||
@ -21,7 +23,9 @@ First install them with:
|
|||||||
Have `black` auto-format your code (it shouldn't change any
|
Have `black` auto-format your code (it shouldn't change any
|
||||||
functionality) with:
|
functionality) with:
|
||||||
|
|
||||||
black . --exclude="\.tox|build|env"
|
```sh
|
||||||
|
black . --exclude="\.tox|build|env"
|
||||||
|
```
|
||||||
|
|
||||||
- **flake8**
|
- **flake8**
|
||||||
|
|
||||||
@ -30,7 +34,9 @@ First install them with:
|
|||||||
|
|
||||||
Check all application and test code with:
|
Check all application and test code with:
|
||||||
|
|
||||||
flake8 synapse tests
|
```sh
|
||||||
|
flake8 synapse tests
|
||||||
|
```
|
||||||
|
|
||||||
- **isort**
|
- **isort**
|
||||||
|
|
||||||
@ -39,7 +45,9 @@ First install them with:
|
|||||||
|
|
||||||
Auto-fix imports with:
|
Auto-fix imports with:
|
||||||
|
|
||||||
isort -rc synapse tests
|
```sh
|
||||||
|
isort -rc synapse tests
|
||||||
|
```
|
||||||
|
|
||||||
`-rc` means to recursively search the given directories.
|
`-rc` means to recursively search the given directories.
|
||||||
|
|
||||||
@ -66,15 +74,19 @@ save as it takes a while and is very resource intensive.
|
|||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
||||||
from synapse.types import UserID
|
```python
|
||||||
...
|
from synapse.types import UserID
|
||||||
user_id = UserID(local, server)
|
...
|
||||||
|
user_id = UserID(local, server)
|
||||||
|
```
|
||||||
|
|
||||||
is preferred over:
|
is preferred over:
|
||||||
|
|
||||||
from synapse import types
|
```python
|
||||||
...
|
from synapse import types
|
||||||
user_id = types.UserID(local, server)
|
...
|
||||||
|
user_id = types.UserID(local, server)
|
||||||
|
```
|
||||||
|
|
||||||
(or any other variant).
|
(or any other variant).
|
||||||
|
|
||||||
@ -134,28 +146,30 @@ Some guidelines follow:
|
|||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
||||||
## Frobnication ##
|
```yaml
|
||||||
|
## Frobnication ##
|
||||||
|
|
||||||
# The frobnicator will ensure that all requests are fully frobnicated.
|
# The frobnicator will ensure that all requests are fully frobnicated.
|
||||||
# To enable it, uncomment the following.
|
# To enable it, uncomment the following.
|
||||||
#
|
#
|
||||||
#frobnicator_enabled: true
|
#frobnicator_enabled: true
|
||||||
|
|
||||||
# By default, the frobnicator will frobnicate with the default frobber.
|
# By default, the frobnicator will frobnicate with the default frobber.
|
||||||
# The following will make it use an alternative frobber.
|
# The following will make it use an alternative frobber.
|
||||||
#
|
#
|
||||||
#frobincator_frobber: special_frobber
|
#frobincator_frobber: special_frobber
|
||||||
|
|
||||||
# Settings for the frobber
|
# Settings for the frobber
|
||||||
#
|
#
|
||||||
frobber:
|
frobber:
|
||||||
# frobbing speed. Defaults to 1.
|
# frobbing speed. Defaults to 1.
|
||||||
#
|
#
|
||||||
#speed: 10
|
#speed: 10
|
||||||
|
|
||||||
# frobbing distance. Defaults to 1000.
|
# frobbing distance. Defaults to 1000.
|
||||||
#
|
#
|
||||||
#distance: 100
|
#distance: 100
|
||||||
|
```
|
||||||
|
|
||||||
Note that the sample configuration is generated from the synapse code
|
Note that the sample configuration is generated from the synapse code
|
||||||
and is maintained by a script, `scripts-dev/generate_sample_config`.
|
and is maintained by a script, `scripts-dev/generate_sample_config`.
|
||||||
|
@ -99,7 +99,7 @@ construct URIs where users can give their consent.
|
|||||||
see if an unauthenticated user is viewing the page. This is typically
|
see if an unauthenticated user is viewing the page. This is typically
|
||||||
wrapped around the form that would be used to actually agree to the document:
|
wrapped around the form that would be used to actually agree to the document:
|
||||||
|
|
||||||
```
|
```html
|
||||||
{% if not public_version %}
|
{% if not public_version %}
|
||||||
<!-- The variables used here are only provided when the 'u' param is given to the homeserver -->
|
<!-- The variables used here are only provided when the 'u' param is given to the homeserver -->
|
||||||
<form method="post" action="consent">
|
<form method="post" action="consent">
|
||||||
|
@ -8,23 +8,23 @@ easy to run CAS implementation built on top of Django.
|
|||||||
1. Create a new virtualenv: `python3 -m venv <your virtualenv>`
|
1. Create a new virtualenv: `python3 -m venv <your virtualenv>`
|
||||||
2. Activate your virtualenv: `source /path/to/your/virtualenv/bin/activate`
|
2. Activate your virtualenv: `source /path/to/your/virtualenv/bin/activate`
|
||||||
3. Install Django and django-mama-cas:
|
3. Install Django and django-mama-cas:
|
||||||
```
|
```sh
|
||||||
python -m pip install "django<3" "django-mama-cas==2.4.0"
|
python -m pip install "django<3" "django-mama-cas==2.4.0"
|
||||||
```
|
```
|
||||||
4. Create a Django project in the current directory:
|
4. Create a Django project in the current directory:
|
||||||
```
|
```sh
|
||||||
django-admin startproject cas_test .
|
django-admin startproject cas_test .
|
||||||
```
|
```
|
||||||
5. Follow the [install directions](https://django-mama-cas.readthedocs.io/en/latest/installation.html#configuring) for django-mama-cas
|
5. Follow the [install directions](https://django-mama-cas.readthedocs.io/en/latest/installation.html#configuring) for django-mama-cas
|
||||||
6. Setup the SQLite database: `python manage.py migrate`
|
6. Setup the SQLite database: `python manage.py migrate`
|
||||||
7. Create a user:
|
7. Create a user:
|
||||||
```
|
```sh
|
||||||
python manage.py createsuperuser
|
python manage.py createsuperuser
|
||||||
```
|
```
|
||||||
1. Use whatever you want as the username and password.
|
1. Use whatever you want as the username and password.
|
||||||
2. Leave the other fields blank.
|
2. Leave the other fields blank.
|
||||||
8. Use the built-in Django test server to serve the CAS endpoints on port 8000:
|
8. Use the built-in Django test server to serve the CAS endpoints on port 8000:
|
||||||
```
|
```sh
|
||||||
python manage.py runserver
|
python manage.py runserver
|
||||||
```
|
```
|
||||||
|
|
||||||
|
@ -89,7 +89,9 @@ To do so, use `scripts-dev/make_full_schema.sh`. This will produce new
|
|||||||
|
|
||||||
Ensure postgres is installed, then run:
|
Ensure postgres is installed, then run:
|
||||||
|
|
||||||
./scripts-dev/make_full_schema.sh -p postgres_username -o output_dir/
|
```sh
|
||||||
|
./scripts-dev/make_full_schema.sh -p postgres_username -o output_dir/
|
||||||
|
```
|
||||||
|
|
||||||
NB at the time of writing, this script predates the split into separate `state`/`main`
|
NB at the time of writing, this script predates the split into separate `state`/`main`
|
||||||
databases so will require updates to handle that correctly.
|
databases so will require updates to handle that correctly.
|
||||||
|
@ -69,9 +69,9 @@ A default policy can be defined as such, in the `retention` section of
|
|||||||
the configuration file:
|
the configuration file:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
default_policy:
|
default_policy:
|
||||||
min_lifetime: 1d
|
min_lifetime: 1d
|
||||||
max_lifetime: 1y
|
max_lifetime: 1y
|
||||||
```
|
```
|
||||||
|
|
||||||
Here, `min_lifetime` and `max_lifetime` have the same meaning and level
|
Here, `min_lifetime` and `max_lifetime` have the same meaning and level
|
||||||
@ -95,14 +95,14 @@ depending on an event's room's policy. This can be done by setting the
|
|||||||
file. An example of such configuration could be:
|
file. An example of such configuration could be:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
purge_jobs:
|
purge_jobs:
|
||||||
- longest_max_lifetime: 3d
|
- longest_max_lifetime: 3d
|
||||||
interval: 12h
|
interval: 12h
|
||||||
- shortest_max_lifetime: 3d
|
- shortest_max_lifetime: 3d
|
||||||
longest_max_lifetime: 1w
|
longest_max_lifetime: 1w
|
||||||
interval: 1d
|
interval: 1d
|
||||||
- shortest_max_lifetime: 1w
|
- shortest_max_lifetime: 1w
|
||||||
interval: 2d
|
interval: 2d
|
||||||
```
|
```
|
||||||
|
|
||||||
In this example, we define three jobs:
|
In this example, we define three jobs:
|
||||||
@ -141,8 +141,8 @@ purging old events in a room. These limits can be defined as such in the
|
|||||||
`retention` section of the configuration file:
|
`retention` section of the configuration file:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
allowed_lifetime_min: 1d
|
allowed_lifetime_min: 1d
|
||||||
allowed_lifetime_max: 1y
|
allowed_lifetime_max: 1y
|
||||||
```
|
```
|
||||||
|
|
||||||
The limits are considered when running purge jobs. If necessary, the
|
The limits are considered when running purge jobs. If necessary, the
|
||||||
|
@ -10,7 +10,7 @@ registered by using the Module API's `register_password_auth_provider_callbacks`
|
|||||||
|
|
||||||
_First introduced in Synapse v1.46.0_
|
_First introduced in Synapse v1.46.0_
|
||||||
|
|
||||||
```
|
```python
|
||||||
auth_checkers: Dict[Tuple[str,Tuple], Callable]
|
auth_checkers: Dict[Tuple[str,Tuple], Callable]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
@ -29,16 +29,20 @@ connect to a postgres database.
|
|||||||
|
|
||||||
Assuming your PostgreSQL database user is called `postgres`, first authenticate as the database user with:
|
Assuming your PostgreSQL database user is called `postgres`, first authenticate as the database user with:
|
||||||
|
|
||||||
su - postgres
|
```sh
|
||||||
# Or, if your system uses sudo to get administrative rights
|
su - postgres
|
||||||
sudo -u postgres bash
|
# Or, if your system uses sudo to get administrative rights
|
||||||
|
sudo -u postgres bash
|
||||||
|
```
|
||||||
|
|
||||||
Then, create a postgres user and a database with:
|
Then, create a postgres user and a database with:
|
||||||
|
|
||||||
# this will prompt for a password for the new user
|
```sh
|
||||||
createuser --pwprompt synapse_user
|
# this will prompt for a password for the new user
|
||||||
|
createuser --pwprompt synapse_user
|
||||||
|
|
||||||
createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse
|
createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse
|
||||||
|
```
|
||||||
|
|
||||||
The above will create a user called `synapse_user`, and a database called
|
The above will create a user called `synapse_user`, and a database called
|
||||||
`synapse`.
|
`synapse`.
|
||||||
@ -145,20 +149,26 @@ Firstly, shut down the currently running synapse server and copy its
|
|||||||
database file (typically `homeserver.db`) to another location. Once the
|
database file (typically `homeserver.db`) to another location. Once the
|
||||||
copy is complete, restart synapse. For instance:
|
copy is complete, restart synapse. For instance:
|
||||||
|
|
||||||
./synctl stop
|
```sh
|
||||||
cp homeserver.db homeserver.db.snapshot
|
./synctl stop
|
||||||
./synctl start
|
cp homeserver.db homeserver.db.snapshot
|
||||||
|
./synctl start
|
||||||
|
```
|
||||||
|
|
||||||
Copy the old config file into a new config file:
|
Copy the old config file into a new config file:
|
||||||
|
|
||||||
cp homeserver.yaml homeserver-postgres.yaml
|
```sh
|
||||||
|
cp homeserver.yaml homeserver-postgres.yaml
|
||||||
|
```
|
||||||
|
|
||||||
Edit the database section as described in the section *Synapse config*
|
Edit the database section as described in the section *Synapse config*
|
||||||
above and with the SQLite snapshot located at `homeserver.db.snapshot`
|
above and with the SQLite snapshot located at `homeserver.db.snapshot`
|
||||||
simply run:
|
simply run:
|
||||||
|
|
||||||
synapse_port_db --sqlite-database homeserver.db.snapshot \
|
```sh
|
||||||
--postgres-config homeserver-postgres.yaml
|
synapse_port_db --sqlite-database homeserver.db.snapshot \
|
||||||
|
--postgres-config homeserver-postgres.yaml
|
||||||
|
```
|
||||||
|
|
||||||
The flag `--curses` displays a coloured curses progress UI.
|
The flag `--curses` displays a coloured curses progress UI.
|
||||||
|
|
||||||
@ -170,16 +180,20 @@ To complete the conversion shut down the synapse server and run the port
|
|||||||
script one last time, e.g. if the SQLite database is at `homeserver.db`
|
script one last time, e.g. if the SQLite database is at `homeserver.db`
|
||||||
run:
|
run:
|
||||||
|
|
||||||
synapse_port_db --sqlite-database homeserver.db \
|
```sh
|
||||||
--postgres-config homeserver-postgres.yaml
|
synapse_port_db --sqlite-database homeserver.db \
|
||||||
|
--postgres-config homeserver-postgres.yaml
|
||||||
|
```
|
||||||
|
|
||||||
Once that has completed, change the synapse config to point at the
|
Once that has completed, change the synapse config to point at the
|
||||||
PostgreSQL database configuration file `homeserver-postgres.yaml`:
|
PostgreSQL database configuration file `homeserver-postgres.yaml`:
|
||||||
|
|
||||||
./synctl stop
|
```sh
|
||||||
mv homeserver.yaml homeserver-old-sqlite.yaml
|
./synctl stop
|
||||||
mv homeserver-postgres.yaml homeserver.yaml
|
mv homeserver.yaml homeserver-old-sqlite.yaml
|
||||||
./synctl start
|
mv homeserver-postgres.yaml homeserver.yaml
|
||||||
|
./synctl start
|
||||||
|
```
|
||||||
|
|
||||||
Synapse should now be running against PostgreSQL.
|
Synapse should now be running against PostgreSQL.
|
||||||
|
|
||||||
|
@ -52,7 +52,7 @@ to proxied traffic.)
|
|||||||
|
|
||||||
### nginx
|
### nginx
|
||||||
|
|
||||||
```
|
```nginx
|
||||||
server {
|
server {
|
||||||
listen 443 ssl http2;
|
listen 443 ssl http2;
|
||||||
listen [::]:443 ssl http2;
|
listen [::]:443 ssl http2;
|
||||||
@ -141,7 +141,7 @@ matrix.example.com {
|
|||||||
|
|
||||||
### Apache
|
### Apache
|
||||||
|
|
||||||
```
|
```apache
|
||||||
<VirtualHost *:443>
|
<VirtualHost *:443>
|
||||||
SSLEngine on
|
SSLEngine on
|
||||||
ServerName matrix.example.com
|
ServerName matrix.example.com
|
||||||
@ -170,7 +170,7 @@ matrix.example.com {
|
|||||||
|
|
||||||
**NOTE 2**: It appears that Synapse is currently incompatible with the ModSecurity module for Apache (`mod_security2`). If you need it enabled for other services on your web server, you can disable it for Synapse's two VirtualHosts by including the following lines before each of the two `</VirtualHost>` above:
|
**NOTE 2**: It appears that Synapse is currently incompatible with the ModSecurity module for Apache (`mod_security2`). If you need it enabled for other services on your web server, you can disable it for Synapse's two VirtualHosts by including the following lines before each of the two `</VirtualHost>` above:
|
||||||
|
|
||||||
```
|
```apache
|
||||||
<IfModule security2_module>
|
<IfModule security2_module>
|
||||||
SecRuleEngine off
|
SecRuleEngine off
|
||||||
</IfModule>
|
</IfModule>
|
||||||
|
@ -20,7 +20,9 @@ Finally, to actually run your worker-based synapse, you must pass synctl the `-a
|
|||||||
commandline option to tell it to operate on all the worker configurations found
|
commandline option to tell it to operate on all the worker configurations found
|
||||||
in the given directory, e.g.:
|
in the given directory, e.g.:
|
||||||
|
|
||||||
synctl -a $CONFIG/workers start
|
```sh
|
||||||
|
synctl -a $CONFIG/workers start
|
||||||
|
```
|
||||||
|
|
||||||
Currently one should always restart all workers when restarting or upgrading
|
Currently one should always restart all workers when restarting or upgrading
|
||||||
synapse, unless you explicitly know it's safe not to. For instance, restarting
|
synapse, unless you explicitly know it's safe not to. For instance, restarting
|
||||||
@ -29,4 +31,6 @@ notifications.
|
|||||||
|
|
||||||
To manipulate a specific worker, you pass the -w option to synctl:
|
To manipulate a specific worker, you pass the -w option to synctl:
|
||||||
|
|
||||||
synctl -w $CONFIG/workers/worker1.yaml restart
|
```sh
|
||||||
|
synctl -w $CONFIG/workers/worker1.yaml restart
|
||||||
|
```
|
||||||
|
@ -40,7 +40,9 @@ This will install and start a systemd service called `coturn`.
|
|||||||
|
|
||||||
1. Configure it:
|
1. Configure it:
|
||||||
|
|
||||||
./configure
|
```sh
|
||||||
|
./configure
|
||||||
|
```
|
||||||
|
|
||||||
You may need to install `libevent2`: if so, you should do so in
|
You may need to install `libevent2`: if so, you should do so in
|
||||||
the way recommended by your operating system. You can ignore
|
the way recommended by your operating system. You can ignore
|
||||||
@ -49,22 +51,28 @@ This will install and start a systemd service called `coturn`.
|
|||||||
|
|
||||||
1. Build and install it:
|
1. Build and install it:
|
||||||
|
|
||||||
make
|
```sh
|
||||||
make install
|
make
|
||||||
|
make install
|
||||||
|
```
|
||||||
|
|
||||||
### Configuration
|
### Configuration
|
||||||
|
|
||||||
1. Create or edit the config file in `/etc/turnserver.conf`. The relevant
|
1. Create or edit the config file in `/etc/turnserver.conf`. The relevant
|
||||||
lines, with example values, are:
|
lines, with example values, are:
|
||||||
|
|
||||||
use-auth-secret
|
```
|
||||||
static-auth-secret=[your secret key here]
|
use-auth-secret
|
||||||
realm=turn.myserver.org
|
static-auth-secret=[your secret key here]
|
||||||
|
realm=turn.myserver.org
|
||||||
|
```
|
||||||
|
|
||||||
See `turnserver.conf` for explanations of the options. One way to generate
|
See `turnserver.conf` for explanations of the options. One way to generate
|
||||||
the `static-auth-secret` is with `pwgen`:
|
the `static-auth-secret` is with `pwgen`:
|
||||||
|
|
||||||
pwgen -s 64 1
|
```sh
|
||||||
|
pwgen -s 64 1
|
||||||
|
```
|
||||||
|
|
||||||
A `realm` must be specified, but its value is somewhat arbitrary. (It is
|
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
|
sent to clients as part of the authentication flow.) It is conventional to
|
||||||
@ -73,7 +81,9 @@ This will install and start a systemd service called `coturn`.
|
|||||||
1. You will most likely want to configure coturn to write logs somewhere. The
|
1. You will most likely want to configure coturn to write logs somewhere. The
|
||||||
easiest way is normally to send them to the syslog:
|
easiest way is normally to send them to the syslog:
|
||||||
|
|
||||||
syslog
|
```sh
|
||||||
|
syslog
|
||||||
|
```
|
||||||
|
|
||||||
(in which case, the logs will be available via `journalctl -u coturn` on a
|
(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
|
systemd system). Alternatively, coturn can be configured to write to a
|
||||||
@ -83,31 +93,35 @@ This will install and start a systemd service called `coturn`.
|
|||||||
connect to arbitrary IP addresses and ports. The following configuration is
|
connect to arbitrary IP addresses and ports. The following configuration is
|
||||||
suggested as a minimum starting point:
|
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
|
# 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)
|
# 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.
|
# 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=10.0.0.0-10.255.255.255
|
||||||
denied-peer-ip=192.168.0.0-192.168.255.255
|
denied-peer-ip=192.168.0.0-192.168.255.255
|
||||||
denied-peer-ip=172.16.0.0-172.31.255.255
|
denied-peer-ip=172.16.0.0-172.31.255.255
|
||||||
|
|
||||||
# special case the turn server itself so that client->TURN->TURN->client flows work
|
# special case the turn server itself so that client->TURN->TURN->client flows work
|
||||||
allowed-peer-ip=10.0.0.1
|
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.
|
# 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.
|
user-quota=12 # 4 streams per video call, so 12 streams = 3 simultaneous relayed calls per user.
|
||||||
total-quota=1200
|
total-quota=1200
|
||||||
|
```
|
||||||
|
|
||||||
1. Also consider supporting TLS/DTLS. To do this, add the following settings
|
1. Also consider supporting TLS/DTLS. To do this, add the following settings
|
||||||
to `turnserver.conf`:
|
to `turnserver.conf`:
|
||||||
|
|
||||||
# TLS certificates, including intermediate certs.
|
```
|
||||||
# For Let's Encrypt certificates, use `fullchain.pem` here.
|
# TLS certificates, including intermediate certs.
|
||||||
cert=/path/to/fullchain.pem
|
# For Let's Encrypt certificates, use `fullchain.pem` here.
|
||||||
|
cert=/path/to/fullchain.pem
|
||||||
|
|
||||||
# TLS private key file
|
# TLS private key file
|
||||||
pkey=/path/to/privkey.pem
|
pkey=/path/to/privkey.pem
|
||||||
|
```
|
||||||
|
|
||||||
In this case, replace the `turn:` schemes in the `turn_uri` settings below
|
In this case, replace the `turn:` schemes in the `turn_uri` settings below
|
||||||
with `turns:`.
|
with `turns:`.
|
||||||
@ -126,7 +140,9 @@ This will install and start a systemd service called `coturn`.
|
|||||||
If you want to try it anyway, you will at least need to tell coturn its
|
If you want to try it anyway, you will at least need to tell coturn its
|
||||||
external IP address:
|
external IP address:
|
||||||
|
|
||||||
external-ip=192.88.99.1
|
```
|
||||||
|
external-ip=192.88.99.1
|
||||||
|
```
|
||||||
|
|
||||||
... and your NAT gateway must forward all of the relayed ports directly
|
... and your NAT gateway must forward all of the relayed ports directly
|
||||||
(eg, port 56789 on the external IP must be always be forwarded to port
|
(eg, port 56789 on the external IP must be always be forwarded to port
|
||||||
@ -186,7 +202,7 @@ After updating the homeserver configuration, you must restart synapse:
|
|||||||
./synctl restart
|
./synctl restart
|
||||||
```
|
```
|
||||||
* If you use systemd:
|
* If you use systemd:
|
||||||
```
|
```sh
|
||||||
systemctl restart matrix-synapse.service
|
systemctl restart matrix-synapse.service
|
||||||
```
|
```
|
||||||
... and then reload any clients (or wait an hour for them to refresh their
|
... and then reload any clients (or wait an hour for them to refresh their
|
||||||
|
104
docs/upgrade.md
104
docs/upgrade.md
@ -1176,16 +1176,20 @@ For more information on configuring TLS certificates see the
|
|||||||
For users who have installed Synapse into a virtualenv, we recommend
|
For users who have installed Synapse into a virtualenv, we recommend
|
||||||
doing this by creating a new virtualenv. For example:
|
doing this by creating a new virtualenv. For example:
|
||||||
|
|
||||||
virtualenv -p python3 ~/synapse/env3
|
```sh
|
||||||
source ~/synapse/env3/bin/activate
|
virtualenv -p python3 ~/synapse/env3
|
||||||
pip install matrix-synapse
|
source ~/synapse/env3/bin/activate
|
||||||
|
pip install matrix-synapse
|
||||||
|
```
|
||||||
|
|
||||||
You can then start synapse as normal, having activated the new
|
You can then start synapse as normal, having activated the new
|
||||||
virtualenv:
|
virtualenv:
|
||||||
|
|
||||||
cd ~/synapse
|
```sh
|
||||||
source env3/bin/activate
|
cd ~/synapse
|
||||||
synctl start
|
source env3/bin/activate
|
||||||
|
synctl start
|
||||||
|
```
|
||||||
|
|
||||||
Users who have installed from distribution packages should see the
|
Users who have installed from distribution packages should see the
|
||||||
relevant package documentation. See below for notes on Debian
|
relevant package documentation. See below for notes on Debian
|
||||||
@ -1197,34 +1201,38 @@ For more information on configuring TLS certificates see the
|
|||||||
`<server>.log.config` file. For example, if your `log.config`
|
`<server>.log.config` file. For example, if your `log.config`
|
||||||
file contains:
|
file contains:
|
||||||
|
|
||||||
handlers:
|
```yaml
|
||||||
file:
|
handlers:
|
||||||
class: logging.handlers.RotatingFileHandler
|
file:
|
||||||
formatter: precise
|
class: logging.handlers.RotatingFileHandler
|
||||||
filename: homeserver.log
|
formatter: precise
|
||||||
maxBytes: 104857600
|
filename: homeserver.log
|
||||||
backupCount: 10
|
maxBytes: 104857600
|
||||||
filters: [context]
|
backupCount: 10
|
||||||
console:
|
filters: [context]
|
||||||
class: logging.StreamHandler
|
console:
|
||||||
formatter: precise
|
class: logging.StreamHandler
|
||||||
filters: [context]
|
formatter: precise
|
||||||
|
filters: [context]
|
||||||
|
```
|
||||||
|
|
||||||
Then you should update this to be:
|
Then you should update this to be:
|
||||||
|
|
||||||
handlers:
|
```yaml
|
||||||
file:
|
handlers:
|
||||||
class: logging.handlers.RotatingFileHandler
|
file:
|
||||||
formatter: precise
|
class: logging.handlers.RotatingFileHandler
|
||||||
filename: homeserver.log
|
formatter: precise
|
||||||
maxBytes: 104857600
|
filename: homeserver.log
|
||||||
backupCount: 10
|
maxBytes: 104857600
|
||||||
filters: [context]
|
backupCount: 10
|
||||||
encoding: utf8
|
filters: [context]
|
||||||
console:
|
encoding: utf8
|
||||||
class: logging.StreamHandler
|
console:
|
||||||
formatter: precise
|
class: logging.StreamHandler
|
||||||
filters: [context]
|
formatter: precise
|
||||||
|
filters: [context]
|
||||||
|
```
|
||||||
|
|
||||||
There is no need to revert this change if downgrading to
|
There is no need to revert this change if downgrading to
|
||||||
Python 2.
|
Python 2.
|
||||||
@ -1310,24 +1318,28 @@ with the HS remotely has been removed.
|
|||||||
It has been replaced by specifying a list of application service
|
It has been replaced by specifying a list of application service
|
||||||
registrations in `homeserver.yaml`:
|
registrations in `homeserver.yaml`:
|
||||||
|
|
||||||
app_service_config_files: ["registration-01.yaml", "registration-02.yaml"]
|
```yaml
|
||||||
|
app_service_config_files: ["registration-01.yaml", "registration-02.yaml"]
|
||||||
|
```
|
||||||
|
|
||||||
Where `registration-01.yaml` looks like:
|
Where `registration-01.yaml` looks like:
|
||||||
|
|
||||||
url: <String> # e.g. "https://my.application.service.com"
|
```yaml
|
||||||
as_token: <String>
|
url: <String> # e.g. "https://my.application.service.com"
|
||||||
hs_token: <String>
|
as_token: <String>
|
||||||
sender_localpart: <String> # This is a new field which denotes the user_id localpart when using the AS token
|
hs_token: <String>
|
||||||
namespaces:
|
sender_localpart: <String> # This is a new field which denotes the user_id localpart when using the AS token
|
||||||
users:
|
namespaces:
|
||||||
- exclusive: <Boolean>
|
users:
|
||||||
regex: <String> # e.g. "@prefix_.*"
|
- exclusive: <Boolean>
|
||||||
aliases:
|
regex: <String> # e.g. "@prefix_.*"
|
||||||
- exclusive: <Boolean>
|
aliases:
|
||||||
regex: <String>
|
- exclusive: <Boolean>
|
||||||
rooms:
|
regex: <String>
|
||||||
- exclusive: <Boolean>
|
rooms:
|
||||||
regex: <String>
|
- exclusive: <Boolean>
|
||||||
|
regex: <String>
|
||||||
|
```
|
||||||
|
|
||||||
# Upgrading to v0.8.0
|
# Upgrading to v0.8.0
|
||||||
|
|
||||||
|
@ -443,19 +443,19 @@ In the `media_repository` worker configuration file, configure the http listener
|
|||||||
expose the `media` resource. For example:
|
expose the `media` resource. For example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
worker_listeners:
|
worker_listeners:
|
||||||
- type: http
|
- type: http
|
||||||
port: 8085
|
port: 8085
|
||||||
resources:
|
resources:
|
||||||
- names:
|
- names:
|
||||||
- media
|
- media
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that if running multiple media repositories they must be on the same server
|
Note that if running multiple media repositories they must be on the same server
|
||||||
and you must configure a single instance to run the background tasks, e.g.:
|
and you must configure a single instance to run the background tasks, e.g.:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
media_instance_running_background_jobs: "media-repository-1"
|
media_instance_running_background_jobs: "media-repository-1"
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that if a reverse proxy is used , then `/_matrix/media/` must be routed for both inbound client and federation requests (if they are handled separately).
|
Note that if a reverse proxy is used , then `/_matrix/media/` must be routed for both inbound client and federation requests (if they are handled separately).
|
||||||
@ -492,7 +492,9 @@ must therefore be configured with the location of the main instance, via
|
|||||||
the `worker_main_http_uri` setting in the `frontend_proxy` worker configuration
|
the `worker_main_http_uri` setting in the `frontend_proxy` worker configuration
|
||||||
file. For example:
|
file. For example:
|
||||||
|
|
||||||
worker_main_http_uri: http://127.0.0.1:8008
|
```yaml
|
||||||
|
worker_main_http_uri: http://127.0.0.1:8008
|
||||||
|
```
|
||||||
|
|
||||||
### Historical apps
|
### Historical apps
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user