Fix broken links in documentation (#10180)

* Fix broken links in documentation

* newsfile
This commit is contained in:
Dirk Klimpel 2021-06-16 14:15:52 +02:00 committed by GitHub
parent 9e405034e5
commit 0adc2882c1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 53 additions and 51 deletions

1
changelog.d/10180.doc Normal file
View file

@ -0,0 +1 @@
Fix broken links in documentation.

View file

@ -2,7 +2,7 @@ Admin APIs
========== ==========
**Note**: The latest documentation can be viewed `here <https://matrix-org.github.io/synapse>`_. **Note**: The latest documentation can be viewed `here <https://matrix-org.github.io/synapse>`_.
See `docs/README.md <../docs/README.md>`_ for more information. See `docs/README.md <../README.md>`_ for more information.
**Please update links to point to the website instead.** Existing files in this directory **Please update links to point to the website instead.** Existing files in this directory
are preserved to maintain historical links, but may be moved in the future. are preserved to maintain historical links, but may be moved in the future.
@ -10,5 +10,5 @@ are preserved to maintain historical links, but may be moved in the future.
This directory includes documentation for the various synapse specific admin This directory includes documentation for the various synapse specific admin
APIs available. Updates to the existing Admin API documentation should still APIs available. Updates to the existing Admin API documentation should still
be made to these files, but any new documentation files should instead be placed under be made to these files, but any new documentation files should instead be placed under
`docs/usage/administration/admin_api <../docs/usage/administration/admin_api>`_. `docs/usage/administration/admin_api <../usage/administration/admin_api>`_.

View file

@ -11,4 +11,4 @@ POST /_synapse/admin/v1/delete_group/<group_id>
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: see [Admin API](../../usage/administration/admin_api). server admin: see [Admin API](../usage/administration/admin_api).

View file

@ -7,7 +7,7 @@ The api is:
GET /_synapse/admin/v1/event_reports?from=0&limit=10 GET /_synapse/admin/v1/event_reports?from=0&limit=10
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: see [Admin API](../../usage/administration/admin_api). 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:
@ -95,7 +95,7 @@ The api is:
GET /_synapse/admin/v1/event_reports/<report_id> GET /_synapse/admin/v1/event_reports/<report_id>
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: see [Admin API](../../usage/administration/admin_api). 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:

View file

@ -28,7 +28,7 @@ The API is:
GET /_synapse/admin/v1/room/<room_id>/media GET /_synapse/admin/v1/room/<room_id>/media
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: see [Admin API](../../usage/administration/admin_api). server admin: see [Admin API](../usage/administration/admin_api).
The API returns a JSON body like the following: The API returns a JSON body like the following:
```json ```json
@ -311,7 +311,7 @@ The following fields are returned in the JSON response body:
* `deleted`: integer - The number of media items successfully deleted * `deleted`: integer - The number of media items successfully deleted
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: see [Admin API](../../usage/administration/admin_api). server admin: see [Admin API](../usage/administration/admin_api).
If the user re-requests purged remote media, synapse will re-request the media If the user re-requests purged remote media, synapse will re-request the media
from the originating server. from the originating server.

View file

@ -17,7 +17,7 @@ POST /_synapse/admin/v1/purge_history/<room_id>[/<event_id>]
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
By default, events sent by local users are not deleted, as they may represent By default, events sent by local users are not deleted, as they may represent
the only copies of this content in existence. (Events sent by remote users are the only copies of this content in existence. (Events sent by remote users are

View file

@ -24,7 +24,7 @@ POST /_synapse/admin/v1/join/<room_id_or_alias>
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: see [Admin API](../../usage/administration/admin_api). server admin: see [Admin API](../usage/administration/admin_api).
Response: Response:

View file

@ -443,7 +443,7 @@ with a body of:
``` ```
To use it, you will need to authenticate by providing an ``access_token`` for a To use it, you will need to authenticate by providing an ``access_token`` for a
server admin: see [Admin API](../../usage/administration/admin_api). server admin: see [Admin API](../usage/administration/admin_api).
A response body like the following is returned: A response body like the following is returned:

View file

@ -10,7 +10,7 @@ GET /_synapse/admin/v1/statistics/users/media
``` ```
To use it, you will need to authenticate by providing an `access_token` To use it, you will need to authenticate by providing an `access_token`
for a server admin: see [Admin API](../../usage/administration/admin_api). for a server admin: see [Admin API](../usage/administration/admin_api).
A response body like the following is returned: A response body like the following is returned:

View file

@ -11,7 +11,7 @@ GET /_synapse/admin/v2/users/<user_id>
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
It returns a JSON body like the following: It returns a JSON body like the following:
@ -78,7 +78,7 @@ with a body of:
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
URL parameters: URL parameters:
@ -119,7 +119,7 @@ GET /_synapse/admin/v2/users?from=0&limit=10&guests=false
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
A response body like the following is returned: A response body like the following is returned:
@ -237,7 +237,7 @@ See also: [Client Server
API Whois](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid). API Whois](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid).
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
It returns a JSON body like the following: It returns a JSON body like the following:
@ -294,7 +294,7 @@ with a body of:
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
The erase parameter is optional and defaults to `false`. The erase parameter is optional and defaults to `false`.
An empty body may be passed for backwards compatibility. An empty body may be passed for backwards compatibility.
@ -339,7 +339,7 @@ with a body of:
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
The parameter `new_password` is required. The parameter `new_password` is required.
The parameter `logout_devices` is optional and defaults to `true`. The parameter `logout_devices` is optional and defaults to `true`.
@ -354,7 +354,7 @@ GET /_synapse/admin/v1/users/<user_id>/admin
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
A response body like the following is returned: A response body like the following is returned:
@ -384,7 +384,7 @@ with a body of:
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
## List room memberships of a user ## List room memberships of a user
@ -398,7 +398,7 @@ GET /_synapse/admin/v1/users/<user_id>/joined_rooms
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
A response body like the following is returned: A response body like the following is returned:
@ -443,7 +443,7 @@ GET /_synapse/admin/v1/users/<user_id>/media
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
A response body like the following is returned: A response body like the following is returned:
@ -591,7 +591,7 @@ GET /_synapse/admin/v2/users/<user_id>/devices
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
A response body like the following is returned: A response body like the following is returned:
@ -659,7 +659,7 @@ POST /_synapse/admin/v2/users/<user_id>/delete_devices
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
An empty JSON dict is returned. An empty JSON dict is returned.
@ -683,7 +683,7 @@ GET /_synapse/admin/v2/users/<user_id>/devices/<device_id>
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
A response body like the following is returned: A response body like the following is returned:
@ -731,7 +731,7 @@ PUT /_synapse/admin/v2/users/<user_id>/devices/<device_id>
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
An empty JSON dict is returned. An empty JSON dict is returned.
@ -760,7 +760,7 @@ DELETE /_synapse/admin/v2/users/<user_id>/devices/<device_id>
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
An empty JSON dict is returned. An empty JSON dict is returned.
@ -781,7 +781,7 @@ GET /_synapse/admin/v1/users/<user_id>/pushers
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
A response body like the following is returned: A response body like the following is returned:
@ -872,7 +872,7 @@ POST /_synapse/admin/v1/users/<user_id>/shadow_ban
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
An empty JSON dict is returned. An empty JSON dict is returned.
@ -897,7 +897,7 @@ GET /_synapse/admin/v1/users/<user_id>/override_ratelimit
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
A response body like the following is returned: A response body like the following is returned:
@ -939,7 +939,7 @@ POST /_synapse/admin/v1/users/<user_id>/override_ratelimit
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
A response body like the following is returned: A response body like the following is returned:
@ -984,7 +984,7 @@ DELETE /_synapse/admin/v1/users/<user_id>/override_ratelimit
``` ```
To use it, you will need to authenticate by providing an `access_token` for a To use it, you will need to authenticate by providing an `access_token` for a
server admin: [Admin API](../../usage/administration/admin_api) server admin: [Admin API](../usage/administration/admin_api)
An empty JSON dict is returned. An empty JSON dict is returned.

View file

@ -24,8 +24,8 @@ To enable this, first create templates for the policy and success pages.
These should be stored on the local filesystem. These should be stored on the local filesystem.
These templates use the [Jinja2](http://jinja.pocoo.org) templating language, These templates use the [Jinja2](http://jinja.pocoo.org) templating language,
and [docs/privacy_policy_templates](privacy_policy_templates) gives and [docs/privacy_policy_templates](https://github.com/matrix-org/synapse/tree/develop/docs/privacy_policy_templates/)
examples of the sort of thing that can be done. gives examples of the sort of thing that can be done.
Note that the templates must be stored under a name giving the language of the Note that the templates must be stored under a name giving the language of the
template - currently this must always be `en` (for "English"); template - currently this must always be `en` (for "English");

View file

@ -14,7 +14,7 @@ you set the `server_name` to match your machine's public DNS hostname.
For this default configuration to work, you will need to listen for TLS For this default configuration to work, you will need to listen for TLS
connections on port 8448. The preferred way to do that is by using a connections on port 8448. The preferred way to do that is by using a
reverse proxy: see [reverse_proxy.md](<reverse_proxy.md>) for instructions reverse proxy: see [reverse_proxy.md](reverse_proxy.md) for instructions
on how to correctly set one up. on how to correctly set one up.
In some cases you might not want to run Synapse on the machine that has In some cases you might not want to run Synapse on the machine that has
@ -44,7 +44,7 @@ a complicated dance which requires connections in both directions).
Another common problem is that people on other servers can't join rooms that Another common problem is that people on other servers can't join rooms that
you invite them to. This can be caused by an incorrectly-configured reverse you invite them to. This can be caused by an incorrectly-configured reverse
proxy: see [reverse_proxy.md](<reverse_proxy.md>) for instructions on how to correctly proxy: see [reverse_proxy.md](reverse_proxy.md) for instructions on how to correctly
configure a reverse proxy. configure a reverse proxy.
### Known issues ### Known issues
@ -63,4 +63,4 @@ release of Synapse.
If you want to get up and running quickly with a trio of homeservers in a If you want to get up and running quickly with a trio of homeservers in a
private federation, there is a script in the `demo` directory. This is mainly private federation, there is a script in the `demo` directory. This is mainly
useful just for development purposes. See [demo/README](<../demo/README>). useful just for development purposes. See [demo/README](https://github.com/matrix-org/synapse/tree/develop/demo/).

View file

@ -51,7 +51,7 @@ clients.
Support for this feature can be enabled and configured in the Support for this feature can be enabled and configured in the
`retention` section of the Synapse configuration file (see the `retention` section of the Synapse configuration file (see the
[sample file](https://github.com/matrix-org/synapse/blob/v1.7.3/docs/sample_config.yaml#L332-L393)). [sample file](https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518)).
To enable support for message retention policies, set the setting To enable support for message retention policies, set the setting
`enabled` in this section to `true`. `enabled` in this section to `true`.
@ -87,7 +87,7 @@ expired events from the database. They are only run if support for
message retention policies is enabled in the server's configuration. If message retention policies is enabled in the server's configuration. If
no configuration for purge jobs is configured by the server admin, no configuration for purge jobs is configured by the server admin,
Synapse will use a default configuration, which is described in the Synapse will use a default configuration, which is described in the
[sample configuration file](https://github.com/matrix-org/synapse/blob/master/docs/sample_config.yaml#L332-L393). [sample configuration file](https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518).
Some server admins might want a finer control on when events are removed Some server admins might want a finer control on when events are removed
depending on an event's room's policy. This can be done by setting the depending on an event's room's policy. This can be done by setting the

View file

@ -72,8 +72,7 @@
## Monitoring workers ## Monitoring workers
To monitor a Synapse installation using To monitor a Synapse installation using [workers](workers.md),
[workers](https://github.com/matrix-org/synapse/blob/master/docs/workers.md),
every worker needs to be monitored independently, in addition to every worker needs to be monitored independently, in addition to
the main homeserver process. This is because workers don't send the main homeserver process. This is because workers don't send
their metrics to the main homeserver process, but expose them their metrics to the main homeserver process, but expose them

View file

@ -30,7 +30,7 @@ presence to (for those users that the receiving user is considered interested in
It does not include state for users who are currently offline, and it can only be It does not include state for users who are currently offline, and it can only be
called on workers that support sending federation. Additionally, this method must called on workers that support sending federation. Additionally, this method must
only be called from the process that has been configured to write to the only be called from the process that has been configured to write to the
the [presence stream](https://github.com/matrix-org/synapse/blob/master/docs/workers.md#stream-writers). the [presence stream](workers.md#stream-writers).
By default, this is the main process, but another worker can be configured to do By default, this is the main process, but another worker can be configured to do
so. so.

View file

@ -21,7 +21,7 @@ port 8448. Where these are different, we refer to the 'client port' and the
'federation port'. See [the Matrix 'federation port'. See [the Matrix
specification](https://matrix.org/docs/spec/server_server/latest#resolving-server-names) specification](https://matrix.org/docs/spec/server_server/latest#resolving-server-names)
for more details of the algorithm used for federation connections, and for more details of the algorithm used for federation connections, and
[delegate.md](<delegate.md>) for instructions on setting up delegation. [delegate.md](delegate.md) for instructions on setting up delegation.
**NOTE**: Your reverse proxy must not `canonicalise` or `normalise` **NOTE**: Your reverse proxy must not `canonicalise` or `normalise`
the requested URI in any way (for example, by decoding `%xx` escapes). the requested URI in any way (for example, by decoding `%xx` escapes).

View file

@ -108,7 +108,7 @@ A custom mapping provider must specify the following methods:
Synapse has a built-in OpenID mapping provider if a custom provider isn't Synapse has a built-in OpenID mapping provider if a custom provider isn't
specified in the config. It is located at specified in the config. It is located at
[`synapse.handlers.oidc.JinjaOidcMappingProvider`](../synapse/handlers/oidc.py). [`synapse.handlers.oidc.JinjaOidcMappingProvider`](https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/oidc.py).
## SAML Mapping Providers ## SAML Mapping Providers
@ -194,4 +194,4 @@ A custom mapping provider must specify the following methods:
Synapse has a built-in SAML mapping provider if a custom provider isn't Synapse has a built-in SAML mapping provider if a custom provider isn't
specified in the config. It is located at specified in the config. It is located at
[`synapse.handlers.saml.DefaultSamlMappingProvider`](../synapse/handlers/saml.py). [`synapse.handlers.saml.DefaultSamlMappingProvider`](https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/saml.py).

View file

@ -6,16 +6,18 @@ well as a `matrix-synapse-worker@` service template for any workers you
require. Additionally, to group the required services, it sets up a require. Additionally, to group the required services, it sets up a
`matrix-synapse.target`. `matrix-synapse.target`.
See the folder [system](system) for the systemd unit files. See the folder [system](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/)
for the systemd unit files.
The folder [workers](workers) contains an example configuration for the The folder [workers](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/workers/)
`federation_reader` worker. contains an example configuration for the `federation_reader` worker.
## Synapse configuration files ## Synapse configuration files
See [workers.md](../workers.md) for information on how to set up the See [workers.md](../workers.md) for information on how to set up the
configuration files and reverse-proxy correctly. You can find an example worker configuration files and reverse-proxy correctly. You can find an example worker
config in the [workers](workers) folder. config in the [workers](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/workers/)
folder.
Systemd manages daemonization itself, so ensure that none of the configuration Systemd manages daemonization itself, so ensure that none of the configuration
files set either `daemonize` or `worker_daemonize`. files set either `daemonize` or `worker_daemonize`.
@ -29,8 +31,8 @@ There is no need for a separate configuration file for the master process.
## Set up ## Set up
1. Adjust synapse configuration files as above. 1. Adjust synapse configuration files as above.
1. Copy the `*.service` and `*.target` files in [system](system) to 1. Copy the `*.service` and `*.target` files in [system](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/)
`/etc/systemd/system`. to `/etc/systemd/system`.
1. Run `systemctl daemon-reload` to tell systemd to load the new unit files. 1. Run `systemctl daemon-reload` to tell systemd to load the new unit files.
1. Run `systemctl enable matrix-synapse.service`. This will configure the 1. Run `systemctl enable matrix-synapse.service`. This will configure the
synapse master process to be started as part of the `matrix-synapse.target` synapse master process to be started as part of the `matrix-synapse.target`

View file

@ -16,7 +16,7 @@ workers only work with PostgreSQL-based Synapse deployments. SQLite should only
be used for demo purposes and any admin considering workers should already be be used for demo purposes and any admin considering workers should already be
running PostgreSQL. running PostgreSQL.
See also https://matrix.org/blog/2020/11/03/how-we-fixed-synapses-scalability See also [Matrix.org blog post](https://matrix.org/blog/2020/11/03/how-we-fixed-synapses-scalability)
for a higher level overview. for a higher level overview.
## Main process/worker communication ## Main process/worker communication