finallycoffee/matrix-docker-ansible-deploy
5
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Draupnir 2.0.0 (#3941)

Browse Source 
* Draupnir 2.0.0

The config getting changes all over the place is because of 2.0 having removed a lot of config options due to the code being removed.

* Update Draupnir Documentation to reflect state as of 2.0.0

* Apply Review Feedback

Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>

* Change Room IDs found in code review to not conform to playbook standard.

Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>

* Further Integrate Code Review Feedback

* Apply remaining suggestions from code review.

Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>

* Apply Configuration Review Feedback

Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>

* Add Self Registration and Native Login to Draupnir

* Rework Draupnir Documentation to Remove Pantalaimon

* Set bot.draupnir as default username for the bot in config

* Draupnir 2.0.1

* Integrate Review Feedback on Structure of Docs

Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>

* Further Restructure Docs and tweak variables in response.

* Only auto-create draupnir user if a password has been set

The Draupnir role supports configuring it with either an access token or with a password.

When a password is not assigned (which means the access token mode is used), the user is to be created manually.

* Add ensure-matrix-users-created tag

Now that the Draupnir user may be auto-created in certain configurations (if a password is assigned), it's useful to have the tag there.

---------

Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
This commit is contained in:
Catalan Lover
2025-01-18 20:25:30 +01:00
committed by GitHub
parent 3e06e4be63
commit f15c0a46be
8 changed files with 203 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/configuring-playbook-appservice-draupnir-for-all.md
View File

@ -24,9 +24,7 @@ The playbook does not create a management room for your Main Draupnir. You **nee
Note that the room must be unencrypted.
<!-- TODO: enable Pantalaimon as configuring-playbook-bot-draupnir.md -->
The management room has to be given an alias and be public when you are setting up the bot for the first time as the bot does not differentiate between invites and invites to the management room.
The management room has to be given an alias, and your bot has to be invited to the room.
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.
@ -36,8 +34,6 @@ As noted in the Draupnir install instructions the control room is sensitive. **A
Next, set an alias to the management room.
This alias can be anything you want. However, for increased security during the setup phase, it is recommended to make this alias be a random string. When it has been locked down after setup phase, you can give your room a secondary human readable alias.
## 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`.
@ -80,13 +76,11 @@ After configuring the playbook, run it with [playbook tags](playbook-tags.md) as
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
**Notes**:
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
`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, you'd need to run `just setup-all`, or these components will still remain installed.
@ -103,7 +97,7 @@ Draupnir for all includes several security measures like that it only allows use
The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297))
To allow users or whole homeservers you type /plain @draupnir-main:example.com allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
To allow users or whole homeservers you type /plain !admin allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to register. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
### How to provision a D4A once you are allowed to

156
docs/configuring-playbook-bot-draupnir.md
View File

@ -2,7 +2,7 @@
The playbook can install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation bot for you.
See the project's [documentation](https://github.com/the-draupnir-project/Draupnir/blob/main/README.md) to learn what it does and why it might be useful to you.
See the project's [documentation](https://the-draupnir-project.github.io/draupnir-documentation/) to learn what it does and why it might be useful to you.
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.
@ -10,33 +10,74 @@ If your migrating from Mjolnir skip to [this section](#migrating-from-mjolnir-on
## Prerequisites
### Register the bot account
### Create a management room
The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
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.
Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
If you make the management room encrypted (E2EE), then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
You can use the playbook to [register a new user](registering-users.md):
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`.
```sh
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
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.
## 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.
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.
**Note**: 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.
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
matrix_bot_draupnir_enable_experimental_rust_crypto: true
# Access Token the bot uses to login.
# Comment out `matrix_bot_draupnir_login_native` when using this option.
matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE"
```
If you would like Draupnir to be able to deactivate users, move aliases, shutdown rooms, show abuse reports (see [below](#abuse-reports)), etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
## Adjusting the playbook configuration
### Obtain an access token
To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`.
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).
```yaml
# Enable Draupnir
matrix_bot_draupnir_enabled: true
⚠️ **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.
# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_draupnir_login: bot.draupnir
# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`.
# If creating the user on your own and using `matrix_bot_draupnir_access_token` to login you can comment out this line.
matrix_bot_draupnir_password: PASSWORD_FOR_THE_BOT
# Comment out if using `matrix_bot_draupnir_enable_experimental_rust_crypto: true` or `matrix_bot_draupnir_access_token` to login.
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.
```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 required step. If you do not configure it, Draupnir will crash.**
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 `inventory/host_vars/matrix.example.com/vars.yml` file:
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
@ -52,92 +93,33 @@ To discharge rate limiting, run the following command on systems that ship curl
curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@bot.draupnir: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 Draupnir itself. If you have made Draupnir an admin, you can just use the Draupnir token.
### Obtain an access token
### Create a management room
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).
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.
If you make the management room encrypted (E2EE), 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`.
Finally invite the `@bot.draupnir:example.com` account you created earlier into the room.
## 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`.
```yaml
# Enable Draupnir
matrix_bot_draupnir_enabled: true
matrix_bot_draupnir_management_room: "MANAGEMENT_ROOM_ID_HERE"
```
### End-to-End Encryption support
Decide whether you want Draupnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms.
To support E2EE, Draupnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
#### Configuration with E2EE support
When using Pantalaimon, Draupnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
Add the following configuration to your `vars.yml` file (adapt to your needs):
```yaml
# Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
matrix_pantalaimon_enabled: true
# Tell Draupnir to use Pantalaimon
matrix_bot_draupnir_pantalaimon_use: true
# User name and password for the bot you have created above. Required when using Pantalaimon.
matrix_bot_draupnir_pantalaimon_username: "bot.draupnir"
matrix_bot_draupnir_pantalaimon_password: "PASSWORD_FOR_THE_BOT"
```
The playbook's `group_vars` will configure other required settings. If using this role separately without the playbook, you also need to configure the two URLs that Draupnir uses to reach the homeserver, one through Pantalaimon and one "raw". This example is taken from the playbook's `group_vars`:
```yaml
# Endpoint URL that Draupnir uses to interact with the Matrix homeserver (client-server API).
# Set this to the pantalaimon URL if you're using that.
matrix_bot_draupnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_draupnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
# Endpoint URL that Draupnir could use to fetch events related to reports (client-server API and /_synapse/),
# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
```
#### Configuration without E2EE support
When NOT using Pantalaimon, Draupnir does not log in by itself and you must give it an access token for its bot account.
Add the following configuration to your `vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token).
```yaml
matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE"
```
⚠️ **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 supports two methods to receive reports in the management room.
Draupnir can receive reports in the management room.
The first method intercepts the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver. If you are using traefik, the playbook can set this up for you:
The bot can intercept the report API endpoint of the client-server API, which requires integration with the reverse proxy in front of the homeserver. If you are using Traefik, this playbook can set this up for you:
```yaml
matrix_bot_draupnir_abuse_reporting_enabled: true
```
The other method polls an Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin (see [above](#register-the-bot-account)). To enable it, set `pollReports: true` on `vars.yml` file as below.
<!--
NOTE: this is unsupported by the playbook due to the admin API being inaccessible from containers currently.
The other method polls an Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin (see [above](#register-the-bot-account)). To enable it, set `pollReports: true` on `vars.yml` file as below.
-->
### Extending the configuration
You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable.
For example, to change Draupnir's `pollReports` option to `true`, add the following configuration to your `vars.yml` file:
For example, to change Draupnir's `acceptInvitesFromSpace` option to `!qporfwt:example.com`, add the following configuration to your `vars.yml` file:
```yaml
matrix_bot_draupnir_configuration_extension_yaml: |
@ -148,13 +130,15 @@ matrix_bot_draupnir_configuration_extension_yaml: |
#
# If you need something more special, you can take full control by
# completely redefining `matrix_bot_draupnir_configuration_yaml`.
pollReports: true
acceptInvitesFromSpace: "!qporfwt:example.com"
```
### Migrating from Mjolnir (Only required if migrating)
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).
That is all you need to do due to that Draupnir can complete migration on its own.
## Installing
@ -174,8 +158,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
`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, you'd need to run `just setup-all`, or these components will still remain installed.
- If you change the Pantalaimon's password (`matrix_bot_draupnir_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_draupnir_pantalaimon_password` to let Pantalaimon know its new password.
## Usage
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.
@ -236,7 +218,7 @@ You can also **turn on various built-in [protections](https://the-draupnir-proje
To **see which protections are available and which are enabled**, send a `!draupnir protections` command to the Management Room.
To **see the configuration options for a given protection**, send a `!draupnir config get PROTECTION_NAME` (e.g. `!draupnir config get JoinWaveShortCircuit`).
To **see the configuration options for a given protection**, send a `!draupnir protections show PROTECTION_NAME` (e.g. `!draupnir protections show JoinWaveShortCircuit`).
To **set a specific option for a given protection**, send a command like this: `!draupnir config set PROTECTION_NAME.OPTION VALUE` (e.g. `!draupnir config set JoinWaveShortCircuit.timescaleMinutes 30`).