diff --git a/latest/404.html b/latest/404.html index 721eb3da7d..c39141e953 100644 --- a/latest/404.html +++ b/latest/404.html @@ -101,7 +101,7 @@ diff --git a/latest/CAPTCHA_SETUP.html b/latest/CAPTCHA_SETUP.html index e69713a598..adec4d1711 100644 --- a/latest/CAPTCHA_SETUP.html +++ b/latest/CAPTCHA_SETUP.html @@ -99,7 +99,7 @@ diff --git a/latest/MSC1711_certificates_FAQ.html b/latest/MSC1711_certificates_FAQ.html index 1bc06c2c9d..61bc3f526c 100644 --- a/latest/MSC1711_certificates_FAQ.html +++ b/latest/MSC1711_certificates_FAQ.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/account_validity.html b/latest/admin_api/account_validity.html index 5a2f583c5a..b1f6dedf63 100644 --- a/latest/admin_api/account_validity.html +++ b/latest/admin_api/account_validity.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/delete_group.html b/latest/admin_api/delete_group.html index 4dc5bfd28f..f48720c8b3 100644 --- a/latest/admin_api/delete_group.html +++ b/latest/admin_api/delete_group.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/event_reports.html b/latest/admin_api/event_reports.html index e8541999ff..f8ca18717e 100644 --- a/latest/admin_api/event_reports.html +++ b/latest/admin_api/event_reports.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/media_admin_api.html b/latest/admin_api/media_admin_api.html index 2af7ae084f..321d07c6dd 100644 --- a/latest/admin_api/media_admin_api.html +++ b/latest/admin_api/media_admin_api.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/purge_history_api.html b/latest/admin_api/purge_history_api.html index d4b0e89228..0ab311d650 100644 --- a/latest/admin_api/purge_history_api.html +++ b/latest/admin_api/purge_history_api.html @@ -99,7 +99,7 @@ @@ -228,6 +228,7 @@ server admin.

}

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 VACUUM FULL; on the database.

