diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/SUMMARY.md | 6 | ||||
| -rw-r--r-- | docs/admin_api/purge_history_api.md | 2 | ||||
| -rw-r--r-- | docs/admin_api/rooms.md | 191 | ||||
| -rw-r--r-- | docs/admin_api/user_admin_api.md | 14 | ||||
| -rw-r--r-- | docs/ancient_architecture_notes.md | 6 | ||||
| -rw-r--r-- | docs/setup/installation.md | 6 | ||||
| -rw-r--r-- | docs/turn-howto.md | 16 | ||||
| -rw-r--r-- | docs/usage/configuration/user_authentication/single_sign_on/README.md | 5 | ||||
| -rw-r--r-- | docs/usage/configuration/user_authentication/single_sign_on/cas.md | 8 | ||||
| -rw-r--r-- | docs/usage/configuration/user_authentication/single_sign_on/saml.md | 8 |
10 files changed, 230 insertions, 32 deletions
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 04320ab07b..cdedf8bccc 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -23,10 +23,10 @@ - [Structured Logging](structured_logging.md) - [Templates](templates.md) - [User Authentication](usage/configuration/user_authentication/README.md) - - [Single-Sign On]() + - [Single-Sign On](usage/configuration/user_authentication/single_sign_on/README.md) - [OpenID Connect](openid.md) - - [SAML]() - - [CAS]() + - [SAML](usage/configuration/user_authentication/single_sign_on/saml.md) + - [CAS](usage/configuration/user_authentication/single_sign_on/cas.md) - [SSO Mapping Providers](sso_mapping_providers.md) - [Password Auth Providers](password_auth_providers.md) - [JSON Web Tokens](jwt.md) diff --git a/docs/admin_api/purge_history_api.md b/docs/admin_api/purge_history_api.md index bd29e29ab8..277e28d9cb 100644 --- a/docs/admin_api/purge_history_api.md +++ b/docs/admin_api/purge_history_api.md @@ -70,6 +70,8 @@ This API returns a JSON body like the following: The status will be one of `active`, `complete`, or `failed`. +If `status` is `failed` there will be a string `error` with the error message. + ## Reclaim disk space (Postgres) To reclaim the disk space and return it to the operating system, you need to run diff --git a/docs/admin_api/rooms.md b/docs/admin_api/rooms.md index ab6b82a082..6a6ae92d66 100644 --- a/docs/admin_api/rooms.md +++ b/docs/admin_api/rooms.md @@ -4,6 +4,9 @@ - [Room Members API](#room-members-api) - [Room State API](#room-state-api) - [Delete Room API](#delete-room-api) + * [Version 1 (old version)](#version-1-old-version) + * [Version 2 (new version)](#version-2-new-version) + * [Status of deleting rooms](#status-of-deleting-rooms) * [Undoing room shutdowns](#undoing-room-shutdowns) - [Make Room Admin API](#make-room-admin-api) - [Forward Extremities Admin API](#forward-extremities-admin-api) @@ -396,18 +399,33 @@ The new room will be created with the user specified by the `new_room_user_id` p as room administrator and will contain a message explaining what happened. Users invited to the new room will have power level `-10` by default, and thus be unable to speak. -If `block` is `True` it prevents new joins to the old room. +If `block` is `true`, users will be prevented from joining the old room. +This option can in [Version 1](#version-1-old-version) also be used to pre-emptively +block a room, even if it's unknown to this homeserver. In this case, the room will be +blocked, and no further action will be taken. If `block` is `false`, attempting to +delete an unknown room is invalid and will be rejected as a bad request. This API will remove all trace of the old room from your database after removing all local users. If `purge` is `true` (the default), all traces of the old room will be removed from your database after removing all local users. If you do not want this to happen, set `purge` to `false`. -Depending on the amount of history being purged a call to the API may take +Depending on the amount of history being purged, a call to the API may take several minutes or longer. The local server will only have the power to move local user and room aliases to the new room. Users on other servers will be unaffected. +To use it, you will need to authenticate by providing an ``access_token`` for a +server admin: see [Admin API](../usage/administration/admin_api). + +## Version 1 (old version) + +This version works synchronously. That means you only get the response once the server has +finished the action, which may take a long time. If you request the same action +a second time, and the server has not finished the first one, the second request will block. +This is fixed in version 2 of this API. The parameters are the same in both APIs. +This API will become deprecated in the future. + The API is: ``` @@ -426,9 +444,6 @@ with a body of: } ``` -To use it, you will need to authenticate by providing an ``access_token`` for a -server admin: see [Admin API](../usage/administration/admin_api). - A response body like the following is returned: ```json @@ -445,6 +460,44 @@ A response body like the following is returned: } ``` +The parameters and response values have the same format as +[version 2](#version-2-new-version) of the API. + +## Version 2 (new version) + +**Note**: This API is new, experimental and "subject to change". + +This version works asynchronously, meaning you get the response from server immediately +while the server works on that task in background. You can then request the status of the action +to check if it has completed. + +The API is: + +``` +DELETE /_synapse/admin/v2/rooms/<room_id> +``` + +with a body of: + +```json +{ + "new_room_user_id": "@someuser:example.com", + "room_name": "Content Violation Notification", + "message": "Bad Room has been shutdown due to content violations on this server. Please review our Terms of Service.", + "block": true, + "purge": true +} +``` + +The API starts the shut down and purge running, and returns immediately with a JSON body with +a purge id: + +```json +{ + "delete_id": "<opaque id>" +} +``` + **Parameters** The following parameters should be set in the URL: @@ -464,8 +517,10 @@ The following JSON body parameters are available: `new_room_user_id` in the new room. Ideally this will clearly convey why the original room was shut down. Defaults to `Sharing illegal content on this server is not permitted and rooms in violation will be blocked.` -* `block` - Optional. If set to `true`, this room will be added to a blocking list, preventing - future attempts to join the room. Defaults to `false`. +* `block` - Optional. If set to `true`, this room will be added to a blocking list, + preventing future attempts to join the room. Rooms can be blocked + even if they're not yet known to the homeserver (only with + [Version 1](#version-1-old-version) of the API). Defaults to `false`. * `purge` - Optional. If set to `true`, it will remove all traces of the room from your database. Defaults to `true`. * `force_purge` - Optional, and ignored unless `purge` is `true`. If set to `true`, it @@ -475,16 +530,124 @@ The following JSON body parameters are available: The JSON body must not be empty. The body must be at least `{}`. -**Response** +## Status of deleting rooms -The following fields are returned in the JSON response body: +**Note**: This API is new, experimental and "subject to change". + +It is possible to query the status of the background task for deleting rooms. +The status can be queried up to 24 hours after completion of the task, +or until Synapse is restarted (whichever happens first). + +### Query by `room_id` -* `kicked_users` - An array of users (`user_id`) that were kicked. -* `failed_to_kick_users` - An array of users (`user_id`) that that were not kicked. -* `local_aliases` - An array of strings representing the local aliases that were migrated from - the old room to the new. -* `new_room_id` - A string representing the room ID of the new room. +With this API you can get the status of all active deletion tasks, and all those completed in the last 24h, +for the given `room_id`. + +The API is: + +``` +GET /_synapse/admin/v2/rooms/<room_id>/delete_status +``` + +A response body like the following is returned: + +```json +{ + "results": [ + { + "delete_id": "delete_id1", + "status": "failed", + "error": "error message", + "shutdown_room": { + "kicked_users": [], + "failed_to_kick_users": [], + "local_aliases": [], + "new_room_id": null + } + }, { + "delete_id": "delete_id2", + "status": "purging", + "shutdown_room": { + "kicked_users": [ + "@foobar:example.com" + ], + "failed_to_kick_users": [], + "local_aliases": [ + "#badroom:example.com", + "#evilsaloon:example.com" + ], + "new_room_id": "!newroomid:example.com" + } + } + ] +} +``` + +**Parameters** + +The following parameters should be set in the URL: + +* `room_id` - The ID of the room. + +### Query by `delete_id` + +With this API you can get the status of one specific task by `delete_id`. + +The API is: + +``` +GET /_synapse/admin/v2/rooms/delete_status/<delete_id> +``` + +A response body like the following is returned: + +```json +{ + "status": "purging", + "shutdown_room": { + "kicked_users": [ + "@foobar:example.com" + ], + "failed_to_kick_users": [], + "local_aliases": [ + "#badroom:example.com", + "#evilsaloon:example.com" + ], + "new_room_id": "!newroomid:example.com" + } +} +``` + +**Parameters** + +The following parameters should be set in the URL: + +* `delete_id` - The ID for this delete. + +### Response + +The following fields are returned in the JSON response body: +- `results` - An array of objects, each containing information about one task. + This field is omitted from the result when you query by `delete_id`. + Task objects contain the following fields: + - `delete_id` - The ID for this purge if you query by `room_id`. + - `status` - The status will be one of: + - `shutting_down` - The process is removing users from the room. + - `purging` - The process is purging the room and event data from database. + - `complete` - The process has completed successfully. + - `failed` - The process is aborted, an error has occurred. + - `error` - A string that shows an error message if `status` is `failed`. + Otherwise this field is hidden. + - `shutdown_room` - An object containing information about the result of shutting down the room. + *Note:* The result is shown after removing the room members. + The delete process can still be running. Please pay attention to the `status`. + - `kicked_users` - An array of users (`user_id`) that were kicked. + - `failed_to_kick_users` - An array of users (`user_id`) that that were not kicked. + - `local_aliases` - An array of strings representing the local aliases that were + migrated from the old room to the new. + - `new_room_id` - A string representing the room ID of the new room, or `null` if + no such room was created. ## Undoing room deletions diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md index f03539c9f0..ba574d795f 100644 --- a/docs/admin_api/user_admin_api.md +++ b/docs/admin_api/user_admin_api.md @@ -948,7 +948,7 @@ The following fields are returned in the JSON response body: See also the [Client-Server API Spec on pushers](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-pushers). -## Shadow-banning users +## Controlling whether a user is shadow-banned Shadow-banning is a useful tool for moderating malicious or egregiously abusive users. A shadow-banned users receives successful responses to their client-server API requests, @@ -961,16 +961,22 @@ or broken behaviour for the client. A shadow-banned user will not receive any notification and it is generally more appropriate to ban or kick abusive users. A shadow-banned user will be unable to contact anyone on the server. -The API is: +To shadow-ban a user the API is: ``` POST /_synapse/admin/v1/users/<user_id>/shadow_ban ``` +To un-shadow-ban a user the API is: + +``` +DELETE /_synapse/admin/v1/users/<user_id>/shadow_ban +``` + To use it, you will need to authenticate by providing an `access_token` for a server admin: [Admin API](../usage/administration/admin_api) -An empty JSON dict is returned. +An empty JSON dict is returned in both cases. **Parameters** @@ -1107,7 +1113,7 @@ This endpoint will work even if registration is disabled on the server, unlike The API is: ``` -POST /_synapse/admin/v1/username_availabile?username=$localpart +GET /_synapse/admin/v1/username_available?username=$localpart ``` The request and response format is the same as the [/_matrix/client/r0/register/available](https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-register-available) API. diff --git a/docs/ancient_architecture_notes.md b/docs/ancient_architecture_notes.md index 3ea8976cc7..07bb199d7a 100644 --- a/docs/ancient_architecture_notes.md +++ b/docs/ancient_architecture_notes.md @@ -7,7 +7,7 @@ ## Server to Server Stack -To use the server to server stack, home servers should only need to +To use the server to server stack, homeservers should only need to interact with the Messaging layer. The server to server side of things is designed into 4 distinct layers: @@ -23,7 +23,7 @@ Server with a domain specific API. 1. **Messaging Layer** - This is what the rest of the Home Server hits to send messages, join rooms, + This is what the rest of the homeserver hits to send messages, join rooms, etc. It also allows you to register callbacks for when it get's notified by lower levels that e.g. a new message has been received. @@ -45,7 +45,7 @@ Server with a domain specific API. For incoming PDUs, it has to check the PDUs it references to see if we have missed any. If we have go and ask someone (another - home server) for it. + homeserver) for it. 3. **Transaction Layer** diff --git a/docs/setup/installation.md b/docs/setup/installation.md index 3e08024441..16562be953 100644 --- a/docs/setup/installation.md +++ b/docs/setup/installation.md @@ -76,6 +76,12 @@ 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 We do not recommend using the packages from the default Debian `buster` diff --git a/docs/turn-howto.md b/docs/turn-howto.md index e2f66f60e2..e6812de69e 100644 --- a/docs/turn-howto.md +++ b/docs/turn-howto.md @@ -1,12 +1,12 @@ # Overview -This document explains how to enable VoIP relaying on your Home Server with +This document explains how to enable VoIP relaying on your homeserver with TURN. -The synapse Matrix Home Server supports integration with TURN server via the +The synapse Matrix homeserver supports integration with TURN server via the [TURN server REST API](<https://tools.ietf.org/html/draft-uberti-behave-turn-rest-00>). This -allows the Home Server to generate credentials that are valid for use on the -TURN server through the use of a secret shared between the Home Server and the +allows the homeserver to generate credentials that are valid for use on the +TURN server through the use of a secret shared between the homeserver and the TURN server. The following sections describe how to install [coturn](<https://github.com/coturn/coturn>) (which implements the TURN REST API) and integrate it with synapse. @@ -165,18 +165,18 @@ This will install and start a systemd service called `coturn`. ## Synapse setup -Your home server configuration file needs the following extra keys: +Your homeserver configuration file needs the following extra keys: 1. "`turn_uris`": This needs to be a yaml list of public-facing URIs for your TURN server to be given out to your clients. Add separate entries for each transport your TURN server supports. 2. "`turn_shared_secret`": This is the secret shared between your - Home server and your TURN server, so you should set it to the same + homeserver and your TURN server, so you should set it to the same string you used in turnserver.conf. 3. "`turn_user_lifetime`": This is the amount of time credentials - generated by your Home Server are valid for (in milliseconds). + generated by your homeserver are valid for (in milliseconds). Shorter times offer less potential for abuse at the expense of - increased traffic between web clients and your home server to + increased traffic between web clients and your homeserver to refresh credentials. The TURN REST API specification recommends one day (86400000). 4. "`turn_allow_guests`": Whether to allow guest users to use the diff --git a/docs/usage/configuration/user_authentication/single_sign_on/README.md b/docs/usage/configuration/user_authentication/single_sign_on/README.md new file mode 100644 index 0000000000..b94aad92cf --- /dev/null +++ b/docs/usage/configuration/user_authentication/single_sign_on/README.md @@ -0,0 +1,5 @@ +# Single Sign-On + +Synapse supports single sign-on through the SAML, Open ID Connect or CAS protocols. +LDAP and other login methods are supported through first and third-party password +auth provider modules. \ No newline at end of file diff --git a/docs/usage/configuration/user_authentication/single_sign_on/cas.md b/docs/usage/configuration/user_authentication/single_sign_on/cas.md new file mode 100644 index 0000000000..3bac1b29f0 --- /dev/null +++ b/docs/usage/configuration/user_authentication/single_sign_on/cas.md @@ -0,0 +1,8 @@ +# CAS + +Synapse supports authenticating users via the [Central Authentication +Service protocol](https://en.wikipedia.org/wiki/Central_Authentication_Service) +(CAS) natively. + +Please see the `cas_config` and `sso` sections of the [Synapse configuration +file](../../../configuration/homeserver_sample_config.md) for more details. \ No newline at end of file diff --git a/docs/usage/configuration/user_authentication/single_sign_on/saml.md b/docs/usage/configuration/user_authentication/single_sign_on/saml.md new file mode 100644 index 0000000000..2b6f052cc1 --- /dev/null +++ b/docs/usage/configuration/user_authentication/single_sign_on/saml.md @@ -0,0 +1,8 @@ +# SAML + +Synapse supports authenticating users via the [Security Assertion +Markup Language](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) +(SAML) protocol natively. + +Please see the `saml2_config` and `sso` sections of the [Synapse configuration +file](../../../configuration/homeserver_sample_config.md) for more details. \ No newline at end of file |