diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index 0bda701cd..c38c88eff 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -128,53 +128,6 @@ Then, run the playbook with the following command to make sure that the bot user ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created ``` -### Make sure the account is free from rate limiting (recommended) - -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.** - -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. - -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 -``` - -Then, run the playbook with the following command to apply the configuration to the server *without starting the systemd services*: - -```sh -ansible-playbook -i inventory/hosts setup.yml --tags=setup-all -``` - -**Notes**: - -- 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). - -#### 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). - -#### Run the `curl` command - -After applying the configuration to the server and obtaining the access token for the admin account, run the following command on systems that ship curl to discharge rate limiting. - -Before running it, make sure to replace: -- `ADMIN_ACCESS_TOKEN_HERE` with the access token of the admin account -- `example.com` with your base domain -- `@bot.draupnir:example.com` with the MXID of your Draupnir - -```sh -curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit -``` - -**Notes**: - -- The command does not work on the 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. - ### Abuse Reports Draupnir can receive reports in the management room. @@ -234,6 +187,53 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components ([Pantalaimon](#disable-pantalaimon-for-draupnir-since-v2-0-0), for example), you'd need to run `just setup-all`, or these components will still remain installed. +### Discharge rate limiting for Draupnir (recommended) + +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.** + +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. + +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 +``` + +Then, run the playbook again with the following command to apply the configuration to the server: + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` + +**Notes**: + +- 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). + +#### 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). + +#### Run the `curl` command + +After applying the configuration to the server and obtaining the access token for the admin account, run the following command on systems that ship curl to discharge rate limiting. + +Before running it, make sure to replace: +- `ADMIN_ACCESS_TOKEN_HERE` with the access token of the admin account +- `example.com` with your base domain +- `@bot.draupnir:example.com` with the MXID of your Draupnir's bot user + +```sh +curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir:example.com/override_ratelimit +``` + +**Notes**: + +- The command does not work on the 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. + ## Usage To use Draupnir, you need to invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier. diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index cc19497df..2f2626ea3 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -26,55 +26,6 @@ The bot requires an access token to be able to connect to your homeserver. Refer ⚠️ **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 - -If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a required step. If you do not configure it, Mjolnir will crash.** - -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. - -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 -``` - -Then, run the playbook with the following command to apply the configuration to the server *without starting the systemd services*: - -```sh -ansible-playbook -i inventory/hosts setup.yml --tags=setup-all -``` - -**Notes**: - -- 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). - -#### 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. - -#### Run the `curl` command - -After applying the configuration to the server and obtaining the access token for the admin account, run the following command on systems that ship curl to discharge rate limiting. - -Before running it, make sure to replace: -- `ADMIN_ACCESS_TOKEN_HERE` with the access token of the admin account -- `example.com` with your base domain -- `@bot.mjolnir:example.com` with the MXID of your Mjolnir - -```sh -curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit -``` - -**Notes**: - -- The command does not work on the 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. - ### 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. @@ -196,6 +147,55 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use - If you change the Pantalaimon's password (`matrix_bot_mjolnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_mjolnir_pantalaimon_password` to let Pantalaimon know its new password. +### Discharge rate limiting for Mjolnir + +If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a required step. If you do not configure it, Mjolnir will crash.** + +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. + +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 +``` + +Then, run the playbook again with the following command to apply the configuration to the server: + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` + +**Notes**: + +- 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). + +#### 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. + +#### Run the `curl` command + +After applying the configuration to the server and obtaining the access token for the admin account, run the following command on systems that ship curl to discharge rate limiting. + +Before running it, make sure to replace: +- `ADMIN_ACCESS_TOKEN_HERE` with the access token of the admin account +- `example.com` with your base domain +- `@bot.mjolnir:example.com` with the MXID of your Mjolnir's bot user + +```sh +curl --header "Authorization: Bearer ADMIN_ACCESS_TOKEN_HERE" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.mjolnir:example.com/override_ratelimit +``` + +**Notes**: + +- The command does not work on the 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. + ## Usage You can refer to the upstream [documentation](https://github.com/matrix-org/mjolnir) for additional ways to use and configure Mjolnir. Check out their [quickstart guide](https://github.com/matrix-org/mjolnir#quickstart-guide) for some basic commands you can give to the bot.