From 30a53efaddfc8605268b588614bc9c7534042d7b Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 12:56:19 +0900 Subject: [PATCH 1/6] Update docs for Draupnir and Mjolnir: move the note about API access above Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 4 ++-- docs/configuring-playbook-bot-mjolnir.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index daa770567..e9cae6aaa 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -84,6 +84,8 @@ If your homeserver's implementation is Synapse, you will need to prevent it from This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). They can be accessed both externally and internally. +**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). + To expose the APIs publicly, add the following configuration to your `vars.yml` file: ```yaml @@ -92,8 +94,6 @@ matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md). -**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). - To disable rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.draupnir:example.com` with the MXID of your Draupnir: ```sh diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index 87a8f85dc..f0d96f163 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -32,6 +32,8 @@ If your homeserver's implementation is Synapse, you will need to prevent it from This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). They can be accessed both externally and internally. +**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). + To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml @@ -40,8 +42,6 @@ matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md). -**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). - To disable rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.mjolnir:example.com` with the MXID of your Mjolnir: ```sh From aea2a6d53fcd671962a0c3381ae6f9cea4dabcf9 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 13:03:10 +0900 Subject: [PATCH 2/6] Update docs for Draupnir and Mjolnir: create subsections for the instruction about making sure the account is free from rate limiting Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 6 +++++- docs/configuring-playbook-bot-mjolnir.md | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index e9cae6aaa..dce9362b1 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -86,13 +86,17 @@ This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synap **Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). +The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md). + +#### Add the configuration + To expose the APIs publicly, add the following configuration to your `vars.yml` file: ```yaml matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true ``` -The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md). +#### Run the `curl` command To disable rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.draupnir:example.com` with the MXID of your Draupnir: diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index f0d96f163..d52952724 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -34,13 +34,17 @@ This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synap **Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). +The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md). + +#### Add the configuration + To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true ``` -The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md). +#### Run the `curl` command To disable rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.mjolnir:example.com` with the MXID of your Mjolnir: From 9a0e1e64a8ac11696e6039ccdaeaed11b5363cd0 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 13:08:08 +0900 Subject: [PATCH 3/6] Update docs for Draupnir and Mjolnir: move the instruction to obtain an access token for the admin account above the one about running the curl command Also: clarify that it is the admin account that needs to be obtained for Synapse's Admin APIs. Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 12 ++++++------ docs/configuring-playbook-bot-mjolnir.md | 8 ++++++-- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index dce9362b1..89258f620 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -96,6 +96,12 @@ To expose the APIs publicly, add the following configuration to your `vars.yml` matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true ``` +#### Obtain an access token for admin account + +Manual access to Synapse's Admin APIs requires an access token for a homeserver admin account. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). + +⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. + #### Run the `curl` command To disable rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.draupnir:example.com` with the MXID of your Draupnir: @@ -104,12 +110,6 @@ To disable rate limiting, run the following command on systems that ship curl (n curl --header "Authorization: Bearer " -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit ``` -### Obtain an access token - -Manual access to Synapse's Admin API requires an access token. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). - -⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. - ### Abuse Reports Draupnir can receive reports in the management room. diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index d52952724..ef3900277 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -44,6 +44,12 @@ To expose the APIs publicly, add the following configuration to your `inventory/ matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true ``` +#### Obtain an access token for admin account + +Manual access to Synapse's Admin APIs requires an access token for a homeserver admin account. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). If you have made Mjolnir an admin, you can just use the Mjolnir token. + +⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. + #### Run the `curl` command To disable rate limiting, run the following command on systems that ship curl (note that it does not work on outdated Windows 10). Even if the APIs are not exposed to the internet, you should still be able to run the command on the homeserver locally. Before running it, make sure to replace `@bot.mjolnir:example.com` with the MXID of your Mjolnir: @@ -52,8 +58,6 @@ To disable rate limiting, run the following command on systems that ship curl (n curl --header "Authorization: Bearer " -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit ``` -You can obtain an access token for a homeserver admin account in the same way as you can do so for Mjolnir itself. If you have made Mjolnir an admin, you can just use the Mjolnir token. - ### Create a management room Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. From 8eb513a49de6e55c7b5db495893ace87e14d0660 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 13:20:40 +0900 Subject: [PATCH 4/6] Update docs for Draupnir and Mjolnir: improve instructions to replace the IDs Also: replace the placeholder for the clean access token Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 6 +++--- docs/configuring-playbook-bot-mjolnir.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 89258f620..92c9ce5af 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -40,7 +40,7 @@ To enable the native E2EE support, you need to obtain an access token for Draupn Note that native E2EE requires a clean access token that has not touched E2EE so curl is recommended as a method to obtain it. **The access token obtained via Element Web does not work with it**. Refer to the documentation on [how to obtain an access token via curl](obtaining-access-tokens.md#obtain-an-access-token-via-curl). -To enable the native E2EE support, add the following configuration to your `vars.yml` file: +To enable the native E2EE support, add the following configuration to your `vars.yml` file. Make sure to replace `CLEAN_ACCESS_TOKEN_HERE` with the access token you obtained just now. ```yaml # Enables the native E2EE support @@ -48,12 +48,12 @@ matrix_bot_draupnir_enable_experimental_rust_crypto: true # Access token which the bot will use for logging in. # Comment out `matrix_bot_draupnir_login_native` when using this option. -matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE" +matrix_bot_draupnir_access_token: "CLEAN_ACCESS_TOKEN_HERE" ``` ## Adjusting the playbook configuration -To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`. +To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created earlier. ```yaml # Enable Draupnir diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index ef3900277..f5218a87f 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -72,7 +72,7 @@ Finally invite the `@bot.mjolnir:example.com` account you created earlier into t ## Adjusting the playbook configuration -To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`. +To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the one of the room which you have created just now. ```yaml # Enable Mjolnir From 2698ed85a045e9166acd49329cde92622decd2e8 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Tue, 21 Jan 2025 08:13:31 +0200 Subject: [PATCH 5/6] Replace old warnings with Github Markdown Warnings Ref: https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3980 --- docs/configuring-playbook-bot-mjolnir.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index f5218a87f..78337025c 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -24,7 +24,8 @@ If you would like Mjolnir to be able to deactivate users, move aliases, shutdown The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). -⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. +> [!WARNING] +> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. ### Make sure the account is free from rate limiting @@ -48,7 +49,8 @@ matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true Manual access to Synapse's Admin APIs requires an access token for a homeserver admin account. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). If you have made Mjolnir an admin, you can just use the Mjolnir token. -⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. +> [!WARNING] +> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. #### Run the `curl` command @@ -62,7 +64,8 @@ curl --header "Authorization: Bearer " -X POST https://matrix.exam Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. -⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room. +> [!WARNING] +> Anyone in this room can control the bot so it is important that you only invite trusted users to this room. It is possible to make the management room encrypted (E2EE). If doing so, then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)). From 3343eadd466c52c61468531f765e7177356560cc Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Tue, 21 Jan 2025 08:14:49 +0200 Subject: [PATCH 6/6] Replace old warnings with Github Markdown Warnings on Draupnir doc page Ref: https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3980 --- docs/configuring-playbook-bot-draupnir.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 92c9ce5af..ce4ac494f 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -14,7 +14,8 @@ If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [ Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. -⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room. +> [!WARNING] +> Anyone in this room can control the bot so it is important that you only invite trusted users to this room. It is possible to make the management room encrypted (E2EE). If doing so, then you need to enable the native E2EE support (see [below](#native-e2ee-support)). @@ -100,7 +101,8 @@ matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true Manual access to Synapse's Admin APIs requires an access token for a homeserver admin account. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). -⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. +> [!WARNING] +> Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. #### Run the `curl` command