diff --git a/latest/admin_api/register_api.html b/latest/admin_api/register_api.html index 30800a5dbe..cd2a137112 100644 --- a/latest/admin_api/register_api.html +++ b/latest/admin_api/register_api.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/room_membership.html b/latest/admin_api/room_membership.html index 5c43f59a5c..d043e2b97f 100644 --- a/latest/admin_api/room_membership.html +++ b/latest/admin_api/room_membership.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/rooms.html b/latest/admin_api/rooms.html index 4d9b06b619..8e31f898fd 100644 --- a/latest/admin_api/rooms.html +++ b/latest/admin_api/rooms.html @@ -99,7 +99,7 @@ @@ -188,8 +188,12 @@
  • Room Details API
  • Room Members API
  • Room State API
  • +
  • Block Room API
  • Delete Room API
  • @@ -536,6 +540,61 @@ end of the list.

    ] } +

    Block Room API

    +

    The Block Room admin API allows server admins to block and unblock rooms, +and query to see if a given room is blocked. +This API can be used to pre-emptively block a room, even if it's unknown to this +homeserver. Users will be prevented from joining a blocked room.

    +

    Block or unblock a room

    +

    The API is:

    +
    PUT /_synapse/admin/v1/rooms/<room_id>/block
    +
    +

    with a body of:

    +
    {
    +    "block": true
    +}
    +
    +

    A response body like the following is returned:

    +
    {
    +    "block": true
    +}
    +
    +

    Parameters

    +

    The following parameters should be set in the URL:

    + +

    The following JSON body parameters are available:

    + +

    Response

    +

    The following fields are possible in the JSON response body:

    + +

    Get block status

    +

    The API is:

    +
    GET /_synapse/admin/v1/rooms/<room_id>/block
    +
    +

    A response body like the following is returned:

    +
    {
    +    "block": true,
    +    "user_id": "<user_id>"
    +}
    +
    +

    Parameters

    +

    The following parameters should be set in the URL:

    + +

    Response

    +

    The following fields are possible in the JSON response body:

    +

    Delete Room API

    The Delete Room admin API allows server admins to remove rooms from the server and block these rooms.

    @@ -545,15 +604,27 @@ leave the room without any information.

    The new room will be created with the user specified by the new_room_user_id parameter 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 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.

    +

    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:

    DELETE /_synapse/admin/v1/rooms/<room_id>
     
    @@ -566,8 +637,6 @@ the new room. Users on other servers will be unaffected.

    "purge": true } -

    To use it, you will need to authenticate by providing an access_token for a -server admin: see Admin API.

    A response body like the following is returned:

    {
         "kicked_users": [
    @@ -581,6 +650,31 @@ server admin: see Admin API.

    "new_room_id": "!newroomid:example.com" }
    +

    The parameters and response values have the same format as +version 2 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:

    +
    {
    +    "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:

    +
    {
    +    "delete_id": "<opaque id>"
    +}
    +

    Parameters

    The following parameters should be set in the URL:

    The JSON body must not be empty. The body must be at least {}.

    -

    Response

    +

    Status of deleting rooms

    +

    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

    +

    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:

    +
    {
    +    "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:

    + +

    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:

    +
    {
    +    "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:

    + +

    Response

    The following fields are returned in the JSON response body:

    Undoing room deletions

    Note: This guide may be outdated by the time you read it. By nature of room deletions being performed at the database level, diff --git a/latest/admin_api/server_notices.html b/latest/admin_api/server_notices.html index 78860b66e4..85182a55b2 100644 --- a/latest/admin_api/server_notices.html +++ b/latest/admin_api/server_notices.html @@ -99,7 +99,7 @@

    diff --git a/latest/admin_api/statistics.html b/latest/admin_api/statistics.html index 7e4f50b166..116e56bfc9 100644 --- a/latest/admin_api/statistics.html +++ b/latest/admin_api/statistics.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/user_admin_api.html b/latest/admin_api/user_admin_api.html index 0efa1f241f..f9291da868 100644 --- a/latest/admin_api/user_admin_api.html +++ b/latest/admin_api/user_admin_api.html @@ -99,7 +99,7 @@ @@ -1000,7 +1000,7 @@ Max length, 512 bytes.

    See also the Client-Server API Spec on 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, but the events are not propagated into rooms. This can be an effective tool as it @@ -1010,12 +1010,15 @@ pivoting to another account.

    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

    -

    An empty JSON dict is returned.

    +

    An empty JSON dict is returned in both cases.

    Parameters

    The following parameters should be set in the URL:

    Synapse can additionally be extended to support custom authentication schemes through optional "password auth provider" modules.

    +

    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.

    Configuring Synapse to authenticate against an OpenID Connect provider

    Synapse can be configured to use an OpenID Connect Provider (OP) for authentication, instead of its own local password database.

    @@ -6735,6 +6750,18 @@ needed to add OAuth2 capabilities to your Django projects. It supports display_name_template: "{{ user.first_name }} {{ user.last_name }}" email_template: "{{ user.email }}" +

    SAML

    +

    Synapse supports authenticating users via the Security Assertion +Markup Language +(SAML) protocol natively.

    +

    Please see the saml2_config and sso sections of the Synapse configuration +file for more details.

    +

    CAS

    +

    Synapse supports authenticating users via the Central Authentication +Service protocol +(CAS) natively.

    +

    Please see the cas_config and sso sections of the Synapse configuration +file for more details.

    SSO Mapping Providers

    A mapping provider is a Python class (loaded via a Python module) that works out how to map attributes of a SSO response to Matrix-specific @@ -7116,8 +7143,9 @@ follows:

    will be removed in a future version of Synapse.

    The token field should include the JSON web token with the following claims:

    See also the Client-Server API Spec on 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, but the events are not propagated into rooms. This can be an effective tool as it @@ -11473,12 +11714,15 @@ pivoting to another account.

    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

    -

    An empty JSON dict is returned.

    +

    An empty JSON dict is returned in both cases.

    Parameters

    The following parameters should be set in the URL: