From 4e5532a0d5f17c7d16829a91b9dc4113f2246e2e Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 12:32:35 +0900 Subject: [PATCH 1/9] Update docs for Draupnir, D4A, and Mjolnir: emphasize the importance of being careful when inviting a user to the management room Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-appservice-draupnir-for-all.md | 2 +- docs/configuring-playbook-bot-draupnir.md | 4 +++- docs/configuring-playbook-bot-mjolnir.md | 4 +++- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/configuring-playbook-appservice-draupnir-for-all.md b/docs/configuring-playbook-appservice-draupnir-for-all.md index be7aacc30..8d6547dfd 100644 --- a/docs/configuring-playbook-appservice-draupnir-for-all.md +++ b/docs/configuring-playbook-appservice-draupnir-for-all.md @@ -28,7 +28,7 @@ The management room has to be given an alias, and your bot has to be invited to This management room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element clients call this powerlevel. -As noted in the Draupnir install instructions the control room is sensitive. **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. ### Set an alias to the management room diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 288cc4104..79747fae6 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -12,7 +12,9 @@ If your migrating from Mjolnir skip to [this section](#migrating-from-mjolnir-on ### 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. Anyone in this room can control the bot so it is important that you only invite trusted users to this 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. + +⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room. If you make the management room encrypted (E2EE), then you need to enable the native E2EE support (see [below](#native-e2ee-support)). diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index 2564cd2f9..4e9717b55 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -52,7 +52,9 @@ You can obtain an access token for a homeserver admin account in the same way as ### 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. Anyone in this room can control the bot so it is important that you only invite trusted users to this 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. + +⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room. If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)). From 39625aae155869a0f65d6bbada20f0491e8631c3 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 16:32:16 +0900 Subject: [PATCH 2/9] Update docs for Draupnir and Mjolnir: small edits for the common sentences Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 2 +- docs/configuring-playbook-bot-mjolnir.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 79747fae6..69ab00e60 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -16,7 +16,7 @@ Using your own account, create a new invite only room that you will use to manag ⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room. -If you make the management room encrypted (E2EE), then you need to enable the native E2EE support (see [below](#native-e2ee-support)). +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)). Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`. diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index 4e9717b55..4d44a0e7a 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -56,7 +56,7 @@ Using your own account, create a new invite only room that you will use to manag ⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room. -If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)). +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)). Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`. From 04ff68e229c9f4e2f2f9f4472e22c11bc29924f4 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 20 Jan 2025 13:08:49 +0900 Subject: [PATCH 3/9] Update docs for Draupnir and Mjolnir: tidy up the instruction to check the room ID Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 2 +- docs/configuring-playbook-bot-mjolnir.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 69ab00e60..6884d67e5 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -18,7 +18,7 @@ Using your own account, create a new invite only room that you will use to manag 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)). -Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`. +Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`. Finally invite the `@bot.draupnir:example.com` account that the playbook will create for you to the management room. Please note that clients can issue a warning that your attempting to invite a user that doesnt have a profile and might not exist. This warning is expected as your inviting the bot before its user account exists. diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index 4d44a0e7a..8d138396d 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -58,7 +58,7 @@ Using your own account, create a new invite only room that you will use to manag 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)). -Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`. +Once you have created the room you need to copy the room ID so you can specify it on your `vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`. Finally invite the `@bot.mjolnir:example.com` account you created earlier into the room. From 340e569984dd3f6c8343bba6632b8b5984ca3783 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 11:42:59 +0900 Subject: [PATCH 4/9] Update docs/configuring-playbook-appservice-draupnir-for-all.md: remove the duplicated instruction to set an alias to the management room Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-appservice-draupnir-for-all.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/configuring-playbook-appservice-draupnir-for-all.md b/docs/configuring-playbook-appservice-draupnir-for-all.md index 8d6547dfd..f2a2ade8c 100644 --- a/docs/configuring-playbook-appservice-draupnir-for-all.md +++ b/docs/configuring-playbook-appservice-draupnir-for-all.md @@ -30,10 +30,6 @@ This management room is used to control who has access to your D4A deployment. T ⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room. -### Set an alias to the management room - -Next, set an alias to the management room. - ## Adjusting the playbook configuration Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ALIAS_HERE`. From 7b6b103e01f842e1e7d32fe6e7dd1c4eae9e179a Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 11:39:59 +0900 Subject: [PATCH 5/9] Update docs/configuring-playbook-bot-draupnir.md: misc changes mainly fixing typos The typos were introduced by f15c0a46be2f9bd4adfdff207f64701560d11b13. Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 6884d67e5..bbf04217b 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -20,29 +20,29 @@ It is possible to make the management room encrypted (E2EE). If doing so, then y Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`. -Finally invite the `@bot.draupnir:example.com` account that the playbook will create for you to the management room. Please note that clients can issue a warning that your attempting to invite a user that doesnt have a profile and might not exist. This warning is expected as your inviting the bot before its user account exists. +Finally invite the `@bot.draupnir:example.com` account that the playbook will create for you to the management room. Please note that clients can issue a warning that you are attempting to invite a user that does not have a profile and might not exist. This warning is expected as your inviting the bot before its user account exists. ## End-to-End Encryption support -Decide whether you want to support having an Encrypted management room or not. Draupnir can still protect encrypted rooms without encryption support enabled. +Decide whether you want to support having an encrypted management room or not. Draupnir can still protect encrypted rooms without encryption support enabled. -Refer to Draupnir's [Documentation](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#protecting-encrypted-rooms) for more information on why you might or might not care about encryption support for protected rooms. +Refer to Draupnir's [documentation](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#protecting-encrypted-rooms) for more details about why you might want to care about encryption support for protected rooms. -**Note**: Draupnir does not support running with Pantalaimon as it would break all workflows that involve answering prompts with reactions. +**Note**: since v2.0.0 Draupnir does not support running with Pantalaimon as it would break all workflows that involve answering prompts with reactions. ### Native E2EE support -To enable the native E2EE support, you need to obtain an access token for Draupnir. +To enable the native E2EE support, you need to obtain an access token for Draupnir and set it on your `vars.yml` file. 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: ```yaml -# Enables the native E2EE Support +# Enables the native E2EE support matrix_bot_draupnir_enable_experimental_rust_crypto: true -# Access Token the bot uses to login. +# 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" ``` @@ -68,14 +68,15 @@ matrix_bot_draupnir_login_native: true matrix_bot_draupnir_management_room: "MANAGEMENT_ROOM_ID_HERE" ``` -Before Proceeding run the playbook with the following command to make sure the Draupnir user has been created. +Before proceeding to the next step, run the playbook with the following command to make sure that the bot user has been created. + ```sh ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created ``` ### Make sure the account is free from rate limiting -If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a heavily recomended step. If you do not configure it, Draupnir performance will be degraded.** +If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a highly recommended step. If you do not configure it, Draupnir performance will be degraded.** 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. @@ -114,7 +115,7 @@ matrix_bot_draupnir_abuse_reporting_enabled: true ### Extending the configuration From 2c7914d07142ee555903c631a9309a0311dd9419 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 20 Jan 2025 13:06:47 +0900 Subject: [PATCH 6/9] Update docs/configuring-playbook-bot-draupnir.md: invite the Draupnir bot after installation Now that the bot user for Draupnir is created automatically and you no longer need to register it manually since its 2.0.0 version, it does not seem to be sensible to synchronize descriptions about inviting bots between documents for Draupnir and Mjolnir. It is not friendly to instruct to invite the bot which does not exist just yet, only to let the known error message about the nonexistent user displayed. Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index bbf04217b..f95e3b3c5 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -20,8 +20,6 @@ It is possible to make the management room encrypted (E2EE). If doing so, then y Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`. -Finally invite the `@bot.draupnir:example.com` account that the playbook will create for you to the management room. Please note that clients can issue a warning that you are attempting to invite a user that does not have a profile and might not exist. This warning is expected as your inviting the bot before its user account exists. - ## End-to-End Encryption support Decide whether you want to support having an encrypted management room or not. Draupnir can still protect encrypted rooms without encryption support enabled. @@ -163,6 +161,8 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage +To use Draupnir, you need to invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier. + You can refer to the upstream [documentation](https://the-draupnir-project.github.io/draupnir-documentation/) for additional ways to use and configure Draupnir and for a more detailed usage guide. Below is a **non-exhaustive quick-start guide** for the impatient. From 7186d5fb930f731f76e72e5dbd66f9d075fe377b Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 20 Jan 2025 00:00:10 +0900 Subject: [PATCH 7/9] Update docs/configuring-playbook-bot-draupnir.md: add an anchor link to configuring-playbook-bot-mjolnir.md Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index f95e3b3c5..a79d69b66 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -6,7 +6,7 @@ See the project's [documentation](https://the-draupnir-project.github.io/draupni This documentation page is about installing Draupnir in bot mode. As an alternative, you can run a multi-instance Draupnir deployment by installing [Draupnir in appservice mode](./configuring-playbook-appservice-draupnir-for-all.md) (called Draupnir-for-all) instead. -If your migrating from Mjolnir skip to [this section](#migrating-from-mjolnir-only-required-if-migrating). +If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [this section](#migrating-from-mjolnir-only-required-if-migrating). ## Prerequisites From c4507d42e3bd07c7c94269a95d216f083dc2b89d Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 19 Jan 2025 15:33:35 +0900 Subject: [PATCH 8/9] Update docs/configuring-playbook-bot-draupnir.md: add "optoional, recommended" label to the section Unlike Mjolnir, the step is no longer required. It is optional and recommended on Draupnir, therefore it should be clarified so. Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index a79d69b66..808bc4aa6 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -72,7 +72,7 @@ Before proceeding to the next step, run the playbook with the following command ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created ``` -### Make sure the account is free from rate limiting +### Make sure the account is free from rate limiting (optional, recommended) If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a highly recommended step. If you do not configure it, Draupnir performance will be degraded.** From 887db388e8dbe060e0a8db07dd50f649348ca3dd Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 20 Jan 2025 11:55:52 +0900 Subject: [PATCH 9/9] Apply the review from another PR Cherry-picked from f7c01cca9c5a4aa6002f45fd011e0a2753a86482. Regressed by f15c0a46be2f9bd4adfdff207f64701560d11b13. Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bot-draupnir.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 808bc4aa6..bb0d479d7 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -26,7 +26,13 @@ Decide whether you want to support having an encrypted management room or not. D Refer to Draupnir's [documentation](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#protecting-encrypted-rooms) for more details about why you might want to care about encryption support for protected rooms. -**Note**: since v2.0.0 Draupnir does not support running with Pantalaimon as it would break all workflows that involve answering prompts with reactions. +### Disable Pantalaimon for Draupnir (since v2.0.0; optional) + +It is known that running Draupnir along with Pantalaimon breaks all workflows that involve answering prompts with reactions. + +If you are updating Draupnir from v1.x.x and have enabled Pantalaimon for it, you can disable Pantalaimon in favor of the native E2EE support. To disable Pantalaimon, remove the configuration `matrix_bot_draupnir_pantalaimon_use: true` from your `vars.yml` file. + +**Note**: because the management room is still encrypted, disabling it without enabling the native E2EE support will break the management room. ### Native E2EE support @@ -138,7 +144,7 @@ matrix_bot_draupnir_configuration_extension_yaml: | Replace your `matrix_bot_mjolnir` config with `matrix_bot_draupnir` config. Also disable Mjolnir if you're doing migration. -Note that Pantalaimon is unsupported by Draupnir so it is recommended to consult the instructions to enable [the native E2EE support](#native-e2ee-support). +Note that Draupnir supports E2EE natively, so you can enable it instead of Pantalaimon. It is recommended to consult the instruction [here](#native-e2ee-support). That is all you need to do due to that Draupnir can complete migration on its own.