Merge af47f323eacb30bf3d65c18e895300a5caf8dfd5 into fea8df5ca2d5db2208370c891b1e0b5919b09324

* Update docs/configuring-playbook-appservice-draupnir-for-all.md: fix sections title

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-appservice-draupnir-for-all.md: merge configuration sections

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-appservice-draupnir-for-all.md: small edits

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-appservice-draupnir-for-all.md: remove a note abour Pantalaimon's unavailability

Pantalaimon can be installed and it has become available for matrix-bot-draupnir and matrix-bot-mjolnir already.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-appservice-draupnir-for-all.md: edit instruction of setting an alias to the management room

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bot-draupnir.md: remove 'c.' from the section title

The section is not related to choosing E2EE support.

Also: replace the instruction to go to the section with the anchor link.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bot-draupnir.md and docs/configuring-playbook-bot-mjolnir.md: create a section for common configs

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update draupnir and mjolnir docs: create "Extending the configuration" sections

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bot-draupnir.md and docs/configuring-playbook-bot-mjolnir.md: create the "End-to-End Encryption support" section

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bot-mjolnir: adjust the section hierarchy

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update draupnir and mjolnir docs: replace numbering

This is a follow-up to e5ab17cafd62feb6e68e3234d434d69cbb383962.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update draupnir and mjolnir docs: create "Prerequisites" section

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update draupnir and mjolnir docs: emphasize necessity of disabling rate limit

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update draupnir and mjolnir docs: instruction for discharging rate limit on Synapse

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update draupnir and mjolnir docs: edit the placeholder for matrix_bot_draupnir_pantalaimon_password and matrix_bot_mjolnir_pantalaimon_password

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update draupnir and mjolnir docs: add an anchor link to "Configuration with E2EE support"

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bot-draupnir.md: move the "Abuse Reports" section above

Also: use "pollReports: true" as an example for extending the configuration.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bot-draupnir.md and docs/configuring-playbook-bot-mjolnir.md: small edits

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-appservice-draupnir-for-all.md: use a common expression

cf. docs/configuring-playbook-alertmanager-receiver.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-appservice-draupnir-for-all.md: integrate the description for installation by Draupnir into our description

Check the original one: 120b37f3ea29101be3baf0856d5d23491db9309e

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-appservice-draupnir-for-all.md: fix a typo

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

---------

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

README.md

@@ -6,7 +6,7 @@
 
 This [Ansible](https://www.ansible.com/) playbook is meant to help you run your own [Matrix](http://matrix.org/) homeserver, along with the [various services](#supported-services) related to that.
 
-That is, it lets you join the Matrix network using your own `@<username>:example.com` identifier, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
+That is, it lets you join the Matrix network using your own user ID like `@alice:example.com`, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
 
 We run all [supported services](#-supported-services) in [Docker](https://www.docker.com/) containers (see [the container images we use](docs/container-images.md)), which lets us have a predictable and up-to-date setup, across multiple supported distros (see [prerequisites](docs/prerequisites.md)) and [architectures](docs/alternative-architectures.md) (x86/amd64 being recommended).
 

docs/configuring-dns.md

@@ -6,9 +6,9 @@ To set up Matrix on your domain, you'd need to do some DNS configuration.
 
 ## DNS setting for server delegation (optional)
 
-In the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user identifier like `@<username>:example.com`.
+In the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user ID like `@alice:example.com` instead of `@alice:matrix.example.com`.
 
-To use such an identifier, you don't need to install anything on the actual `example.com` server. Instead, you need to instruct the Matrix network that Matrix services for `example.com` are redirected over to `matrix.example.com`. This redirection is also known as "delegation".
+To use such an ID, you don't need to install anything on the actual `example.com` server. Instead, you need to instruct the Matrix network that Matrix services for `example.com` are redirected over to `matrix.example.com`. This redirection is also known as "delegation".
 
 As we discuss in [Server Delegation](howto-server-delegation.md), server delegation can be configured in either of these ways:
 

docs/configuring-playbook-alertmanager-receiver.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure the [matrix-alertmanager-receiver](https://github.com/metio/matrix-alertmanager-receiver) service for you. It's a [client](https://prometheus.io/docs/alerting/latest/clients/) for Prometheus' [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/), allowing you to deliver alerts to Matrix rooms.
 
-See the project's [documentation](https://github.com/metio/matrix-alertmanager-receiver) to learn more about what this component does and why it might be useful to you.
+See the project's [documentation](https://github.com/metio/matrix-alertmanager-receiver/blob/main/README.md) to learn what it does and why it might be useful to you.
 
 At the moment, **setting up this service's bot requires some manual actions** as described below in [Account and room preparation](#account-and-room-preparation).
 

docs/configuring-playbook-appservice-draupnir-for-all.md

@@ -16,36 +16,65 @@ Normal Draupnir does come with the benefit of access to Synapse Admin features.
 
 Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
 
-## Installation
+## Prerequisites
 
-### Create a main management room.
+### Create a main management room
 
-The playbook does not create a management room for your Main Draupnir. This task you have to do on your own.
+The playbook does not create a management room for your Main Draupnir. You **need to create the room manually** before setting up the bot.
+
+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.
 
 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. The following is said about the control room in the Draupnir install instructions.
->Anyone in this room can control the bot so it is important that you only invite trusted users to this room. The room must be unencrypted since the playbook does not support installing Pantalaimon yet.
+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.**
 
-### Give your main management room an alias.
+### Set an alias to the management room
 
-Give the room from step 1 an alias. This alias can be anything you want and its recommended for increased security during the setup phase of the bot that you make this alias be a random string. You can give your room a secondary human readable alias when it has been locked down after setup phase.
+Next, set an alias to the management room.
 
-### Adjusting the playbook configuration.
+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.
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+## Adjusting the playbook configuration
 
-You must replace `ALIAS_FROM_STEP_2_GOES_HERE` with the alias you created in step 2.
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ALIAS_HERE`.
 
 ```yaml
 matrix_appservice_draupnir_for_all_enabled: true
 
-matrix_appservice_draupnir_for_all_master_control_room_alias: "ALIAS_FROM_STEP_2_GOES_HERE"
+matrix_appservice_draupnir_for_all_master_control_room_alias: "MANAGEMENT_ROOM_ALIAS_HERE"
 ```
 
-### Installing
+### Extending the configuration
+
+You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable.
+
+For example, to change Draupnir's `protectAllJoinedRooms` option to `true`, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_appservice_draupnir_for_all_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_appservice_draupnir_for_all_yaml`.
+  protectAllJoinedRooms: true
+```
+
+You can refer to the upstream [documentation](https://github.com/the-draupnir-project/Draupnir) for more configuration documentation.
+
+**Notes**:
+
+- The playbook ships a full copy of the example config that does transfer to provisioned Draupnirs in the production-bots.yaml.j2 file in the template directory of the role.
+
+- Config extension does not affect the appservices config as this config is not extensible in current Draupnir anyway. It instead touches the config passed to the Draupnirs that your Appservice creates. So the example above (`protectAllJoinedRooms: true`) makes all provisioned Draupnirs protect all joined rooms.
+
+## Installing
 
 After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
 
@@ -66,7 +95,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com` you have succesfully installed Draupnir for All and can now start using it.
 
-The installation of Draupnir for all in this playbook is very much Alpha quality. Usage-wise, Draupnir for allis almost identical to Draupnir bot mode.
+The installation of Draupnir for all in this playbook is very much Alpha quality. Usage-wise, Draupnir for all is almost identical to Draupnir bot mode.
 
 ### Granting Users the ability to use D4A
 
@@ -76,30 +105,8 @@ The bot requires a powerlevel of 50 in the management room to control who is all
 
 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.
 
-### How to provision a D4A once you are allowed to.
+### How to provision a D4A once you are allowed to
 
-Open a DM with @draupnir-main:example.com and if using an Element client send a message into this DM to finalise creating it. The bot will reject this invite and you will shortly get invited to the Draupnir control room for your newly provisioned Draupnir. From here its just a normal Draupnir experience.
+To provision a D4A, you need to start a chat with `@draupnir-main:example.com`. The bot will reject this invite and you will shortly get invited to the Draupnir control room for your newly provisioned Draupnir. From here its just a normal Draupnir experience.
 
 Congratulations if you made it all the way here because you now have a fully working Draupnir for all deployment.
-
-### Configuration of D4A
-
-You can refer to the upstream [documentation](https://github.com/the-draupnir-project/Draupnir) for more configuration documentation. Please note that the playbook ships a full copy of the example config that does transfer to provisioned Draupnirs in the production-bots.yaml.j2 file in the template directory of the role.
-
-Please note that Config extension does not affect the appservices config as this config is not extensible in current Draupnir anyways. Config extension instead touches the config passed to the Draupnirs that your Appservice creates. So for example below makes all provisioned Draupnirs protect all joined rooms.
-
-You can configure additional options by adding the `matrix_appservice_draupnir_for_all_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.
-
-For example to change Draupnir's `protectAllJoinedRooms` option to `true` you would add the following to your `vars.yml` file.
-
-```yaml
-matrix_appservice_draupnir_for_all_extension_yaml: |
-  # Your custom YAML configuration goes here.
-  # This configuration extends the default starting configuration (`matrix_appservice_draupnir_for_all_yaml`).
-  #
-  # You can override individual variables from the default configuration, or introduce new ones.
-  #
-  # If you need something more special, you can take full control by
-  # completely redefining `matrix_appservice_draupnir_for_all_yaml`.
-  protectAllJoinedRooms: true
-```

docs/configuring-playbook-bot-draupnir.md

@@ -2,17 +2,17 @@
 
 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) to learn what it does and why it might be useful to 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.
 
 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 step 5b.
+If your migrating from Mjolnir skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
 
-## Register the bot account
+## Prerequisites
 
-The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
+### Register the bot account
 
-You **need to register the bot user manually** before setting up the bot.
+The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
 
 Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
 
@@ -22,25 +22,41 @@ You can use the playbook to [register a new user](registering-users.md):
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupnir password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
-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.
+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.
 
-## Get an access token
+### Get an access token
 
-Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+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).
 
-## Make sure the account is free from rate limiting
+### Make sure the account is free from rate limiting
 
-You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Draupnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
+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 Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](configuring-playbook-synapse-admin.md) or running `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands.
+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.
 
-The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@example:example.com/override_ratelimit` Replace `@example:example.com` with the MXID of your Draupnir and example.com with your homeserver domain. You can easily obtain an access token for a homeserver admin account the same way you can obtain an access token for Draupnir itself. If you made Draupnir Admin you can just use the Draupnir token.
+To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file.
 
-## Create a management room
+```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).
+
+**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 discharge 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
+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.
+
+### 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.
 
-If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see below).
+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`.
 
@@ -48,9 +64,22 @@ Finally invite the `@bot.draupnir:example.com` account you created earlier into
 
 ## Adjusting the playbook configuration
 
-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).
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`.
 
-### a. Configuration with E2EE support
+```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.
 
@@ -60,17 +89,12 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
 # Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
 matrix_pantalaimon_enabled: true
 
-# Enable Draupnir
-matrix_bot_draupnir_enabled: true
-
 # Tell Draupnir to use Pantalaimon
 matrix_bot_draupnir_pantalaimon_use: true
 
-# User name and password for the bot. Required when using Pantalaimon.
-matrix_bot_draupnir_pantalaimon_username: "DRAUPNIR_USERNAME_FROM_STEP_1"
-matrix_bot_draupnir_pantalaimon_password: ### you should create a secure password for the bot account
-
-matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+# 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`:
@@ -85,23 +109,47 @@ matrix_bot_draupnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matr
 matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
 ```
 
-### b. Configuration without E2EE support
+#### 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 `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
-
-You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with your own values.
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#get-an-access-token).
 
 ```yaml
-matrix_bot_draupnir_enabled: true
-
-matrix_bot_draupnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
-
-matrix_bot_draupnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE"
 ```
 
-### c. Migrating from Mjolnir (Only required if migrating.)
+### Abuse Reports
+
+Draupnir supports two methods to 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, 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.
+
+### 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 `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_bot_draupnir_configuration_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_bot_draupnir_configuration_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_bot_draupnir_configuration_yaml`.
+  pollReports: true
+```
+
+### 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.
 
@@ -170,7 +218,7 @@ The simplest and most useful entity to target is `user`. Below are a few example
 
 To create rules, you run commands in the Management Room (**not** in the policy list room).
 
-- (ban a single user on a given homeserver): `!draupnir ban @someone:example.com my-bans Rude to others`
+- (ban a single user on a given homeserver): `!draupnir ban @charles:example.com my-bans Rude to others`
 - (ban all users on a given homeserver by using a [wildcard](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-users#wildcards)): `!draupnir ban @*:example.org my-bans Spam server - all users are fake`
 
 As a result of running these commands, you may observe:
@@ -193,38 +241,3 @@ To **set a specific option for a given protection**, send a command like this: `
 To **enable a given protection**, send a command like this: `!draupnir enable PROTECTION_NAME` (e.g. `!draupnir enable JoinWaveShortCircuit`).
 
 To **disable a given protection**, send a command like this: `!draupnir disable PROTECTION_NAME` (e.g. `!draupnir disable JoinWaveShortCircuit`).
-
-## Extending the configuration
-
-You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.
-
-For example to change Draupnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file.
-
-```yaml
-matrix_bot_draupnir_configuration_extension_yaml: |
-  # Your custom YAML configuration goes here.
-  # This configuration extends the default starting configuration (`matrix_bot_draupnir_configuration_yaml`).
-  #
-  # You can override individual variables from the default configuration, or introduce new ones.
-  #
-  # If you need something more special, you can take full control by
-  # completely redefining `matrix_bot_draupnir_configuration_yaml`.
-  recordIgnoredInvites: true
-```
-
-## Abuse Reports
-
-Draupnir supports two methods to 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, 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 and is hence only available when using synapse and when the Draupnir user is an admin user (see step 1). To enable it, set `pollReports: true` in Draupnir's config:
-
-```yaml
-matrix_bot_draupnir_configuration_extension_yaml: |
-  pollReports: true
-```

docs/configuring-playbook-bot-go-neb.md

@@ -6,9 +6,9 @@ The playbook can install and configure [Go-NEB](https://github.com/matrix-org/go
 
 Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.
 
-See the project's [documentation](https://github.com/matrix-org/go-neb) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/go-neb/blob/master/README.md) to learn what it does and why it might be useful to you.
 
-## Registering the bot user
+## Registering the bot account
 
 The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver.
 
@@ -62,7 +62,7 @@ matrix_bot_go_neb_realms:
 matrix_bot_go_neb_sessions:
   - SessionID: "your_github_session"
     RealmID: "github_realm"
-    UserID: "@YOUR_USER_ID:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
+    UserID: "@alice:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
     Config:
       # Populate these fields by generating a "Personal Access Token" on github.com
       AccessToken: "YOUR_GITHUB_ACCESS_TOKEN"
@@ -149,7 +149,7 @@ matrix_bot_go_neb_services:
     UserID: "@another_goneb:{{ matrix_domain }}"
     Config:
       RealmID: "github_realm"
-      ClientUserID: "@YOUR_USER_ID:{{ matrix_domain }}" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
+      ClientUserID: "@alice:{{ matrix_domain }}" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
       Rooms:
         "!qporfwt:example.com":
           Repos:
@@ -234,7 +234,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-To use the bot, invite it to any existing Matrix room (`/invite @whatever_you_chose:example.com` where `example.com` is your base domain, not the `matrix.` domain, make sure you have permission from the room owner if that's not you).
+To use the bot, invite it to any existing Matrix room (`/invite @bot.go-neb:example.com` where `example.com` is your base domain, not the `matrix.` domain). Make sure you are granted with the sufficient permission if you are not the room owner.
 
 Basic usage is like this: `!echo hi` or `!imgur puppies` or `!giphy matrix`
 

docs/configuring-playbook-bot-honoroit.md

@@ -4,7 +4,7 @@ The playbook can install and configure [Honoroit](https://github.com/etkecc/hono
 
 It's a bot you can use to setup **your own helpdesk on matrix**
 
-See the project's [documentation](https://github.com/etkecc/honoroit#how-it-looks-like) to learn what it does with screenshots and why it might be useful to you.
+See the project's [documentation](https://github.com/etkecc/honoroit/blob/main/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-bot-matrix-registration-bot.md

@@ -4,7 +4,7 @@ The playbook can install and configure [matrix-registration-bot](https://github.
 
 The bot allows you to easily **create and manage registration tokens** aka. invitation codes. It can be used for an invitation-based server, where you invite someone by sending them a registration token (tokens look like this: `rbalQ0zkaDSRQCOp`). They can register as per normal but have to provide a valid registration token in the final step of the registration process.
 
-See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/moan0s/matrix-registration-bot/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Configuration
 

docs/configuring-playbook-bot-matrix-reminder-bot.md

@@ -4,7 +4,7 @@ The playbook can install and configure [matrix-reminder-bot](https://github.com/
 
 It's a bot you can use to **schedule one-off & recurring reminders and alarms**.
 
-See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-bot-mjolnir.md

@@ -2,13 +2,13 @@
 
 The playbook can install and configure the [Mjolnir](https://github.com/matrix-org/mjolnir) moderation bot for you.
 
-See the project's [documentation](https://github.com/matrix-org/mjolnir) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/mjolnir/blob/main/README.md) to learn what it does and why it might be useful to you.
 
-## Register the bot account
+## Prerequisites
 
-The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
+### Register the bot account
 
-You **need to register the bot user manually** before setting up the bot.
+The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
 
 Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
 
@@ -20,23 +20,39 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.mjolnir
 
 If you would like Mjolnir to be able to deactivate users, move aliases, shutdown rooms, etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
 
-## Get an access token
+### Get an access token
 
-Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
+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).
 
-## Make sure the account is free from rate limiting
+### Make sure the account is free from rate limiting
 
-You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
+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.**
 
-If your Synapse Admin API is exposed to the internet for some reason like running the Synapse Admin Role [Link](configuring-playbook-synapse-admin.md) or running `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true` in your playbook config. If your API is not externally exposed you should still be able to on the local host for your synapse run these commands.
+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.
 
-The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@example:example.com/override_ratelimit` Replace `@example:example.com` with the MXID of your Mjolnir and example.com with your homeserver domain. You can easily obtain an access token for a homeserver admin account the same way you can obtain an access token for Mjolnir itself. If you made Mjolnir Admin you can just use the Mjolnir token.
+To expose the APIs publicly, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file.
 
-## Create a management room
+```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).
+
+**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 discharge 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
+curl --header "Authorization: Bearer <access_token>" -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. 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).
+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`.
 
@@ -44,9 +60,22 @@ Finally invite the `@bot.mjolnir:example.com` account you created earlier into t
 
 ## Adjusting the playbook configuration
 
-Decide whether you want Mjolnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Mjolnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`.
 
-### a. Configuration with E2EE support
+```yaml
+# Enable Mjolnir
+matrix_bot_mjolnir_enabled: true
+
+matrix_bot_mjolnir_management_room: "MANAGEMENT_ROOM_ID_HERE"
+```
+
+### End-to-End Encryption support
+
+Decide whether you want Mjolnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms.
+
+To support E2EE, Mjolnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
+
+#### Configuration with E2EE support
 
 When using Pantalaimon, Mjolnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
 
@@ -56,17 +85,12 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
 # Enable Pantalaimon. See docs/configuring-playbook-pantalaimon.md
 matrix_pantalaimon_enabled: true
 
-# Enable Mjolnir
-matrix_bot_mjolnir_enabled: true
-
 # Tell Mjolnir to use Pantalaimon
 matrix_bot_mjolnir_pantalaimon_use: true
 
-# User name and password for the bot. Required when using Pantalaimon.
-matrix_bot_mjolnir_pantalaimon_username: "MJOLNIR_USERNAME_FROM_STEP_1"
-matrix_bot_mjolnir_pantalaimon_password: ### you should create a secure password for the bot account
-
-matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+# User name and password for the bot you have created above. Required when using Pantalaimon.
+matrix_bot_mjolnir_pantalaimon_username: "bot.mjolnir"
+matrix_bot_mjolnir_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 Mjolnir uses to reach the homeserver, one through Pantalaimon and one "raw". This example is taken from the playbook's `group_vars`:
@@ -81,25 +105,19 @@ matrix_bot_mjolnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matri
 matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
 ```
 
-### b. Configuration without E2EE support
+#### Configuration without E2EE support
 
 When NOT using Pantalaimon, Mjolnir does not log in by itself and you must give it an access token for its bot account.
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
-
-You must replace `ACCESS_TOKEN_FROM_STEP_2_GOES_HERE` and `ROOM_ID_FROM_STEP_4_GOES_HERE` with your own values.
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#get-an-access-token).
 
 ```yaml
-matrix_bot_mjolnir_enabled: true
-
-matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_FROM_STEP_2_GOES_HERE"
-
-matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
+matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_HERE"
 ```
 
-## Adding Mjolnir synapse antispam module (optional)
+### Adding Mjolnir synapse antispam module (optional)
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
+To enable Mjolnir synapse antispam module, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled: true
@@ -109,6 +127,24 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_usernames: false
 matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
 ```
 
+### Extending the configuration
+
+You can configure additional options by adding the `matrix_bot_mjolnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.
+
+For example, to change Mjolnir's `recordIgnoredInvites` option to `true`, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_bot_mjolnir_configuration_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_bot_mjolnir_configuration_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_bot_mjolnir_configuration_yaml`.
+  recordIgnoredInvites: true
+```
+
 ## Installing
 
 After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
@@ -131,19 +167,3 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 ## 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.
-
-You can configure additional options by adding the `matrix_bot_mjolnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.
-
-For example to change Mjolnir's `recordIgnoredInvites` option to `true` you would add the following to your `vars.yml` file.
-
-```yaml
-matrix_bot_mjolnir_configuration_extension_yaml: |
-  # Your custom YAML configuration goes here.
-  # This configuration extends the default starting configuration (`matrix_bot_mjolnir_configuration_yaml`).
-  #
-  # You can override individual variables from the default configuration, or introduce new ones.
-  #
-  # If you need something more special, you can take full control by
-  # completely redefining `matrix_bot_mjolnir_configuration_yaml`.
-  recordIgnoredInvites: true
-```

docs/configuring-playbook-bridge-appservice-discord.md

@@ -97,5 +97,5 @@ There's the Discord bridge's guide for [setting privileges on bridge managed roo
 
 ```sh
 docker exec -it matrix-appservice-discord \
-/bin/sh -c 'cp /cfg/registration.yaml /tmp/discord-registration.yaml && cd /tmp && node /build/tools/adminme.js -c /cfg/config.yaml -m "!qporfwt:example.com" -u "@USER:example.com" -p 100'
+/bin/sh -c 'cp /cfg/registration.yaml /tmp/discord-registration.yaml && cd /tmp && node /build/tools/adminme.js -c /cfg/config.yaml -m "!qporfwt:example.com" -u "@alice:example.com" -p 100'
 ```

docs/configuring-playbook-bridge-appservice-irc.md

@@ -79,4 +79,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-You then need to start a chat with `@irc_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@irc_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).

docs/configuring-playbook-bridge-appservice-kakaotalk.md

@@ -4,7 +4,7 @@ The playbook can install and configure [matrix-appservice-kakaotalk](https://src
 
 ⚠️ **Warning**: there have been recent reports (~2022-09-16) that **using this bridge may get your account banned**.
 
-See the project's [documentation](https://src.miscworks.net/fair/matrix-appservice-kakaotalk) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://src.miscworks.net/fair/matrix-appservice-kakaotalk/src/branch/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Prerequisite (optional)
 
@@ -50,7 +50,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
 

docs/configuring-playbook-bridge-appservice-slack.md

@@ -82,7 +82,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Send `/invite @slackbot:example.com` to invite the bridge bot user into the admin room.
+To use the bridge, you need to send `/invite @slackbot:example.com` to invite the bridge bot user into the admin room.
 
 If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
 

docs/configuring-playbook-bridge-appservice-webhooks.md

@@ -43,7 +43,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Invite the bridge bot user to your room in either way.
+To use the bridge, you need to invite the bridge bot user to your room in either way.
 
 - Send `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
 - Add the bridge bot to a private channel (personal channels imply you being an administrator)

docs/configuring-playbook-bridge-beeper-linkedin.md

@@ -27,7 +27,7 @@ If you would like to be able to administrate the bridge from your account it can
 matrix_beeper_linkedin_configuration_extension_yaml: |
   bridge:
     permissions:
-      '@YOUR_USERNAME:example.com': admin
+      '@alice:{{ matrix_domain }}': admin
 ```
 
 You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
@@ -59,7 +59,7 @@ Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playb
 
 ## Usage
 
-You then need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account.
 

docs/configuring-playbook-bridge-go-skype-bridge.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/kelaresg/go-skype-bridge/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 
@@ -31,6 +31,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Once the bot is enabled, you need to start a chat with `Skype bridge bot` with the handle `@skypebridgebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Skype bridge bot` with the handle `@skypebridgebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `help` to the bot to see the commands available.

docs/configuring-playbook-bridge-heisenbridge.md

@@ -4,7 +4,7 @@
 
 The playbook can install and configure [Heisenbridge](https://github.com/hifi/heisenbridge) - the bouncer-style [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) bridge for you.
 
-See the project's [README](https://github.com/hifi/heisenbridge/blob/master/README.md) to learn what it does and why it might be useful to you. You can also take a look at [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I).
+See the project's [documentation](https://github.com/hifi/heisenbridge/blob/master/README.md) to learn what it does and why it might be useful to you. You can also take a look at [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I).
 
 ## Configuration
 
@@ -15,7 +15,7 @@ matrix_heisenbridge_enabled: true
 
 # Setting the owner is optional as the first local user to DM `@heisenbridge:example.com` will be made the owner.
 # If you are not using a local user you must set it as otherwise you can't DM it at all.
-matrix_heisenbridge_owner: "@you:example.com"
+matrix_heisenbridge_owner: "@alice:{{ matrix_domain }}"
 
 # Uncomment to enable identd on host port 113/TCP (optional)
 # matrix_heisenbridge_identd_enabled: true
@@ -66,7 +66,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-After the bridge is successfully running just DM `@heisenbridge:example.com` to start setting it up. If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.
+To use the bridge, you need to start a chat with `@heisenbridge:example.com` (where `example.com` is your base domain, not the `matrix.` domain). If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.
 
 Help is available for all commands with the `-h` switch.
 

docs/configuring-playbook-bridge-hookshot.md

@@ -4,7 +4,7 @@ The playbook can install and configure [matrix-hookshot](https://github.com/matr
 
 Hookshot can bridge [Webhooks](https://en.wikipedia.org/wiki/Webhook) from software project management services such as GitHub, GitLab, JIRA, and Figma, as well as generic webhooks.
 
-See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html) to learn what it does in detail and why it might be useful to you.
+See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html) to learn what it does and why it might be useful to you.
 
 **Note**: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however was deprecated by its author.
 
@@ -30,7 +30,7 @@ Should the crypto store be corrupted, you can reset it by executing this Ansible
 
 ## Usage
 
-Create a room and invite the Hookshot bot (`@hookshot:example.com`) to it.
+To use the bridge, you need to create a room and invite the Hookshot bot (`@hookshot:example.com`) to it.
 
 Make sure the bot is able to send state events (usually the Moderator power level in clients).
 

docs/configuring-playbook-bridge-matrix-bridge-sms.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 **The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.**
 

docs/configuring-playbook-bridge-mautrix-facebook.md

@@ -38,7 +38,7 @@ If you would like to be able to administrate the bridge from your account it can
 matrix_mautrix_facebook_configuration_extension_yaml: |
   bridge:
     permissions:
-      '@YOUR_USERNAME:{{ matrix_domain }}': admin
+      '@alice:{{ matrix_domain }}': admin
 ```
 
 Using both would look like
@@ -47,7 +47,7 @@ Using both would look like
 matrix_mautrix_facebook_configuration_extension_yaml: |
   bridge:
     permissions:
-      '@YOUR_USERNAME:{{ matrix_domain }}': admin
+      '@alice:{{ matrix_domain }}': admin
     encryption:
       allow: true
       default: true
@@ -74,7 +74,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-You then need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/facebook/authentication.html).
 

docs/configuring-playbook-bridge-mautrix-gmessages.md

@@ -37,7 +37,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-You then need to start a chat with `@gmessagesbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@gmessagesbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 ### 💡 Set up Double Puppeting
 

docs/configuring-playbook-bridge-mautrix-googlechat.md

@@ -37,7 +37,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Once the bot is enabled you need to start a chat with `googlechat bridge bot` with handle `@googlechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `googlechat bridge bot` with handle `@googlechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions.
 

docs/configuring-playbook-bridge-mautrix-hangouts.md

@@ -39,7 +39,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Once the bot is enabled you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions.
 

docs/configuring-playbook-bridge-mautrix-instagram.md

@@ -30,14 +30,14 @@ If you would like to be able to administrate the bridge from your account it can
 
 ```yaml
 # The easy way. The specified Matrix user ID will be made an admin of all bridges
-matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
+matrix_admin: "@alice:{{ matrix_domain }}"
 
 # OR:
 # The more verbose way. Applies to this bridge only. You may define multiple Matrix users as admins.
 matrix_mautrix_instagram_configuration_extension_yaml: |
   bridge:
     permissions:
-      '@YOUR_USERNAME:example.com': admin
+      '@alice:{{ matrix_domain }}': admin
 ```
 
 You may wish to look at `roles/custom/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure.
@@ -61,7 +61,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-You then need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account.
 

docs/configuring-playbook-bridge-mautrix-meta-instagram.md

@@ -56,13 +56,13 @@ matrix_mautrix_meta_instagram_bridge_permissions_default:
   '{{ matrix_admin }}': admin
 ```
 
-If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:example.com`), then there's no admin by default.
+If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default.
 
 You may redefine `matrix_mautrix_meta_instagram_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_instagram_bridge_permissions_custom` like this:
 
 ```yaml
 matrix_mautrix_meta_instagram_bridge_permissions_custom:
-  '@YOUR_USERNAME:example.com': admin
+  '@alice:{{ matrix_domain }}': admin
 ```
 
 You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
@@ -86,7 +86,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-You then need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 ### 💡 Set up Double Puppeting
 

docs/configuring-playbook-bridge-mautrix-meta-messenger.md

@@ -69,13 +69,13 @@ matrix_mautrix_meta_messenger_bridge_permissions_default:
   '{{ matrix_admin }}': admin
 ```
 
-If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @user:example.com`), then there's no admin by default.
+If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default.
 
 You may redefine `matrix_mautrix_meta_messenger_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_messenger_bridge_permissions_custom` like this:
 
 ```yaml
 matrix_mautrix_meta_messenger_bridge_permissions_custom:
-  '@YOUR_USERNAME:example.com': admin
+  '@alice:{{ matrix_domain }}': admin
 ```
 
 You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
@@ -99,7 +99,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-You then need to start a chat with `@messengerbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). Note that the user ID of the bridge's bot is not `@facebookbot:example.com`.
+To use the bridge, you need to start a chat with `@messengerbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). Note that the user ID of the bridge's bot is not `@facebookbot:example.com`.
 
 You then need to send a `login` command and follow the bridge bot's instructions.
 

docs/configuring-playbook-bridge-mautrix-signal.md

@@ -54,7 +54,7 @@ If you want to augment the preset permissions, you might want to set the additio
 matrix_mautrix_signal_configuration_extension_yaml: |
   bridge:
     permissions:
-      '@YOUR_USERNAME:example.com': admin
+      '@alice:{{ matrix_domain }}': admin
 ```
 
 This will add the admin permission to the specific user, while keeping the default permissions.
@@ -63,8 +63,8 @@ In case you want to replace the default permissions settings **completely**, pop
 
 ```yaml
 matrix_mautrix_signal_bridge_permissions:
-  '@ADMIN:example.com': admin
-  '@USER:example.com' : user
+  '@alice:{{ matrix_domain }}': admin
+  '@bob:{{ matrix_domain }}' : user
 ```
 
 You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure.
@@ -88,7 +88,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-You then need to start a chat with `@signalbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@signalbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 ### 💡 Set up Double Puppeting
 

docs/configuring-playbook-bridge-mautrix-telegram.md

@@ -39,7 +39,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-You then need to start a chat with `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
@@ -57,7 +57,7 @@ You might also want to give permissions to administrate the bot:
 matrix_mautrix_telegram_configuration_extension_yaml: |
   bridge:
     permissions:
-      '@user:example.com': admin
+      '@alice:{{ matrix_domain }}': admin
 ```
 
 More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410

docs/configuring-playbook-bridge-mautrix-twitter.md

@@ -4,11 +4,13 @@
 
 The playbook can install and configure [mautrix-twitter](https://github.com/mautrix/twitter) for you.
 
-See the project's [documentation](https://github.com/mautrix/twitter) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/mautrix/twitter/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Prerequisite (optional)
 
-If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+### Enable Appservice Double Puppet (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
 
 For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
 
@@ -50,14 +52,18 @@ After successfully enabling bridging, you may wish to set up [Double Puppeting](
 
 To set it up, you have 2 ways of going about it.
 
-#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth
+#### Method 1: automatically, by enabling Appservice Double Puppet
 
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
+The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook.
 
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
+This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
 
 #### Method 2: manually, by asking each user to provide a working access token
 
-This method is currently not available for the Mautrix-Twitter bridge, but is on the [roadmap](https://github.com/mautrix/twitter/blob/master/ROADMAP.md) under Misc/Manual login with `login-matrix`
+When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
+
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
+
+- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
+
+- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature

docs/configuring-playbook-bridge-mautrix-whatsapp.md

@@ -53,7 +53,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-You then need to start a chat with `@whatsappbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@whatsappbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 ### 💡 Set up Double Puppeting
 

docs/configuring-playbook-bridge-mautrix-wsproxy.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure [mautrix-wsproxy](https://github.com/mautrix/wsproxy) for you.
 
-See the project's [documentation](https://github.com/mautrix/wsproxy#readme) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/mautrix/wsproxy/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-bridge-mx-puppet-discord.md

@@ -6,7 +6,7 @@
 
 The playbook can install and configure [mx-puppet-discord](https://gitlab.com/mx-puppet/discord/mx-puppet-discord) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://gitlab.com/mx-puppet/discord/mx-puppet-discord/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 
@@ -35,7 +35,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Once the bot is enabled you need to start a chat with `Discord Puppet Bridge` with the handle `@_discordpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Discord Puppet Bridge` with the handle `@_discordpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-discord [documentation](https://gitlab.com/mx-puppet/discord/mx-puppet-discord) for more information about how to configure the bridge.
 

docs/configuring-playbook-bridge-mx-puppet-groupme.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 
@@ -31,7 +31,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Once the bot is enabled you need to start a chat with `GroupMe Puppet Bridge` with the handle `@_groupmepuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `GroupMe Puppet Bridge` with the handle `@_groupmepuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 One authentication method is available.
 

docs/configuring-playbook-bridge-mx-puppet-instagram.md

@@ -31,7 +31,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Once the bot is enabled, you need to start a chat with `Instagram Puppet Bridge` with the handle `@_instagrampuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Instagram Puppet Bridge` with the handle `@_instagrampuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `link <username> <password>` to the bridge bot to link your instagram account.
 

docs/configuring-playbook-bridge-mx-puppet-slack.md

@@ -4,7 +4,7 @@
 
 The playbook can install and configure [mx-puppet-slack](https://gitlab.com/mx-puppet/slack/mx-puppet-slack) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://gitlab.com/mx-puppet/slack/mx-puppet-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Prerequisite
 
@@ -40,7 +40,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Once the bot is enabled you need to start a chat with `Slack Puppet Bridge` with the handle `@_slackpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Slack Puppet Bridge` with the handle `@_slackpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-slack [documentation](https://gitlab.com/mx-puppet/slack/mx-puppet-slack) for more information about how to configure the bridge.
 

docs/configuring-playbook-bridge-mx-puppet-steam.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/icewind1991/mx-puppet-steam/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 
@@ -31,7 +31,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Once the bot is enabled you need to start a chat with `Steam Puppet Bridge` with the handle `@_steampuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Steam Puppet Bridge` with the handle `@_steampuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Three authentication methods are available, Legacy Token, OAuth and xoxc token. See mx-puppet-steam [documentation](https://github.com/icewind1991/mx-puppet-steam) for more information about how to configure the bridge.
 

docs/configuring-playbook-bridge-mx-puppet-twitter.md

@@ -4,7 +4,7 @@
 
 The playbook can install and configure [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) for you.
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/Sorunome/mx-puppet-twitter/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Prerequisite
 
@@ -42,7 +42,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ## Usage
 
-Once the bot is enabled you need to start a chat with `Twitter Puppet Bridge` with the handle `@_twitterpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `Twitter Puppet Bridge` with the handle `@_twitterpuppet_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 To log in, use `link` and click the link.
 

docs/configuring-playbook-bridge-postmoogle.md

@@ -6,7 +6,7 @@ The playbook can install and configure [Postmoogle](https://github.com/etkecc/po
 
 Postmoogle is a bridge you can use to have its bot user forward emails to Matrix rooms. It runs an SMTP email server and allows you to assign mailbox addresses to the rooms.
 
-See the project's [documentation](https://github.com/etkecc/postmoogle) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/etkecc/postmoogle/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Prerequisites
 

docs/configuring-playbook-bridge-wechat.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure the [matrix-wechat](https://github.com/duo/matrix-wechat) bridge for you (for bridging to the [WeChat](https://www.wechat.com/) network).
 
-See the project page to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/duo/matrix-wechat/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-email2matrix.md

@@ -24,11 +24,13 @@ For details about using Email2Matrix alongside [Postfix](http://www.postfix.org/
 
 ### Creating a user
 
-Before enabling Email2Matrix, you'd most likely wish to create a dedicated user (or more) that would be sending messages on the Matrix side. Refer to [Registering users](registering-users.md) for ways to do that. A regular (non-admin) user works best.
+Before enabling Email2Matrix, you'd most likely wish to create a dedicated user (or more) that would be sending messages on the Matrix side. Take note of the user's ID as it needs to be specified as `MatrixUserId` on your `inventory/host_vars/matrix.example.com/vars.yml` file later.
+
+Refer to [Registering users](registering-users.md) for ways to create a user. A regular (non-admin) user works best.
 
 ### Creating a shared room
 
-After creating a sender user, you should create one or more Matrix rooms that you share with that user. It doesn't matter who creates and owns the rooms and who joins later (you or the sender user).
+After creating the sender user, you should create one or more Matrix rooms that you share with that user. It doesn't matter who creates and owns the rooms and who joins later (you or the sender user).
 
 What matters is that both you and the sender user are part of the same room and that the sender user has enough privileges in the room to be able to send messages there.
 
@@ -51,7 +53,7 @@ matrix_email2matrix_matrix_mappings:
   - MailboxName: "mailbox1"
     MatrixRoomId: "!qporfwt:{{ matrix_domain }}"
     MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
-    MatrixUserId: "@email2matrix:{{ matrix_domain }}"
+    MatrixUserId: "@email2matrix1:{{ matrix_domain }}"
     MatrixAccessToken: "MATRIX_ACCESS_TOKEN_HERE"
     IgnoreSubject: false
     IgnoreBody: false
@@ -60,7 +62,7 @@ matrix_email2matrix_matrix_mappings:
   - MailboxName: "mailbox2"
     MatrixRoomId: "!aaabaa:{{ matrix_domain }}"
     MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
-    MatrixUserId: "@email2matrix:{{ matrix_domain }}"
+    MatrixUserId: "@email2matrix2:{{ matrix_domain }}"
     MatrixAccessToken: "MATRIX_ACCESS_TOKEN_HERE"
     IgnoreSubject: true
     IgnoreBody: false
@@ -72,7 +74,7 @@ where:
 * MailboxName - local-part of the email address, through which emails are bridged to the room whose ID is defined with MatrixRoomId
 * MatrixRoomId - internal ID of the room, to which received emails are sent as Matrix message
 * MatrixHomeserverUrl - URL of your Matrix homeserver, through which to send Matrix messages. You can also set `MatrixHomeserverUrl` to the container URL where your homeserver's Client-Server API lives by using the `{{ matrix_addons_homeserver_client_api_url }}` variable
-* MatrixUserId - the full ID of the sender user which sends bridged messages to the room
+* MatrixUserId - the full ID of the sender user which sends bridged messages to the room. On this configuration it is `@email2matrix1:example.com` and `@email2matrix2:example.com` (where `example.com` is your base domain, not the `matrix.` domain)
 * MatrixAccessToken - sender user's access token
 * IgnoreSubject - if set to "true", the subject is not bridged to Matrix
 * IgnoreBody - if set to "true", the message body is not bridged to Matrix

docs/configuring-playbook-federation.md

@@ -2,7 +2,7 @@
 
 By default, your server federates with the whole Matrix network. That is, people on your server can communicate with people on any other Matrix server.
 
-**Note**: in the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user identifier like `@<username>:example.com` and set up [server delegation](howto-server-delegation.md) / redirection. Without a proper configuration, your server will effectively not be part of the Matrix network. If you find your server is not federated, make sure to [check whether services work](maintenance-checking-services.md) and your server is properly delegated.
+**Note**: in the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user ID like `@alice:example.com` instead of `@alice:matrix.example.com` and set up [server delegation](howto-server-delegation.md) / redirection. Without a proper configuration, your server will effectively not be part of the Matrix network. If you find your server is not federated, make sure to [check whether services work](maintenance-checking-services.md) and your server is properly delegated.
 
 ## Federating only with select servers
 

docs/configuring-playbook-ldap-auth.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider for you.
 
-See that project's documentation to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/matrix-synapse-ldap3/blob/main/README.rst) to learn what it does and why it might be useful to you.
 
 If you decide that you'd like to let this playbook install it for you, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
 

docs/configuring-playbook-ma1sd.md

@@ -6,7 +6,7 @@ The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity
 
 ma1sd is used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some [enhanced features](https://github.com/ma1uta/ma1sd/#features). It is private by default, potentially at the expense of user discoverability.
 
-See the project's [documentation](https://github.com/ma1uta/ma1sd) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/ma1uta/ma1sd/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 **Note**: enabling ma1sd, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
 

docs/configuring-playbook-matrix-authentication-service.md

@@ -353,7 +353,7 @@ If you have existing OIDC users in your Synapse user database (which will be the
 
 If you don't do this, `syn2mas` would report errors like this one:
 
-> [FATAL] migrate - [Failed to import external id 4264b0f0-4f11-4ddd-aedb-b500e4d07c25 with oidc-keycloak for user @user:example.com: Error: Unknown upstream provider oidc-keycloak]
+> [FATAL] migrate - [Failed to import external id 4264b0f0-4f11-4ddd-aedb-b500e4d07c25 with oidc-keycloak for user @alice:example.com: Error: Unknown upstream provider oidc-keycloak]
 
 Below is an example situation and a guide for how to solve it.
 

docs/configuring-playbook-matrix-corporal.md

@@ -8,7 +8,9 @@
 
 The playbook can install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you.
 
-In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment. See that project's documentation to learn what it does and why it might be useful to you.
+In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment.
+
+See the project's [documentation](https://github.com/devture/matrix-corporal/blob/main/README.md) to learn what it does and why it might be useful to you.
 
 If you decide that you'd like to let this playbook install it for you, you'd need to also:
 - (required) [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md)

docs/configuring-playbook-matrix-media-repo.md

@@ -47,7 +47,7 @@ matrix_media_repo_database_max_idle_connections: 5
 # See docs/admin.md for information on what these people can do. They must belong to one of the
 # configured homeservers above.
 # matrix_media_repo_admins: [
-#   "@your_username:example.org"
+#   "@alice:example.org"
 # ]
 
 matrix_media_repo_admins: []

docs/configuring-playbook-mautrix-bridges.md

@@ -18,7 +18,7 @@ There are some additional things you may wish to configure about the bridge befo
 To **configure a user as an administrator for all bridges**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
 ```yaml
-matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
+matrix_admin: "@alice:{{ matrix_domain }}"
 ```
 
 **Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with:
@@ -27,7 +27,7 @@ matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
 matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
   bridge:
     permissions:
-      '@YOUR_USERNAME:{{ matrix_domain }}': admin
+      '@alice:{{ matrix_domain }}': admin
 ```
 
 ## encryption
@@ -73,7 +73,7 @@ You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml`
 matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
   bridge:
     permissions:
-      '@YOUR_USERNAME:{{ matrix_domain }}': admin
+      '@alice:{{ matrix_domain }}': admin
     encryption:
       allow: true
       default: true
@@ -132,7 +132,7 @@ If you have issues with a service, and are requesting support, the higher levels
 
 ## Usage
 
-You then need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
+To use the bridge, you need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
 Send `login` to the bridge bot to get started. You can learn more here about authentication from the bridge's official documentation on Authentication: https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html
 

docs/configuring-playbook-pantalaimon.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure the [pantalaimon](https://github.com/matrix-org/pantalaimon) E2EE aware proxy daemon for you.
 
-See the project's [documentation](https://github.com/matrix-org/pantalaimon) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/pantalaimon/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 This role exposes Pantalaimon's API only within the container network, so bots and clients installed on the same machine can use it. In particular the [Draupnir](configuring-playbook-bot-draupnir.md) and [Mjolnir](configuring-playbook-bot-mjolnir.md) roles (and possibly others) can use it.
 

docs/configuring-playbook-rest-auth.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) for you.
 
-See that project's documentation to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/ma1uta/matrix-synapse-rest-password-provider/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-shared-secret-auth.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) for you.
 
-See that project's documentation to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/devture/matrix-synapse-shared-secret-auth/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-sygnal.md

@@ -2,7 +2,7 @@
 
 The playbook can install and configure the [Sygnal](https://github.com/matrix-org/sygnal) push gateway for you.
 
-See the project's [documentation](https://github.com/matrix-org/sygnal) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/sygnal/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 **Note**: most people don't need to install their own gateway. As Sygnal's [Notes for application developers](https://github.com/matrix-org/sygnal/blob/master/docs/applications.md) documentation says:
 

docs/configuring-playbook-synapse-auto-accept-invite.md

@@ -2,7 +2,9 @@
 
 The playbook can install and configure [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) for you.
 
-See that project's [documentation](https://github.com/matrix-org/synapse-auto-accept-invite) to learn what it does and why it might be useful to you. In short, it automatically accepts room invites. You can specify that only 1:1 room invites are auto-accepted. Defaults to false if not specified.
+In short, it automatically accepts room invites. You can specify that only 1:1 room invites are auto-accepted. Defaults to false if not specified.
+
+See the project's [documentation](https://github.com/matrix-org/synapse-auto-accept-invite/blob/main/README.md) to learn what it does and why it might be useful to you.
 
 **Note**: Synapse [v1.109.0](https://github.com/element-hq/synapse/releases/tag/v1.109.0), the same feature [has been merged](https://github.com/element-hq/synapse/pull/17147) into Synapse (see the [Native alternative](#native-alternative) section below). You'd better use the native feature, instead of the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) 3rd party module.
 

docs/configuring-playbook-synapse-auto-compressor.md

@@ -4,7 +4,7 @@ The playbook can install and configure [synapse_auto_compressor](https://github.
 
 It's a CLI tool that automatically compresses Synapse's `state_groups` database table in the background.
 
-See the project's [documentation](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://github.com/matrix-org/rust-synapse-compress-state/blob/master/README.md#automated-tool-synapse_auto_compressor) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-synapse-simple-antispam.md

@@ -2,7 +2,9 @@
 
 The playbook can install and configure [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) for you.
 
-See that project's documentation to learn what it does and why it might be useful to you. In short, it lets you fight invite-spam by automatically blocking invitiations from a list of servers specified by you (blacklisting).
+It lets you fight invite-spam by automatically blocking invitiations from a list of servers specified by you (blacklisting).
+
+See the project's [documentation](https://github.com/t2bot/synapse-simple-antispam/blob/master/README.md) to learn what it does and why it might be useful to you.
 
 ## Adjusting the playbook configuration
 

docs/configuring-well-known.md

@@ -16,7 +16,7 @@ There are 3 types of well-known service discovery mechanism that Matrix makes us
 
 All services created by this playbook are meant to be installed on their own server (such as `matrix.example.com`), instead of the base domain (`example.com`).
 
-As [per the Server-Server specification](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), to use a short Matrix user identifier like `@user:example.com` while hosting services on a subdomain such as `matrix.example.com`, the Matrix network needs to be instructed of [server delegation](howto-server-delegation.md) / redirection.
+As [per the Server-Server specification](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), in order to use a short Matrix user ID like `@alice:example.com` instead of `@alice:matrix.example.com` while hosting services on a subdomain such as `matrix.example.com`, the Matrix network needs to be instructed of [server delegation](howto-server-delegation.md) / redirection.
 
 For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file.
 
@@ -24,7 +24,7 @@ If you set up the DNS SRV record for server delegation instead, take a look at t
 
 ### Client Server Discovery
 
-Client Server Service discovery lets various client programs which support it, to receive a full user ID (e.g. `@username:example.com`) and determine where the Matrix server is automatically (e.g. `https://matrix.example.com`).
+Client Server Service discovery lets various client programs which support it, to receive a full user ID (e.g. `@alice:example.com`) and determine where the Matrix server is automatically (e.g. `https://matrix.example.com`).
 
 This lets you (and your users) easily connect to your Matrix server without having to customize connection URLs. When using client programs that support it, you won't need to point them to `https://matrix.example.com` in Custom Server options manually anymore. The connection URL would be discovered automatically from your full username.
 

docs/faq.md

@@ -26,9 +26,9 @@ In the world of the Matrix chat protocol, there are various client programs. The
 
 Matrix is also like email due to the fact that there are many servers around the world which can all talk to each other (you can send email from `@gmail.com` addresses to `@yahoo.com` and `@hotmail.com` addresses). It's the same with Matrix (`@bob:example.com` can talk to `@alice:example.org`).
 
-If someone else is hosting your Matrix server (you being `@user:matrix.org` or some other public server like this), all you need is a Matrix client program, like Element Web or Element X Android.
+If someone else is hosting your Matrix server (you being `@alice:matrix.org` or some other public server like this), all you need is a Matrix client program, like Element Web or Element X Android.
 
-If you'd like to host your own server (you being `@user:example.com`), you'd need to set up a Matrix server program, like Synapse.
+If you'd like to host your own server (you being `@alice:example.com`), you'd need to set up a Matrix server program, like Synapse.
 
 In short:
 
@@ -56,7 +56,7 @@ There are 3 ways to get into Matrix, depending on your technical ability and nee
 
 - **using some other server** - instead of using the largest public server (`matrix.org`), you can use another public one. Here's a [list of public Matrix servers](https://joinmatrix.org/servers/) to choose from. Go to [Element Web](https://app.element.io) or download [some other client](https://matrix.org/clients/) of your choosing and adjust the homeserver URL during login.
 
-- **using your own server** - running your own server puts you in ultimate control of your data. It also lets you have your own user identifiers (e.g. `@bob:example.com`). See [How do I set up my own Matrix server](#how-do-i-set-up-my-own-matrix-server).
+- **using your own server** - running your own server puts you in ultimate control of your data. It also lets you have your own user IDs (e.g. `@bob:example.com`). See [How do I set up my own Matrix server](#how-do-i-set-up-my-own-matrix-server).
 
 ### How do I set up my own Matrix server?
 
@@ -281,7 +281,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 
   `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. Note these shortcuts run the `ensure-matrix-users-created` tag too.
 
-- Without setting up [server delegation](howto-server-delegation.md) to `matrix.example.com`, your user identifiers will be like `@user:matrix.example.com`. This is equivalent to having an email address like `bob@mail.company.com`, instead of just `bob@company.com`.
+- Without setting up [server delegation](howto-server-delegation.md) to `matrix.example.com`, your user IDs will be like `@alice:matrix.example.com`. This is equivalent to having an email address like `bob@mail.company.com`, instead of just `bob@company.com`.
 
 ### I don't use the base domain for anything. How am I supposed to set up Server Delegation for Matrix services?
 
@@ -391,7 +391,7 @@ Yes, you can.
 
 You generally need to do a playbook installation. It's recommended to follow the full installation guide (starting at the [Prerequisites](prerequisites.md) page), not the [Quick start](quick-start.md) guide. The full installation guide will tell you when it's time to import your existing data into the newly-prepared server.
 
-This Ansible playbook guides you into installing a server for `example.com` (user identifiers are like this: `@user:example.com`), while the server is at `matrix.example.com`. If your existing setup has a server name (`server_name` configuration setting in Synapse's `homeserver.yaml` file) other than the base `example.com`, you may need to tweak some additional variables. This FAQ entry may be of use if you're dealing with a more complicated setup - [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrixexamplecom-without-involving-the-base-domain)
+This Ansible playbook guides you into installing a server for `example.com` (user IDs are like this: `@alice:example.com`), while the server is at `matrix.example.com`. If your existing setup has a server name (`server_name` configuration setting in Synapse's `homeserver.yaml` file) other than the base `example.com`, you may need to tweak some additional variables. This FAQ entry may be of use if you're dealing with a more complicated setup - [How do I install on matrix.example.com without involving the base domain?](#how-do-i-install-on-matrixexamplecom-without-involving-the-base-domain)
 
 After configuring the playbook and installing and **before starting** services (done with `ansible-playbook … --tags=start`) you'd import [your SQLite](importing-synapse-sqlite.md) (or [Postgres](importing-postgres.md)) database and also [import your media store](importing-synapse-media-store.md).
 

docs/installing.md

@@ -83,7 +83,7 @@ To create your user account (as an administrator of the server) via this Ansible
 
 **Notes**:
 - Make sure to adjust `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE`
-- For `YOUR_USERNAME_HERE`, use a plain username like `alice`, not your full identifier (`@alice:example.com`)
+- For `YOUR_USERNAME_HERE`, use a plain username like `alice`, not your full ID (`@alice:example.com`)
 - Use `admin=yes` to make your user account an administrator of the Matrix server
 
 ```sh
@@ -104,7 +104,7 @@ This is required for federation to work! Without a proper configuration, your se
 
 To configure the delegation, you have these two options. Choose one of them according to your situation.
 
-- If you can afford to point the base domain at the Matrix server, follow the instructions below which guide you into [serving the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server. It will enable you to use a Matrix user identifier like `@<username>:example.com` while hosting services on a subdomain like `matrix.example.com`.
+- If you can afford to point the base domain at the Matrix server, follow the instructions below which guide you into [serving the base domain](configuring-playbook-base-domain-serving.md) from the integrated web server. It will enable you to use a Matrix user ID like `@alice:example.com` while hosting services on a subdomain like `matrix.example.com`.
 - Alternatively, if you're using the base domain for other purposes and cannot point it to the Matrix server (and thus cannot "serve the base domain" from it), you most likely need to [manually install well-known files on the base domain's server](configuring-well-known.md#manually-installing-well-known-files-on-the-base-domains-server), but feel free to familiarize yourself with all [server delegation (redirection) options](howto-server-delegation.md).
 
 To have the base domain served from the integrated web server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:

docs/obtaining-access-tokens.md

@@ -26,7 +26,7 @@ You can use the following command to get an access token for your user directly
 
 ```sh
 curl -XPOST -d '{
-    "identifier": { "type": "m.id.user", "user": "USERNAME" },
+    "identifier": { "type": "m.id.user", "user": "alice" },
     "password": "PASSWORD",
     "type": "m.login.password",
     "device_id": "YOURDEVICEID"
@@ -40,7 +40,7 @@ Your response will look like this (prettified):
 
 ```
 {
-    "user_id":"@USERNAME:example.com",
+    "user_id":"@alice:example.com",
     "access_token":">>>YOUR_ACCESS_TOKEN_IS_HERE<<<",
     "home_server":"example.com",
     "device_id":"YOURDEVICEID"

docs/quick-start.md

@@ -13,7 +13,7 @@ We will be using `example.com` as the "base domain" in the following instruction
 By following the instruction on this page, you will set up:
 
 - **your own Matrix server** on a `matrix.example.com` server, which is configured to present itself as `example.com`
-- **your user account** like `@user:example.com` on the server
+- **your user account** like `@alice:example.com` on the server
 - a **self-hosted Matrix client**, [Element Web](configuring-playbook-client-element-web.md) with the default subdomain at `element.example.com`
 - Matrix delegation, so that your `matrix.example.com` server (presenting itself as `example.com`) can join the Matrix Federation and communicate with any other server in the Matrix network
 
@@ -136,7 +136,7 @@ To create your user account (as an administrator of the server) via this Ansible
 
 **💡 Notes**:
 - Make sure to adjust `YOUR_USERNAME_HERE` and `YOUR_PASSWORD_HERE`
-- For `YOUR_USERNAME_HERE`, use a plain username like `alice`, not your full identifier (`@alice:example.com`)
+- For `YOUR_USERNAME_HERE`, use a plain username like `alice`, not your full ID (`@alice:example.com`)
 
 ```sh
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=yes' --tags=register-user

docs/registering-users.md

@@ -15,7 +15,7 @@ Table of contents:
 
 **Notes**:
 - Make sure to adjust `USERNAME_HERE` and `PASSWORD_HERE`
-- For `USERNAME_HERE`, use a plain username like `alice`, not a full identifier (`@alice:example.com`)
+- For `USERNAME_HERE`, use a plain username like `alice`, not a full ID (`@alice:example.com`)
 - Use `admin=yes` or `admin=no` depending on whether you wish to make the user an administrator of the Matrix server
 
 After registering a user (using one of the methods below), **you can log in with that user** via the [Element Web](configuring-playbook-client-element-web.md) service that this playbook has installed for you at a URL like this: `https://element.example.com/`.
@@ -130,7 +130,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 To change the admin privileges for a user in Synapse's local database, you need to run an SQL query like this against the `synapse` database:
 
 ```sql
-UPDATE users SET admin=ADMIN_VALUE WHERE name = '@USER:example.com';
+UPDATE users SET admin=ADMIN_VALUE WHERE name = '@alice:example.com';
 ```
 
 where:

docs/updating-users-passwords.md

@@ -4,7 +4,7 @@
 
 **Notes**:
 - Make sure to adjust `USERNAME_HERE` and `PASSWORD_HERE`
-- For `USERNAME_HERE`, use a plain username like `alice`, not a full identifier (`@alice:example.com`)
+- For `USERNAME_HERE`, use a plain username like `alice`, not a full ID (`@alice:example.com`)
 
 You can reset a user's password via the Ansible playbook:
 
@@ -25,7 +25,7 @@ docker exec -it matrix-synapse /usr/local/bin/hash_password -c /data/homeserver.
 and then connecting to the postgres server and executing:
 
 ```sql
-UPDATE users SET password_hash = '<password-hash>' WHERE name = '@someone:example.com';
+UPDATE users SET password_hash = '<password-hash>' WHERE name = '@alice:example.com';
 ```
 
 where `<password-hash>` is the hash returned by the docker command above.
@@ -40,8 +40,8 @@ If you didn't make your account a server admin when you created it, you can lear
 
 ### Example:
 
-To set @user:example.com's password to `correct_horse_battery_staple` you could use this curl command:
+To set @alice:example.com's password to `correct_horse_battery_staple` you could use this curl command:
 
 ```sh
-curl -XPOST -d '{ "new_password": "correct_horse_battery_staple" }' "https://matrix.example.com/_matrix/client/r0/admin/reset_password/@user:example.com?access_token=MDA...this_is_my_access_token
+curl -XPOST -d '{ "new_password": "correct_horse_battery_staple" }' "https://matrix.example.com/_matrix/client/r0/admin/reset_password/@alice:example.com?access_token=MDA...this_is_my_access_token
 ```

examples/vars.yml

@@ -1,6 +1,6 @@
 ---
 # The bare domain name which represents your Matrix identity.
-# Matrix user IDs for your server will be of the form (`@user:example.com`).
+# Matrix user IDs for your server will be of the form (`@alice:example.com`).
 #
 # Note: this playbook does not touch the server referenced here.
 # Installation happens on another server ("matrix.example.com", see `matrix_server_fqn_matrix`).

group_vars/matrix_servers

@@ -1835,17 +1835,15 @@ matrix_mautrix_twitter_appservice_token: "{{ '%s' | format(matrix_homeserver_gen
 matrix_mautrix_twitter_homeserver_address: "{{ matrix_addons_homeserver_client_api_url }}"
 matrix_mautrix_twitter_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'twt.hs.token', rounds=655555) | to_uuid }}"
 
-matrix_mautrix_twitter_bridge_login_shared_secret_map_auto: |-
+matrix_mautrix_twitter_provisioning_shared_secret: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'mau.twit.prov', rounds=655555) | to_uuid }}"
+
+matrix_mautrix_twitter_double_puppet_secrets_auto: |-
   {{
     ({
       matrix_mautrix_twitter_homeserver_domain: ("as_token:" + matrix_appservice_double_puppet_registration_as_token)
     })
     if matrix_appservice_double_puppet_enabled
-    else (
-      {matrix_mautrix_twitter_homeserver_domain: matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret}
-      if matrix_synapse_ext_password_provider_shared_secret_auth_enabled
-      else {}
-    )
+    else {}
   }}
 
 matrix_mautrix_twitter_metrics_enabled: "{{ prometheus_enabled or matrix_metrics_exposure_enabled }}"

justfile

@@ -1,6 +1,6 @@
 # Shows help
 default:
-    @just --list --justfile {{ justfile() }}
+    @{{ just_executable() }} --list --justfile {{ justfile() }}
 
 # Pulls external Ansible roles
 roles:
@@ -17,7 +17,7 @@ roles:
 update *flags: update-playbook-only
     #!/usr/bin/env sh
     if [ -x "$(command -v agru)" ]; then
-        echo {{ if flags == "" { "Installing roles pinned in requirements.yml…" } else if flags == "-u" { "Updating roles and pinning new versions in requirements.yml…" } else { "Unknown flags passed" } }}
+        echo {{ if flags == "" { "Installing roles pinned in requirements.yml…" } else { if flags == "-u" { "Updating roles and pinning new versions in requirements.yml…" } else { "Unknown flags passed" } } }}
         agru {{ flags }}
     else
         echo "[NOTE] You are using the standard ansible-galaxy tool to install roles, which is slow and lacks other features. We recommend installing the 'agru' tool to speed up the process: https://github.com/etkecc/agru#where-to-get"
@@ -42,7 +42,7 @@ install-all *extra_args: (run-tags "install-all,ensure-matrix-users-created,star
 
 # Runs installation tasks for a single service
 install-service service *extra_args:
-    just --justfile {{ justfile() }} run \
+    {{ just_executable() }} --justfile {{ justfile() }} run \
     --tags=install-{{ service }},start-group \
     --extra-vars=group={{ service }} \
     --extra-vars=devture_systemd_service_manager_service_restart_mode=one-by-one {{ extra_args }}
@@ -56,7 +56,7 @@ run +extra_args:
 
 # Runs the playbook with the given list of comma-separated tags and optional arguments
 run-tags tags *extra_args:
-    just --justfile {{ justfile() }} run --tags={{ tags }} {{ extra_args }}
+    {{ just_executable() }} --justfile {{ justfile() }} run --tags={{ tags }} {{ extra_args }}
 
 # Runs the playbook in user-registration mode
 register-user username password admin_yes_or_no *extra_args:
@@ -67,14 +67,14 @@ start-all *extra_args: (run-tags "start-all" extra_args)
 
 # Starts a specific service group
 start-group group *extra_args:
-    @just --justfile {{ justfile() }} run-tags start-group --extra-vars="group={{ group }}" {{ extra_args }}
+    @{{ just_executable() }} --justfile {{ justfile() }} run-tags start-group --extra-vars="group={{ group }}" {{ extra_args }}
 
 # Stops all services
 stop-all *extra_args: (run-tags "stop-all" extra_args)
 
 # Stops a specific service group
 stop-group group *extra_args:
-    @just --justfile {{ justfile() }} run-tags stop-group --extra-vars="group={{ group }}" {{ extra_args }}
+    @{{ just_executable() }} --justfile {{ justfile() }} run-tags stop-group --extra-vars="group={{ group }}" {{ extra_args }}
 
 # Rebuilds the mautrix-meta-instagram Ansible role using the mautrix-meta-messenger role as a source
 rebuild-mautrix-meta-instagram:

roles/custom/matrix-base/defaults/main.yml

@@ -1,7 +1,7 @@
 ---
 
 # The bare domain name which represents your Matrix identity.
-# Matrix user IDs for your server will be of the form (`@user:example.com`).
+# Matrix user IDs for your server will be of the form (`@alice:example.com`).
 #
 # Note: this playbook does not touch the server referenced here.
 # Installation happens on another server ("matrix.example.com", see `matrix_server_fqn_matrix`).
@@ -10,7 +10,7 @@
 matrix_domain: ~
 
 # The optional Matrix admin MXID, used in bridges' configs to set bridge admin user
-# Example value: "@someone:{{ matrix_domain }}"
+# Example value: "@alice:{{ matrix_domain }}"
 matrix_admin: ''
 
 # Global var to enable/disable encryption across all bridges with encryption support

roles/custom/matrix-bot-baibot/defaults/main.yml

@@ -11,7 +11,7 @@ matrix_bot_baibot_container_repo_version: "{{ 'main' if matrix_bot_baibot_versio
 matrix_bot_baibot_container_src_files_path: "{{ matrix_base_data_path }}/baibot/container-src"
 
 # renovate: datasource=docker depName=ghcr.io/etkecc/baibot
-matrix_bot_baibot_version: v1.4.0
+matrix_bot_baibot_version: v1.4.1
 matrix_bot_baibot_container_image: "{{ matrix_bot_baibot_container_image_name_prefix }}etkecc/baibot:{{ matrix_bot_baibot_version }}"
 matrix_bot_baibot_container_image_name_prefix: "{{ 'localhost/' if matrix_bot_baibot_container_image_self_build else 'ghcr.io/' }}"
 matrix_bot_baibot_container_image_force_pull: "{{ matrix_bot_baibot_container_image.endswith(':latest') }}"

roles/custom/matrix-bot-chatgpt/defaults/main.yml

@@ -57,7 +57,7 @@ matrix_bot_chatgpt_keyv_bot_storage: true
 # Matrix Static Settings (required, see notes)
 # Defaults to "https://matrix.org"
 matrix_bot_chatgpt_matrix_homeserver_url: ""  # MATRIX_HOMESERVER_URL=
-# With the @ and :example.com, ie @SOMETHING:example.com, needs to be set, created manually beforehand.
+# With the @ and :example.com, ie @bot.chatgpt:example.com, needs to be set, created manually beforehand.
 matrix_bot_chatgpt_matrix_bot_username_localpart: 'bot.chatgpt'
 matrix_bot_chatgpt_matrix_bot_username: "@{{ matrix_bot_chatgpt_matrix_bot_username_localpart }}:{{ matrix_domain }}"  # MATRIX_BOT_USERNAME=
 # Set `MATRIX_BOT_PASSWORD` the bot will print an `MATRIX_ACCESS_TOKEN` to the terminal
@@ -87,8 +87,8 @@ matrix_bot_chatgpt_matrix_rich_text: true  # MATRIX_RICH_TEXT=true
 # A list of admins
 # Example set of rules:
 # matrix_bot_chatgpt_admins:
-# - @someone:example.com
-# - @another:example.com
+# - @alice:example.com
+# - @bob:example.com
 # - @bot.*:example.com
 # - @*:example.net
 # matrix_bot_chatgpt_admins: "{{ [matrix_admin] if matrix_admin else [] }}"

roles/custom/matrix-bot-chatgpt/templates/env.j2

@@ -10,7 +10,7 @@ KEYV_URL={{ matrix_bot_chatgpt_keyv_url }}
 KEYV_BOT_ENCRYPTION={{ matrix_bot_chatgpt_keyv_bot_encryption|lower }}
 KEYV_BOT_STORAGE={{ matrix_bot_chatgpt_keyv_bot_storage|lower }}
 
-# With the @ and :example.com, ie @SOMETHING:example.com
+# With the @ and :example.com, ie @bot.chatgpt:example.com
 MATRIX_BOT_USERNAME={{ matrix_bot_chatgpt_matrix_bot_username }}
 MATRIX_BOT_PASSWORD={{ matrix_bot_chatgpt_matrix_bot_password }}
 

roles/custom/matrix-bot-go-neb/defaults/main.yml

@@ -200,7 +200,7 @@ matrix_bot_go_neb_realms: []
 matrix_bot_go_neb_sessions: []
 #  - SessionID: "your_github_session"
 #    RealmID: "github_realm"
-#    UserID: "@YOUR_USER_ID:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
+#    UserID: "@alice:{{ matrix_domain }}" # This needs to be the username of the person that's allowed to use the !github commands
 #    Config:
 #      # Populate these fields by generating a "Personal Access Token" on github.com
 #      AccessToken: "YOUR_GITHUB_ACCESS_TOKEN"
@@ -286,7 +286,7 @@ matrix_bot_go_neb_services: []
 #    UserID: "@another_goneb:{{ matrix_domain }}"
 #    Config:
 #      RealmID: "github_realm"
-#      ClientUserID: "@YOUR_USER_ID:{{ matrix_domain }}" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
+#      ClientUserID: "@alice:{{ matrix_domain }}" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
 #      Rooms:
 #        "!qporfwt:example.com":
 #          Repos:

roles/custom/matrix-bot-honoroit/defaults/main.yml

@@ -165,8 +165,8 @@ matrix_bot_honoroit_redmine_done_status_id: ''  # done status ID (e.g. 3)
 # If not defined, everyone is allowed.
 # Example set of rules:
 # matrix_bot_honoroit_allowedusers:
-# - @someone:example.com
-# - @another:example.com
+# - @alice:example.com
+# - @bob:example.com
 # - @bot.*:example.com
 # - @*:example.net
 matrix_bot_honoroit_allowedusers:

roles/custom/matrix-bridge-appservice-irc/defaults/main.yml

@@ -12,7 +12,7 @@ matrix_appservice_irc_docker_src_files_path: "{{ matrix_base_data_path }}/appser
 # matrix_appservice_irc_version used to contain the full Docker image tag (e.g. `release-X.X.X`).
 # It's a bare version number now. We try to somewhat retain compatibility below.
 # renovate: datasource=docker depName=docker.io/matrixdotorg/matrix-appservice-irc
-matrix_appservice_irc_version: 1.0.1
+matrix_appservice_irc_version: 3.0.1
 matrix_appservice_irc_docker_image: "{{ matrix_container_global_registry_prefix }}matrixdotorg/matrix-appservice-irc:{{ matrix_appservice_irc_docker_image_tag }}"
 matrix_appservice_irc_docker_image_tag: "{{ 'latest' if matrix_appservice_irc_version == 'latest' else ('release-' + matrix_appservice_irc_version) }}"
 matrix_appservice_irc_docker_image_force_pull: "{{ matrix_appservice_irc_docker_image.endswith(':latest') }}"
@@ -66,20 +66,25 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #     # It is also used in the Third Party Lookup API as the instance `desc`
 #     # property, where each server is an instance.
 #     name: "ExampleNet"
-
+#     # Additional addresses to connect to, used for load balancing between IRCDs.
 #     additionalAddresses: [ "irc2.example.com" ]
+#     # Typically additionalAddresses would be in addition to the address key given above,
+#     # but some configurations wish to exclusively use additional addresses while reserving
+#     # the top key for identification purposes. Set this to true to exclusively use the
+#     # additionalAddresses array when connecting to servers.
+#     onlyAdditionalAddresses: false
 #     #
 #     # [DEPRECATED] Use `name`, above, instead.
 #     # A human-readable description string
 #     # description: "Example.com IRC network"
-
+#
 #     # An ID for uniquely identifying this server amongst other servers being bridged.
 #     # networkId: "example"
-
-#     # URL to an icon used as the network icon whenever this network appear in
-#     # a network list. (Like in the Riot room directory, for instance.)
-#     # icon: https://example.com/images/hash.png
-
+#
+#     # MXC URL to an icon used as the network icon whenever this network appear in
+#     # a network list. (Like in the Element room directory, for instance.)
+#     # icon: mxc://matrix.org/LpsSLrbANVrEIEOgEaVteItf
+#
 #     # The port to connect to. Optional.
 #     port: 6697
 #     # Whether to use SSL or not. Default: false.
@@ -92,19 +97,25 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #     # Whether to allow expired certs when connecting to the IRC server.
 #     # Usually this should be off. Default: false.
 #     allowExpiredCerts: false
-#     # A specific CA to trust instead of the default CAs. Optional.
-#     #ca: |
-#     #  -----BEGIN CERTIFICATE-----
-#     #  …
-#     #  -----END CERTIFICATE-----
-
+#     # Set additional TLS options for the connections to the IRC server.
+#     #tlsOptions:
+#       # A specific CA to trust instead of the default CAs. Optional.
+#       #ca: |
+#       #  -----BEGIN CERTIFICATE-----
+#       #  ...
+#       #  -----END CERTIFICATE-----
+#       # Server name for the SNI (Server Name Indication) TLS extension. If the address you
+#       # are using does not report the correct certificate name, you can override it here.
+#       # servername: real.server.name
+#       # ...or any options in https://nodejs.org/api/tls.html#tls_tls_connect_options_callback
+#
 #     #
 #     # The connection password to send for all clients as a PASS (or SASL, if enabled above) command. Optional.
 #     # password: 'pa$$w0rd'
 #     #
 #     # Whether or not to send connection/error notices to real Matrix users. Default: true.
 #     sendConnectionMessages: true
-
+#
 #     quitDebounce:
 #       # Whether parts due to net-splits are debounced for delayMs, to allow
 #       # time for the netsplit to resolve itself. A netsplit is detected as being
@@ -124,13 +135,13 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #       delayMinMs: 3600000 # 1h
 #       # Default: 7200000, = 2h
 #       delayMaxMs: 7200000 # 2h
-
+#
 #     # A map for conversion of IRC user modes to Matrix power levels. This enables bridging
 #     # of IRC ops to Matrix power levels only, it does not enable the reverse. If a user has
 #     # been given multiple modes, the one that maps to the highest power level will be used.
 #     modePowerMap:
 #       o: 50
-
+#       v: 1
 #     botConfig:
 #       # Enable the presence of the bot in IRC channels. The bot serves as the entity
 #       # which maps from IRC -> Matrix. You can disable the bot entirely which
@@ -153,6 +164,8 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #       enabled: true
 #       # The nickname to give the AS bot.
 #       nick: "MatrixBot"
+#       # The username to give to the AS bot. Defaults to "matrixbot"
+#       username: "matrixbot"
 #       # The password to give to NickServ or IRC Server for this nick. Optional.
 #       # password: "helloworld"
 #       #
@@ -161,7 +174,7 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #       # real Matrix users in them, even if there is a mapping for the channel.
 #       # Default: true
 #       joinChannelsIfNoUsers: true
-
+#
 #     # Configuration for PMs / private 1:1 communications between users.
 #     privateMessages:
 #       # Enable the ability for PMs to be sent to/from IRC/Matrix.
@@ -170,12 +183,12 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #       # Prevent Matrix users from sending PMs to the following IRC nicks.
 #       # Optional. Default: [].
 #       # exclude: ["Alice", "Bob"] # NOT YET IMPLEMENTED
-
+#
 #       # Should created Matrix PM rooms be federated? If false, only users on the
 #       # HS attached to this AS will be able to interact with this room.
 #       # Optional. Default: true.
 #       federate: true
-
+#
 #     # Configuration for mappings not explicitly listed in the 'mappings'
 #     # section.
 #     dynamicChannels:
@@ -189,27 +202,34 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #       # Should the AS publish the new Matrix room to the public room list so
 #       # anyone can see it? Default: true.
 #       published: true
+#       # Publish the rooms to the homeserver directory, as oppose to the appservice
+#       # room directory. Only used if `published` is on.
+#       # Default: false
+#       useHomeserverDirectory: true
 #       # What should the join_rule be for the new Matrix room? If 'public',
 #       # anyone can join the room. If 'invite', only users with an invite can
 #       # join the room. Note that if an IRC channel has +k or +i set on it,
 #       # join_rules will be set to 'invite' until these modes are removed.
 #       # Default: "public".
 #       joinRule: public
-#       # This will set the m.room.related_groups state event in newly created rooms
-#       # with the given groupId. This means flares will show up on IRC users in those rooms.
-#       # This should be set to the same thing as namespaces.users.group_id in irc_registration.
-#       # This does not alter existing rooms.
-#       # Leaving this option empty will not set the event.
-#       groupId: +myircnetwork:localhost
 #       # Should created Matrix rooms be federated? If false, only users on the
 #       # HS attached to this AS will be able to interact with this room.
 #       # Default: true.
 #       federate: true
+#       # Force this room version when creating IRC channels. Beware if the homeserver doesn't
+#       # support the room version then the request will fail. By default, no version is requested.
+#       # roomVersion: "1"
 #       # The room alias template to apply when creating new aliases. This only
 #       # applies if createAlias is 'true'. The following variables are exposed:
 #       # $SERVER => The IRC server address (e.g. "irc.example.com")
 #       # $CHANNEL => The IRC channel (e.g. "#python")
 #       # This MUST have $CHANNEL somewhere in it.
+#       #
+#       # In certain circumstances you might want to bridge your whole IRC network as a
+#       # homeserver (e.g. #matrix:libera.chat). For these use cases, you can set the
+#       # template to just be $CHANNEL. Doing so will preclude you from supporting
+#       # other prefix characters though.
+#       #
 #       # Default: '#irc_$SERVER_$CHANNEL'
 #       aliasTemplate: "#irc_$CHANNEL"
 #       # A list of user IDs which the AS bot will send invites to in response
@@ -221,7 +241,11 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #       # Prevent the given list of channels from being mapped under any
 #       # circumstances.
 #       # exclude: ["#foo", "#bar"]
-
+#
+#     # excludedUsers:
+#     #   - regex: "@.*:evilcorp.com"
+#     #     kickReason: "We don't like Evilcorp"
+#
 #     # Configuration for controlling how Matrix and IRC membership lists are
 #     # synced.
 #     membershipLists:
@@ -230,12 +254,12 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #       # synced. This must be enabled for anything else in this section to take
 #       # effect. Default: false.
 #       enabled: false
-
+#
 #       # Syncing membership lists at startup can result in hundreds of members to
 #       # process all at once. This timer drip feeds membership entries at the
 #       # specified rate. Default: 10000. (10s)
 #       floodDelayMs: 10000
-
+#
 #       global:
 #         ircToMatrix:
 #           # Get a snapshot of all real IRC users on a channel (via NAMES) and
@@ -244,7 +268,14 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #           # Make virtual Matrix clients join and leave rooms as their real IRC
 #           # counterparts join/part channels. Default: false.
 #           incremental: false
-
+#           # Should the bridge check if all Matrix users are connected to IRC and
+#           # joined to the channel before relaying messages into the room.
+#           #
+#           # This is considered a safety net to avoid any leakages by the bridge to
+#           # unconnected users, but given it ignores all IRC messages while users
+#           # are still connecting it may be overkill.
+#           requireMatrixJoined: false
+#
 #         matrixToIrc:
 #           # Get a snapshot of all real Matrix users in the room and join all of
 #           # them to the mapped IRC channel on startup. Default: false.
@@ -253,21 +284,32 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #           # counterparts join/leave rooms. Make sure your 'maxClients' value is
 #           # high enough! Default: false.
 #           incremental: false
-
+#
 #       # Apply specific rules to Matrix rooms. Only matrix-to-IRC takes effect.
 #       rooms:
 #         - room: "!qporfwt:localhost"
 #           matrixToIrc:
 #             initial: false
 #             incremental: false
-
+#
 #       # Apply specific rules to IRC channels. Only IRC-to-matrix takes effect.
 #       channels:
 #         - channel: "#foo"
 #           ircToMatrix:
 #             initial: false
 #             incremental: false
-
+#             requireMatrixJoined: false
+#
+#       # Should the bridge ignore users which are not considered active on the bridge
+#       # during startup
+#       ignoreIdleUsersOnStartup:
+#         enabled: true
+#         # How many hours can a user be considered idle for before they are considered
+#         # ignoreable
+#         idleForHours: 720
+#         # A regex which will exclude matching MXIDs from this check.
+#         exclude: "foobar"
+#
 #     mappings:
 #       # 1:many mappings from IRC channels to room IDs on this IRC server.
 #       # The Matrix room must already exist. Your Matrix client should expose
@@ -277,27 +319,27 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #         # Channel key/password to use. Optional. If provided, Matrix users do
 #         # not need to know the channel key in order to join the channel.
 #         # key: "secret"
-
+#
 #     # Configuration for virtual Matrix users. The following variables are
 #     # exposed:
 #     # $NICK => The IRC nick
 #     # $SERVER => The IRC server address (e.g. "irc.example.com")
 #     matrixClients:
 #       # The user ID template to use when creating virtual Matrix users. This
-#       # MUST have $NICK somewhere in it.
+#       # MUST start with an @ and have $NICK somewhere in it.
 #       # Optional. Default: "@$SERVER_$NICK".
 #       # Example: "@irc.example.com_Alice:example.com"
 #       userTemplate: "@irc_$NICK"
 #       # The display name to use for created Matrix clients. This should have
 #       # $NICK somewhere in it if it is specified. Can also use $SERVER to
 #       # insert the IRC domain.
-#       # Optional. Default: "$NICK (IRC)". Example: "Alice (IRC)"
-#       displayName: "$NICK (IRC)"
+#       # Optional. Default: "$NICK". Example: "Alice"
+#       displayName: "$NICK"
 #       # Number of tries a client can attempt to join a room before the request
 #       # is discarded. You can also use -1 to never retry or 0 to never give up.
 #       # Optional. Default: -1
 #       joinAttempts: -1
-
+#
 #     # Configuration for virtual IRC users. The following variables are exposed:
 #     # $LOCALPART => The user ID localpart ("alice" in @alice:localhost)
 #     # $USERID => The user ID
@@ -326,9 +368,20 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #         # connected user. If not specified, all users will connect from the same
 #         # (default) address. This may require additional OS-specific work to allow
 #         # for the node process to bind to multiple different source addresses
-#         # e.g IP_FREEBIND on Linux, which requires an LD_PRELOAD with the library
+#         # Linux kernels 4.3+ support sysctl net.ipv6.ip_nonlocal_bind=1
+#         # Older kernels will need IP_FREEBIND, which requires an LD_PRELOAD with the library
 #         # https://github.com/matrix-org/freebindfree as Node does not expose setsockopt.
 #         # prefix: "2001:0db8:85a3::"  # modify appropriately
+#
+#         # Optional. Define blocks of IPv6 addresses for different homeservers
+#         # which can be used to restrict users of those homeservers to a given
+#         # IP. These blocks should be considered immutable once set, as changing
+#         # the startFrom value will NOT adjust existing IP addresses.
+#         # Changing the startFrom value to a lower value may conflict with existing clients.
+#         # Multiple homeservers may NOT share blocks.
+#         blocks:
+#           - homeserver: another-server.org
+#             startFrom: '10:0000'
 #       #
 #       # The maximum amount of time in seconds that the client can exist
 #       # without sending another message before being disconnected. Use 0 to
@@ -365,6 +418,25 @@ matrix_appservice_irc_ircService_servers: []  # noqa var-naming
 #       # through the bridge e.g. caller ID as there is no way to /ACCEPT.
 #       # Default: "" (no user modes)
 #       # userModes: "R"
+#       # The format of the realname defined for users, either mxid or reverse-mxid
+#       realnameFormat: "mxid"
+#       # The minimum time to wait between connection attempts if we were disconnected
+#       # due to throttling.
+#       # pingTimeoutMs: 600000
+#       # The rate at which to send pings to the IRCd if the client is being quiet for a while.
+#       # Whilst the IRCd *should* be sending pings to us to keep the connection alive, it appears
+#       # that sometimes they don't get around to it and end up ping timing us out.
+#       # pingRateMs: 60000
+#       # Choose which conditions the IRC bridge should kick Matrix users for. Decisions to this from
+#       # defaults should be taken with care as it may dishonestly repesent Matrix users on the IRC
+#       # network, and cause your bridge to be banned.
+#       kickOn:
+#         # Kick a Matrix user from a bridged room if they fail to join the IRC channel.
+#         channelJoinFailure: true
+#         # Kick a Matrix user from ALL rooms if they are unable to get connected to IRC.
+#         ircConnectionFailure: true
+#         # Kick a Matrix user from ALL rooms if they choose to QUIT the IRC network.
+#         userQuit: true
 
 # Controls whether the matrix-appservice-discord container exposes its HTTP port (tcp/9999 in the container).
 #

roles/custom/matrix-bridge-appservice-irc/templates/config.yaml.j2

@@ -1,14 +1,13 @@
 #jinja2: lstrip_blocks: True
+#
+# Based on https://github.com/matrix-org/matrix-appservice-irc/blob/8daebec7779a2480180cbc4c293838de649aab36/config.sample.yaml
+#
+# Configuration specific to AS registration. Unless other marked, all fields
+# are *REQUIRED*.
+# Unless otherwise specified, these keys CANNOT be hot-reloaded.
 homeserver:
-  # The URL to the home server for client-server API calls, also used to form the
-  # media URLs as displayed in bridged IRC channels:
-  url: {{ matrix_appservice_irc_homeserver_url }}
-  #
-  # The URL of the homeserver hosting media files. This is only used to transform
-  # mxc URIs to http URIs when bridging m.room.[file|image] events. Optional. By
-  # default, this is the homeserver URL, specified above.
-  #
-  media_url: {{ matrix_appservice_irc_homeserver_media_url }}
+  # The URL to the home server for client-server API calls
+  url: "{{ matrix_appservice_irc_homeserver_url }}"
 
   # Drop Matrix messages which are older than this number of seconds, according to
   # the event's origin_server_ts.
@@ -20,18 +19,29 @@ homeserver:
   # clock times and hence produce different origin_server_ts values, which may be old
   # enough to cause *all* events from the homeserver to be dropped.
   # Default: 0 (don't ever drop)
+  # This key CAN be hot-reloaded.
   # dropMatrixMessagesAfterSecs: 300 # 5 minutes
 
   # The 'domain' part for user IDs on this home server. Usually (but not always)
   # is the "domain name" part of the HS URL.
-  domain: {{ matrix_appservice_irc_homeserver_domain }}
+  domain: "{{ matrix_appservice_irc_homeserver_domain }}"
 
   # Should presence be enabled for Matrix clients on this bridge. If disabled on the
   # homeserver then it should also be disabled here to avoid excess traffic.
   # Default: true
   enablePresence: {{ matrix_appservice_irc_homeserver_enablePresence|to_json }}
 
+  # Which port should the appservice bind to. Can be overriden by the one provided in the
+  # command line! Optional.
+  # bindPort: 8090
+
+  # Use this option to force the appservice to listen on another hostname for transactions.
+  # This is NOT your synapse hostname. E.g. use 127.0.0.1 to only listen locally. Optional.
+  # bindHostname: 0.0.0.0
+
+# Configuration specific to the IRC service
 ircService:
+
   # WARNING: The bridge needs to send plaintext passwords to the IRC server, it cannot
   # send a password hash. As a result, passwords (NOT hashes) are stored encrypted in
   # the database.
@@ -50,11 +60,18 @@ ircService:
     # Cache this many Matrix events in memory to be used for m.relates_to messages (usually replies).
     eventCacheSize: 4096
 
+  # All server keys can be hot-reloaded, however existing IRC connections
+  # will not have changes applied to them.
   servers: {{ matrix_appservice_irc_ircService_servers|to_json }}
 
+  # present relevant UI to the user. MSC2346
+  bridgeInfoState:
+    enabled: false
+    initial: false
   # Configuration for an ident server. If you are running a public bridge it is
   # advised you setup an ident server so IRC mods can ban specific Matrix users
   # rather than the application service itself.
+  # This key CANNOT be hot-reloaded
   ident:
     # True to listen for Ident requests and respond with the
     # Matrix user's user_id (converted to ASCII, respecting RFC 1413).
@@ -71,6 +88,10 @@ ircService:
     # Default: 0.0.0.0
     address: "::"
 
+  # Encoding fallback - which text encoding to try if text is not UTF-8. Default: not set.
+  # List of supported encodings: https://www.npmjs.com/package/iconv#supported-encodings
+  # encodingFallback: "ISO-8859-15"
+
   # Configuration for logging. Optional. Default: console debug level logging
   # only.
   logging:
@@ -87,33 +108,42 @@ ircService:
     # to rotations.
     maxFiles: 5
 
-  # Optional. Enable Prometheus metrics. If this is enabled, you MUST install `prom-client`:
-  #   $ npm install prom-client@6.3.0
   # Metrics will then be available via GET /metrics on the bridge listening port (-p).
+  # This key CANNOT be hot-reloaded
   metrics:
     # Whether to actually enable the metric endpoint. Default: false
     enabled: true
+    # Which port to listen on (omit to listen on the bindPort)
+    #port: 7001
+    # Which hostname to listen on (omit to listen on 127.0.0.1), requires port to be set
+    host: 127.0.0.1
+    # When determining activeness of remote and matrix users, cut off at this number of hours.
+    userActivityThresholdHours: 72 # 3 days
     # When collecting remote user active times, which "buckets" should be used. Defaults are given below.
     # The bucket name is formed of a duration and a period. (h=hours,d=days,w=weeks).
     remoteUserAgeBuckets:
       - "1h"
       - "1d"
       - "1w"
-
   # Configuration for the provisioning API.
-  #
-  # GET /_matrix/provision/link
-  # GET /_matrix/provision/unlink
-  # GET /_matrix/provision/listlinks
-  #
+  # This key CANNOT be hot-reloaded
   provisioning:
     # True to enable the provisioning HTTP endpoint. Default: false.
     enabled: false
-    # The number of seconds to wait before giving up on getting a response from
-    # an IRC channel operator. If the channel operator does not respond within the
-    # allotted time period, the provisioning request will fail.
-    # Default: 300 seconds (5 mins)
-    requestTimeoutSeconds: 300
+    # Whether to enable hosting the setup widget page. Default: false.
+    widget: false
+
+  # Config for the media proxy, required to serve publically accessible URLs to authenticated Matrix media
+  mediaProxy:
+    # To generate a .jwk file:
+    # $ node src/generate-signing-key.js > signingkey.jwk
+    signingKeyPath: "signingkey.jwk"
+    # How long should the generated URLs be valid for
+    ttlSeconds: 3600
+    # The port for the media proxy to listen on
+    bindPort: 11111
+    # The publically accessible URL to the media proxy
+    publicUrl: "https://irc.bridge/media"
 
 # Options here are generally only applicable to large-scale bridges and may have
 # consequences greater than other options in this configuration file.
@@ -122,13 +152,18 @@ advanced:
   # however for large bridges it is important to rate limit the bridge to avoid
   # accidentally overloading the homeserver. Defaults to 1000, which should be
   # enough for the vast majority of use cases.
+  # This key CAN be hot-reloaded
   maxHttpSockets: 1000
+  # Max size of an appservice transaction payload, in bytes. Defaults to 10Mb
+  # This key CANNOT be hot-reloaded.
+  maxTxnSize: 10000000
 
 # Use an external database to store bridge state.
+# This key CANNOT be hot-reloaded.
 database:
   # database engine (must be 'postgres' or 'nedb'). Default: nedb
   engine: {{ matrix_appservice_irc_database_engine|to_json }}
   # Either a PostgreSQL connection string, or a path to the NeDB storage directory.
   # For postgres, it must start with postgres://
   # For NeDB, it must start with nedb://. The path is relative to the project directory.
-  connectionString: {{ matrix_appservice_irc_database_connectionString|to_json }}
+  connectionString: {{ matrix_appservice_irc_database_connectionString | to_json }}

roles/custom/matrix-bridge-appservice-kakaotalk/templates/config.yaml.j2

@@ -225,8 +225,8 @@ bridge:
         #
         # Available variables:
         #   $sender_displayname - The display name of the sender (e.g. Example User)
-        #   $sender_username    - The username (Matrix ID localpart) of the sender (e.g. exampleuser)
-        #   $sender_mxid        - The Matrix ID of the sender (e.g. @exampleuser:example.com)
+        #   $sender_username    - The username (Matrix ID localpart) of the sender (e.g. alice)
+        #   $sender_mxid        - The Matrix ID of the sender (e.g. @alice:example.com)
         #   $message            - The message content
         message_formats:
             m.text: '<b>$sender_displayname</b>: $message'

roles/custom/matrix-bridge-mautrix-discord/defaults/main.yml

@@ -9,7 +9,7 @@ matrix_mautrix_discord_container_image_self_build_repo: "https://mau.dev/mautrix
 matrix_mautrix_discord_container_image_self_build_branch: "{{ 'main' if matrix_mautrix_discord_version == 'latest' else matrix_mautrix_discord_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/discord
-matrix_mautrix_discord_version: v0.7.1
+matrix_mautrix_discord_version: v0.7.2
 
 # See: https://mau.dev/mautrix/discord/container_registry
 matrix_mautrix_discord_docker_image: "{{ matrix_mautrix_discord_docker_image_name_prefix }}mautrix/discord:{{ matrix_mautrix_discord_version }}"
@@ -57,6 +57,8 @@ matrix_mautrix_discord_homeserver_token: ''
 
 matrix_mautrix_discord_appservice_bot_username: discordbot
 
+matrix_mautrix_discord_provisioning_shared_secret: disable
+
 # Minimum severity of journal log messages.
 # Options: debug, info, warn, error, fatal
 matrix_mautrix_discord_logging_level: 'warn'

roles/custom/matrix-bridge-mautrix-discord/templates/config.yaml.j2

@@ -277,7 +277,7 @@ bridge:
         prefix: /_matrix/provision
         # Shared secret for authentication. If set to "generate", a random secret will be generated,
         # or if set to "disable", the provisioning API will be disabled.
-        shared_secret: generate
+        shared_secret: {{ matrix_mautrix_discord_provisioning_shared_secret | to_json }}
 
     # Permissions for using the bridge.
     # Permitted values:

roles/custom/matrix-bridge-mautrix-facebook/templates/config.yaml.j2

@@ -211,8 +211,8 @@ bridge:
         #
         # Available variables:
         #   $sender_displayname - The display name of the sender (e.g. Example User)
-        #   $sender_username    - The username (Matrix ID localpart) of the sender (e.g. exampleuser)
-        #   $sender_mxid        - The Matrix ID of the sender (e.g. @exampleuser:example.com)
+        #   $sender_username    - The username (Matrix ID localpart) of the sender (e.g. alice)
+        #   $sender_mxid        - The Matrix ID of the sender (e.g. @alice:example.com)
         #   $message            - The message content
         message_formats:
             m.text: '<b>$sender_displayname</b>: $message'

roles/custom/matrix-bridge-mautrix-gmessages/defaults/main.yml

@@ -9,7 +9,7 @@ matrix_mautrix_gmessages_container_image_self_build_repo: "https://github.com/ma
 matrix_mautrix_gmessages_container_image_self_build_branch: "{{ 'main' if matrix_mautrix_gmessages_version == 'latest' else matrix_mautrix_gmessages_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/gmessages
-matrix_mautrix_gmessages_version: v0.5.2
+matrix_mautrix_gmessages_version: v0.6.0
 
 # See: https://mau.dev/mautrix/gmessages/container_registry
 matrix_mautrix_gmessages_docker_image: "{{ matrix_mautrix_gmessages_docker_image_name_prefix }}mautrix/gmessages:{{ matrix_mautrix_gmessages_version }}"

roles/custom/matrix-bridge-mautrix-instagram/templates/config.yaml.j2

@@ -204,8 +204,8 @@ bridge:
     #
     # Available variables:
     #   $sender_displayname - The display name of the sender (e.g. Example User)
-    #   $sender_username    - The username (Matrix ID localpart) of the sender (e.g. exampleuser)
-    #   $sender_mxid        - The Matrix ID of the sender (e.g. @exampleuser:example.com)
+    #   $sender_username    - The username (Matrix ID localpart) of the sender (e.g. alice)
+    #   $sender_mxid        - The Matrix ID of the sender (e.g. @alice:example.com)
     #   $message            - The message content
     #
     # Note that Instagram doesn't support captions for images, so images won't include any indication of being relayed.

roles/custom/matrix-bridge-mautrix-meta-instagram/defaults/main.yml

@@ -13,7 +13,7 @@ matrix_mautrix_meta_instagram_enabled: true
 matrix_mautrix_meta_instagram_identifier: matrix-mautrix-meta-instagram
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/meta
-matrix_mautrix_meta_instagram_version: v0.4.2
+matrix_mautrix_meta_instagram_version: v0.4.3
 
 matrix_mautrix_meta_instagram_base_path: "{{ matrix_base_data_path }}/mautrix-meta-instagram"
 matrix_mautrix_meta_instagram_config_path: "{{ matrix_mautrix_meta_instagram_base_path }}/config"
@@ -156,6 +156,8 @@ matrix_mautrix_meta_instagram_meta_mode: instagram
 # When in `instagram` mode (see `matrix_mautrix_meta_instagram_meta_mode`), should the bridge connect to WhatsApp servers for encrypted chats?
 matrix_mautrix_meta_instagram_meta_ig_e2ee: false
 
+matrix_mautrix_meta_instagram_provisioning_shared_secret: disable
+
 # Whether or not metrics endpoint should be enabled.
 # Enabling them is usually enough for a local (in-container) Prometheus to consume them.
 # If metrics need to be consumed by another (external) Prometheus server, consider exposing them via `matrix_mautrix_meta_instagram_metrics_proxying_enabled`.

roles/custom/matrix-bridge-mautrix-meta-instagram/templates/config.yaml.j2

@@ -263,7 +263,7 @@ provisioning:
     prefix: /_matrix/provision
     # Shared secret for authentication. If set to "generate" or null, a random secret will be generated,
     # or if set to "disable", the provisioning API will be disabled.
-    shared_secret: disable
+    shared_secret: {{ matrix_mautrix_meta_instagram_provisioning_shared_secret | to_json }}
     # Whether to allow provisioning API requests to be authed using Matrix access tokens.
     # This follows the same rules as double puppeting to determine which server to contact to check the token,
     # which means that by default, it only works for users on the same server as the bridge.

roles/custom/matrix-bridge-mautrix-meta-messenger/defaults/main.yml

@@ -13,7 +13,7 @@ matrix_mautrix_meta_messenger_enabled: true
 matrix_mautrix_meta_messenger_identifier: matrix-mautrix-meta-messenger
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/meta
-matrix_mautrix_meta_messenger_version: v0.4.2
+matrix_mautrix_meta_messenger_version: v0.4.3
 
 matrix_mautrix_meta_messenger_base_path: "{{ matrix_base_data_path }}/mautrix-meta-messenger"
 matrix_mautrix_meta_messenger_config_path: "{{ matrix_mautrix_meta_messenger_base_path }}/config"
@@ -156,6 +156,8 @@ matrix_mautrix_meta_messenger_meta_mode: messenger
 # When in `instagram` mode (see `matrix_mautrix_meta_messenger_meta_mode`), should the bridge connect to WhatsApp servers for encrypted chats?
 matrix_mautrix_meta_messenger_meta_ig_e2ee: false
 
+matrix_mautrix_meta_messenger_provisioning_shared_secret: disable
+
 # Whether or not metrics endpoint should be enabled.
 # Enabling them is usually enough for a local (in-container) Prometheus to consume them.
 # If metrics need to be consumed by another (external) Prometheus server, consider exposing them via `matrix_mautrix_meta_messenger_metrics_proxying_enabled`.

roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2

@@ -263,7 +263,7 @@ provisioning:
     prefix: /_matrix/provision
     # Shared secret for authentication. If set to "generate" or null, a random secret will be generated,
     # or if set to "disable", the provisioning API will be disabled.
-    shared_secret: disable
+    shared_secret: {{ matrix_mautrix_meta_messenger_provisioning_shared_secret | to_json }}
     # Whether to allow provisioning API requests to be authed using Matrix access tokens.
     # This follows the same rules as double puppeting to determine which server to contact to check the token,
     # which means that by default, it only works for users on the same server as the bridge.

roles/custom/matrix-bridge-mautrix-signal/defaults/main.yml

@@ -9,7 +9,7 @@ matrix_mautrix_signal_container_image_self_build_repo: "https://mau.dev/mautrix/
 matrix_mautrix_signal_container_image_self_build_branch: "{{ 'main' if matrix_mautrix_signal_version == 'latest' else matrix_mautrix_signal_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/signal
-matrix_mautrix_signal_version: v0.7.3
+matrix_mautrix_signal_version: v0.7.4
 
 # See: https://mau.dev/mautrix/signal/container_registry
 matrix_mautrix_signal_docker_image: "{{ matrix_mautrix_signal_docker_image_name_prefix }}mautrix/signal:{{ matrix_mautrix_signal_docker_image_tag }}"

roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml

@@ -9,7 +9,7 @@ matrix_mautrix_slack_container_image_self_build_repo: "https://mau.dev/mautrix/s
 matrix_mautrix_slack_container_image_self_build_branch: "{{ 'main' if matrix_mautrix_slack_version == 'latest' else matrix_mautrix_slack_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/slack
-matrix_mautrix_slack_version: v0.1.3
+matrix_mautrix_slack_version: v0.1.4
 # See: https://mau.dev/mautrix/slack/container_registry
 matrix_mautrix_slack_docker_image: "{{ matrix_mautrix_slack_docker_image_name_prefix }}mautrix/slack:{{ matrix_mautrix_slack_version }}"
 matrix_mautrix_slack_docker_image_name_prefix: "{{ 'localhost/' if matrix_mautrix_slack_container_image_self_build else 'dock.mau.dev/' }}"

roles/custom/matrix-bridge-mautrix-telegram/defaults/main.yml

@@ -136,6 +136,8 @@ matrix_mautrix_telegram_systemd_wanted_services_list: []
 matrix_mautrix_telegram_appservice_token: ''
 matrix_mautrix_telegram_homeserver_token: ''
 
+matrix_mautrix_telegram_provisioning_shared_secret: disable
+
 # Whether or not metrics endpoint should be enabled.
 # Enabling them is usually enough for a local (in-container) Prometheus to consume them.
 # If metrics need to be consumed by another (external) Prometheus server, consider exposing them via `matrix_mautrix_telegram_metrics_proxying_enabled`.

roles/custom/matrix-bridge-mautrix-telegram/templates/config.yaml.j2

@@ -71,7 +71,7 @@ appservice:
         prefix: /_matrix/provision/v1
         # The shared secret to authorize users of the API.
         # Set to "generate" to generate and save a new token.
-        shared_secret: generate
+        shared_secret: {{ matrix_mautrix_telegram_provisioning_shared_secret | to_json }}
 
     # The unique ID of this appservice.
     id: telegram
@@ -122,7 +122,7 @@ bridge:
     # Default: {displayname} (Telegram)
     displayname_template: {{ matrix_mautrix_telegram_displayname_template|to_json }}
 
-    # Set the preferred order of user identifiers which to use in the Matrix puppet display name.
+    # Set the preferred order of user IDs which to use in the Matrix puppet display name.
     # In the (hopefully unlikely) scenario that none of the given keys are found, the numeric user
     # ID is used.
     #
@@ -450,8 +450,8 @@ bridge:
     #
     # Available variables:
     #   $sender_displayname - The display name of the sender (e.g. Example User)
-    #   $sender_username    - The username (Matrix ID localpart) of the sender (e.g. exampleuser)
-    #   $sender_mxid        - The Matrix ID of the sender (e.g. @exampleuser:example.com)
+    #   $sender_username    - The username (Matrix ID localpart) of the sender (e.g. alice)
+    #   $sender_mxid        - The Matrix ID of the sender (e.g. @alice:example.com)
     #   $distinguisher      - A random string from the options in the relay_user_distinguishers array.
     #   $message            - The message content
     message_formats:

roles/custom/matrix-bridge-mautrix-twitter/defaults/main.yml

@@ -9,7 +9,7 @@ matrix_mautrix_twitter_container_image_self_build_repo: "https://github.com/maut
 matrix_mautrix_twitter_container_image_self_build_repo_version: "{{ 'master' if matrix_mautrix_twitter_version == 'latest' else matrix_mautrix_twitter_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/twitter
-matrix_mautrix_twitter_version: v0.1.8
+matrix_mautrix_twitter_version: v0.2.0
 # See: https://mau.dev/tulir/mautrix-twitter/container_registry
 matrix_mautrix_twitter_docker_image: "{{ matrix_mautrix_twitter_docker_image_name_prefix }}mautrix/twitter:{{ matrix_mautrix_twitter_version }}"
 matrix_mautrix_twitter_docker_image_name_prefix: "{{ 'localhost/' if matrix_mautrix_twitter_container_image_self_build else 'dock.mau.dev/' }}"
@@ -24,7 +24,10 @@ matrix_mautrix_twitter_homeserver_address: ""
 matrix_mautrix_twitter_homeserver_domain: '{{ matrix_domain }}'
 matrix_mautrix_twitter_appservice_address: 'http://matrix-mautrix-twitter:29327'
 
-matrix_mautrix_twitter_command_prefix: "!tw"
+# A public address that external services can use to reach this appservice.
+matrix_mautrix_twitter_appservice_public_address: ''
+
+matrix_mautrix_twitter_bridge_command_prefix: "!tw"
 
 matrix_mautrix_twitter_bridge_permissions: |
   {{
@@ -84,7 +87,7 @@ matrix_mautrix_twitter_homeserver_token: ''
 
 # Whether or not created rooms should have federation enabled.
 # If false, created portal rooms will never be federated.
-matrix_mautrix_twitter_federate_rooms: true
+matrix_mautrix_twitter_matrix_federate_rooms: true
 
 # Database-related configuration fields.
 #
@@ -97,23 +100,38 @@ matrix_mautrix_twitter_database_password: 'some-password'
 matrix_mautrix_twitter_database_hostname: ''
 matrix_mautrix_twitter_database_port: 5432
 matrix_mautrix_twitter_database_name: 'matrix_mautrix_twitter'
+matrix_mautrix_twitter_database_sslmode: disable
 
-matrix_mautrix_twitter_database_connection_string: 'postgres://{{ matrix_mautrix_twitter_database_username }}:{{ matrix_mautrix_twitter_database_password }}@{{ matrix_mautrix_twitter_database_hostname }}:{{ matrix_mautrix_twitter_database_port }}/{{ matrix_mautrix_twitter_database_name }}'
+matrix_mautrix_twitter_database_connection_string: 'postgres://{{ matrix_mautrix_twitter_database_username }}:{{ matrix_mautrix_twitter_database_password }}@{{ matrix_mautrix_twitter_database_hostname }}:{{ matrix_mautrix_twitter_database_port }}/{{ matrix_mautrix_twitter_database_name }}?sslmode={{ matrix_mautrix_twitter_database_sslmode }}'
 
-matrix_mautrix_twitter_appservice_database: "{{
+matrix_mautrix_twitter_database_uri: "{{
 	{
 		'postgres': matrix_mautrix_twitter_database_connection_string,
 	}[matrix_mautrix_twitter_database_engine]
 }}"
 
-matrix_mautrix_twitter_bridge_login_shared_secret_map: "{{ matrix_mautrix_twitter_bridge_login_shared_secret_map_auto | combine(matrix_mautrix_twitter_bridge_login_shared_secret_map_custom) }}"
-matrix_mautrix_twitter_bridge_login_shared_secret_map_auto: {}
-matrix_mautrix_twitter_bridge_login_shared_secret_map_custom: {}
+matrix_mautrix_twitter_double_puppet_secrets: "{{ matrix_mautrix_twitter_double_puppet_secrets_auto | combine(matrix_mautrix_twitter_double_puppet_secrets_custom) }}"
+matrix_mautrix_twitter_double_puppet_secrets_auto: {}
+matrix_mautrix_twitter_double_puppet_secrets_custom: {}
 
 matrix_mautrix_twitter_appservice_bot_username: twitterbot
+matrix_mautrix_twitter_appservice_bot_displayname: Twitter bridge bot
+matrix_mautrix_twitter_appservice_bot_avatar: mxc://maunium.net/HVHcnusJkQcpVcsVGZRELLCn
 
-# Specifies the default log level for all bridge loggers.
-matrix_mautrix_twitter_logging_level: WARNING
+matrix_mautrix_twitter_backfill_enabled: true
+# Maximum number of messages to backfill in empty rooms
+matrix_mautrix_twitter_backfill_max_initial_messages: 50
+
+# Maximum number of missed messages to backfill after bridge restarts
+matrix_mautrix_twitter_backfill_max_catchup_messages: 500
+
+# Shared secret for authentication of provisioning API requests.
+# If set to "disable", the provisioning API will be disabled.
+matrix_mautrix_twitter_provisioning_shared_secret: disable
+
+# Minimum severity of journal log messages.
+# Options: debug, info, warn, error, fatal
+matrix_mautrix_twitter_logging_level: 'warn'
 
 # Whether or not metrics endpoint should be enabled.
 # Enabling them is usually enough for a local (in-container) Prometheus to consume them.
@@ -162,10 +180,15 @@ matrix_mautrix_twitter_registration_yaml: |
   sender_localpart: _bot_{{ matrix_mautrix_twitter_appservice_bot_username }}
   rate_limited: false
   de.sorunome.msc2409.push_ephemeral: true
+  receive_ephemeral: true
 
 matrix_mautrix_twitter_registration: "{{ matrix_mautrix_twitter_registration_yaml | from_yaml }}"
 
 # Enable End-to-bridge encryption
 matrix_mautrix_twitter_bridge_encryption_allow: "{{ matrix_bridges_encryption_enabled }}"
 matrix_mautrix_twitter_bridge_encryption_default: "{{ matrix_bridges_encryption_default }}"
+matrix_mautrix_twitter_bridge_encryption_require: false
+matrix_mautrix_twitter_bridge_encryption_appservice: false
 matrix_mautrix_twitter_bridge_encryption_key_sharing_allow: "{{ matrix_mautrix_twitter_bridge_encryption_allow }}"
+# This pickle key value is compatible with the old mautrix-twitter bridge (before bridgev2).
+matrix_mautrix_twitter_bridge_encryption_pickle_key: mautrix.bridge.e2ee

roles/custom/matrix-bridge-mautrix-twitter/tasks/validate_config.yml

@@ -22,3 +22,9 @@
   when: "item.old in vars"
   with_items:
     - {'old': 'matrix_mautrix_twitter_login_shared_secret', 'new': '<removed>'}
+    - {'old': 'matrix_mautrix_twitter_appservice_database', 'new': 'matrix_mautrix_twitter_database_uri'}
+    - {'old': 'matrix_mautrix_twitter_bridge_login_shared_secret_map', 'new': 'matrix_mautrix_twitter_double_puppet_secrets'}
+    - {'old': 'matrix_mautrix_twitter_bridge_login_shared_secret_map_auto', 'new': 'matrix_mautrix_twitter_double_puppet_secrets_auto'}
+    - {'old': 'matrix_mautrix_twitter_bridge_login_shared_secret_map_custom', 'new': 'matrix_mautrix_twitter_double_puppet_secrets_custom'}
+    - {'old': 'matrix_mautrix_twitter_federate_rooms', 'new': 'matrix_mautrix_twitter_matrix_federate_rooms'}
+    - {'old': 'matrix_mautrix_twitter_command_prefix', 'new': 'matrix_mautrix_twitter_bridge_command_prefix'}

roles/custom/matrix-bridge-mautrix-twitter/templates/config.yaml.j2

@@ -1,202 +1,428 @@
 #jinja2: lstrip_blocks: "True"
-# Homeserver details
-homeserver:
-    # The address that this appservice can use to connect to the homeserver.
-    address: {{ matrix_mautrix_twitter_homeserver_address }}
-    # The domain of the homeserver (for MXIDs, etc).
-    domain: {{ matrix_mautrix_twitter_homeserver_domain }}
-    # Whether or not to verify the SSL certificate of the homeserver.
-    # Only applies if address starts with https://
-    verify_ssl: true
-    asmux: false
+# Network-specific config options
+network:
+    # Proxy to use for all Twitter connections.
+    proxy: null
+    # Alternative to proxy: an HTTP endpoint that returns the proxy URL to use for Twitter connections.
+    get_proxy_url: null
 
-# Application service host/registration related details
-# Changing these values requires regeneration of the registration.
-appservice:
-    # The address that the homeserver can use to connect to this appservice.
-    address: {{ matrix_mautrix_twitter_appservice_address }}
-    # When using https:// the TLS certificate and key files for the address.
-    tls_cert: false
-    tls_key: false
-
-    # The hostname and port where this appservice should listen.
-    hostname: 0.0.0.0
-    port: 29327
-    # The maximum body size of appservice API requests (from the homeserver) in mebibytes
-    # Usually 1 is enough, but on high-traffic bridges you might need to increase this to avoid 413s
-    max_body_size: 1
-
-    # The full URI to the database. Only Postgres is currently supported.
-    database: {{ matrix_mautrix_twitter_appservice_database|to_json }}
-    # Additional arguments for asyncpg.create_pool()
-    # https://magicstack.github.io/asyncpg/current/api/index.html#asyncpg.pool.create_pool
-    database_opts:
-        min_size: 5
-        max_size: 10
-
-    # Provisioning API part of the web server for automated portal creation and fetching information.
-    # Used by things like mautrix-manager (https://github.com/tulir/mautrix-manager).
-    provisioning:
-        # Whether or not the provisioning API should be enabled.
-        enabled: true
-        # The prefix to use in the provisioning API endpoints.
-        prefix: /_matrix/provision/v1
-        # The shared secret to authorize users of the API.
-        # Set to "generate" to generate and save a new token.
-        shared_secret: generate
-
-    # The unique ID of this appservice.
-    id: twitter
-    # Username of the appservice bot.
-    bot_username: {{ matrix_mautrix_twitter_appservice_bot_username|to_json }}
-    # Display name and avatar for bot. Set to "remove" to remove display name/avatar, leave empty
-    # to leave display name/avatar as-is.
-    bot_displayname: Twitter bridge bot
-    bot_avatar: mxc://maunium.net/HVHcnusJkQcpVcsVGZRELLCn
-
-    # Whether or not to receive ephemeral events via appservice transactions.
-    # Requires MSC2409 support (i.e. Synapse 1.22+).
-    # You should disable bridge -> sync_with_custom_puppets when this is enabled.
-    ephemeral_events: false
-
-    # Authentication tokens for AS <-> HS communication. Autogenerated; do not modify.
-    as_token: "{{ matrix_mautrix_twitter_appservice_token }}"
-    hs_token: "{{ matrix_mautrix_twitter_homeserver_token }}"
-
-# Prometheus telemetry config. Requires prometheus-client to be installed.
-metrics:
-    enabled: {{ matrix_mautrix_twitter_metrics_enabled | to_json }}
-    listen_port: 8000
-
-# Bridge config
-bridge:
-    # Localpart template of MXIDs for Twitter users.
-    # {userid} is replaced with the user ID of the Twitter user.
-    username_template: "twitter_{userid}"
     # Displayname template for Twitter users.
-    # {displayname} is replaced with the display name of the Twitter user.
-    # {username} is replaced with the username of the Twitter user.
-    displayname_template: "{displayname} (Twitter)"
+    # {% raw %}
+    # {{ .DisplayName }} is replaced with the display name of the Twitter user.
+    # {{ .Username }} is replaced with the username of the Twitter user.
+    # {% endraw %}
+    displayname_template: "{% raw %}{{ .DisplayName }}{% endraw %} (Twitter)"
 
-    # Maximum length of displayname
-    displayname_max_length: 100
+    # Maximum number of conversations to sync on startup
+    conversation_sync_limit: 20
 
-    # Number of conversations to sync (and create portals for) on login.
-    # Set 0 to disable automatic syncing.
-    initial_conversation_sync: 10
-    # Whether or not to use /sync to get read receipts and typing notifications
-    # when double puppeting is enabled
-    sync_with_custom_puppets: true
-    # Whether or not to update the m.direct account data event when double puppeting is enabled.
-    # Note that updating the m.direct event is not atomic (except with mautrix-asmux)
-    # and is therefore prone to race conditions.
-    sync_direct_chat_list: false
-    # Allow using double puppeting from any server with a valid client .well-known file.
-    double_puppet_allow_discovery: false
-    # Servers to allow double puppeting from, even if double_puppet_allow_discovery is false.
-    double_puppet_server_map: {}
-    # Shared secret for https://github.com/devture/matrix-synapse-shared-secret-auth
-    #
-    # If set, custom puppets will be enabled automatically for local users
-    # instead of users having to find an access token and run `login-matrix`
-    # manually.
-    # If using this for other servers than the bridge's server,
-    # you must also set the URL in the double_puppet_server_map.
-    login_shared_secret_map: {{ matrix_mautrix_twitter_bridge_login_shared_secret_map|to_json }}
-    # Whether or not created rooms should have federation enabled.
-    # If false, created portal rooms will never be federated.
-    federate_rooms: {{ matrix_mautrix_twitter_federate_rooms|to_json }}
-    # Settings for backfilling messages from Twitter.
-    #
-    # Missed message backfilling is currently based on receiving them from the Twitter polling API,
-    # rather than manually asking for messages in each conversation. Due to this, there's no way to
-    # set a limit for missed message backfilling.
-    backfill:
-        # Whether or not the Twitter users of logged in Matrix users should be
-        # invited to private chats when backfilling history from Twitter. This is
-        # usually needed to prevent rate limits and to allow timestamp massaging.
-        invite_own_puppet: true
-        # Maximum number of messages to backfill initially.
-        # Set to 0 to disable backfilling when creating portal.
-        initial_limit: 0
-        # If using double puppeting, should notifications be disabled
-        # while the initial backfill is in progress?
-        disable_notifications: true
-    # End-to-bridge encryption support options. You must install the e2be optional dependency for
-    # this to work. See https://github.com/tulir/mautrix-telegram/wiki/End‐to‐bridge-encryption
-    encryption:
-        # Allow encryption, work in group chat rooms with e2ee enabled
-        allow: {{ matrix_mautrix_twitter_bridge_encryption_allow|to_json }}
-        # Default to encryption, force-enable encryption in all portals the bridge creates
-        # This will cause the bridge bot to be in private chats for the encryption to work properly.
-        default: {{ matrix_mautrix_twitter_bridge_encryption_default|to_json }}
-        # Options for automatic key sharing.
-        key_sharing:
-            # Enable key sharing? If enabled, key requests for rooms where users are in will be fulfilled.
-            # You must use a client that supports requesting keys from other users to use this feature.
-            allow: {{ matrix_mautrix_twitter_bridge_encryption_key_sharing_allow|to_json }}
-            # Require the requesting device to have a valid cross-signing signature?
-            # This doesn't require that the bridge has verified the device, only that the user has verified it.
-            # Not yet implemented.
-            require_cross_signing: false
-            # Require devices to be verified by the bridge?
-            # Verification by the bridge is not yet implemented.
-            require_verification: true
-    # Whether or not to explicitly set the avatar and room name for private
-    # chat portal rooms. This will be implicitly enabled if encryption.default is true.
-    private_chat_portal_meta: false
-    # Whether or not the bridge should send a read receipt from the bridge bot when a message has
-    # been sent to Twitter.
-    delivery_receipts: false
-    # Whether or not delivery errors should be reported as messages in the Matrix room.
-    delivery_error_reports: true
-    # Whether or not non-fatal polling errors should send notices to the notice room.
-    temporary_disconnect_notices: true
-    # Number of seconds to sleep more than the previous error when a polling error occurs.
-    # Growth is capped at 15 minutes.
-    error_sleep: 5
-    # Maximum number of polling errors before giving up. Set to -1 to retry forever.
-    max_poll_errors: 12
-    # Set this to true to tell the bridge to re-send m.bridge events to all rooms on the next run.
-    # This field will automatically be changed back to false after it,
-    # except if the config file is not writable.
+
+# Config options that affect the central bridge module.
+bridge:
+    # The prefix for commands. Only required in non-management rooms.
+    command_prefix: {{ matrix_mautrix_twitter_bridge_command_prefix | to_json }}
+    # Should the bridge create a space for each login containing the rooms that account is in?
+    personal_filtering_spaces: true
+    # Whether the bridge should set names and avatars explicitly for DM portals.
+    # This is only necessary when using clients that don't support MSC4171.
+    private_chat_portal_meta: true
+    # Should events be handled asynchronously within portal rooms?
+    # If true, events may end up being out of order, but slow events won't block other ones.
+    # This is not yet safe to use.
+    async_events: false
+    # Should every user have their own portals rather than sharing them?
+    # By default, users who are in the same group on the remote network will be
+    # in the same Matrix room bridged to that group. If this is set to true,
+    # every user will get their own Matrix room instead.
+    split_portals: false
+    # Should the bridge resend `m.bridge` events to all portals on startup?
     resend_bridge_info: false
 
-    # The prefix for commands. Only required in non-management rooms.
-    command_prefix: "{{ matrix_mautrix_twitter_command_prefix }}"
+    # Should leaving Matrix rooms be bridged as leaving groups on the remote network?
+    bridge_matrix_leave: false
+    # Should room tags only be synced when creating the portal? Tags mean things like favorite/pin and archive/low priority.
+    # Tags currently can't be synced back to the remote network, so a continuous sync means tagging from Matrix will be undone.
+    tag_only_on_create: true
+    # List of tags to allow bridging. If empty, no tags will be bridged.
+    only_bridge_tags: [m.favourite, m.lowpriority]
+    # Should room mute status only be synced when creating the portal?
+    # Like tags, mutes can't currently be synced back to the remote network.
+    mute_only_on_create: true
+
+    # What should be done to portal rooms when a user logs out or is logged out?
+    # Permitted values:
+    #   nothing - Do nothing, let the user stay in the portals
+    #   kick - Remove the user from the portal rooms, but don't delete them
+    #   unbridge - Remove all ghosts in the room and disassociate it from the remote chat
+    #   delete - Remove all ghosts and users from the room (i.e. delete it)
+    cleanup_on_logout:
+        # Should cleanup on logout be enabled at all?
+        enabled: false
+        # Settings for manual logouts (explicitly initiated by the Matrix user)
+        manual:
+            # Action for private portals which will never be shared with other Matrix users.
+            private: nothing
+            # Action for portals with a relay user configured.
+            relayed: nothing
+            # Action for portals which may be shared, but don't currently have any other Matrix users.
+            shared_no_users: nothing
+            # Action for portals which have other logged-in Matrix users.
+            shared_has_users: nothing
+        # Settings for credentials being invalidated (initiated by the remote network, possibly through user action).
+        # Keys have the same meanings as in the manual section.
+        bad_credentials:
+            private: nothing
+            relayed: nothing
+            shared_no_users: nothing
+            shared_has_users: nothing
+
+    # Settings for relay mode
+    relay:
+        # Whether relay mode should be allowed. If allowed, the set-relay command can be used to turn any
+        # authenticated user into a relaybot for that chat.
+        enabled: false
+        # Should only admins be allowed to set themselves as relay users?
+        # If true, non-admins can only set users listed in default_relays as relays in a room.
+        admin_only: true
+        # List of user login IDs which anyone can set as a relay, as long as the relay user is in the room.
+        default_relays: []
+        # The formats to use when sending messages via the relaybot.
+        # Available variables:
+        #   .Sender.UserID - The Matrix user ID of the sender.
+        #   .Sender.Displayname - The display name of the sender (if set).
+        #   .Sender.RequiresDisambiguation - Whether the sender's name may be confused with the name of another user in the room.
+        #   .Sender.DisambiguatedName - The disambiguated name of the sender. This will be the displayname if set,
+        #                               plus the user ID in parentheses if the displayname is not unique.
+        #                               If the displayname is not set, this is just the user ID.
+        #   .Message - The `formatted_body` field of the message.
+        #   .Caption - The `formatted_body` field of the message, if it's a caption. Otherwise an empty string.
+        #   .FileName - The name of the file being sent.
+        message_formats:
+            m.text: "{% raw %}<b>{{ .Sender.DisambiguatedName }}</b>: {{ .Message }}{% endraw %}"
+            m.notice: "{% raw %}<b>{{ .Sender.DisambiguatedName }}</b>: {{ .Message }}{% endraw %}"
+            m.emote: "{% raw %}* <b>{{ .Sender.DisambiguatedName }}</b> {{ .Message }}{% endraw %}"
+            m.file: "{% raw %}<b>{{ .Sender.DisambiguatedName }}</b> sent a file{{ if .Caption }}: {{ .Caption }}{{ end }}{% endraw %}"
+            m.image: "{% raw %}<b>{{ .Sender.DisambiguatedName }}</b> sent an image{{ if .Caption }}: {{ .Caption }}{{ end }}{% endraw %}"
+            m.audio: "{% raw %}<b>{{ .Sender.DisambiguatedName }}</b> sent an audio file{{ if .Caption }}: {{ .Caption }}{{ end }}{% endraw %}"
+            m.video: "{% raw %}<b>{{ .Sender.DisambiguatedName }}</b> sent a video{{ if .Caption }}: {{ .Caption }}{{ end }}{% endraw %}"
+            m.location: "{% raw %}<b>{{ .Sender.DisambiguatedName }}</b> sent a location{{ if .Caption }}: {{ .Caption }}{{ end }}{% endraw %}"
+        # For networks that support per-message displaynames (i.e. Slack and Discord), the template for those names.
+        # This has all the Sender variables available under message_formats (but without the .Sender prefix).
+        # Note that you need to manually remove the displayname from message_formats above.
+        displayname_format: "{% raw %}{{ .DisambiguatedName }}{% endraw %}"
 
     # Permissions for using the bridge.
     # Permitted values:
-    #       user - Use the bridge with puppeting.
-    #      admin - Use and administrate the bridge.
+    #    relay - Talk through the relaybot (if enabled), no access otherwise
+    # commands - Access to use commands in the bridge, but not login.
+    #     user - Access to use the bridge with puppeting.
+    #    admin - Full access, user level with some additional administration tools.
     # Permitted keys:
     #        * - All Matrix users
     #   domain - All users on that homeserver
     #     mxid - Specific user
-    permissions: {{ matrix_mautrix_twitter_bridge_permissions|to_json }}
+    permissions: {{ matrix_mautrix_twitter_bridge_permissions | to_json }}
 
+# Config for the bridge's database.
+database:
+    # The database type. "sqlite3-fk-wal" and "postgres" are supported.
+    type: postgres
+    # The database URI.
+    #   SQLite: A raw file path is supported, but `file:<path>?_txlock=immediate` is recommended.
+    #           https://github.com/mattn/go-sqlite3#connection-string
+    #   Postgres: Connection string. For example, postgres://user:password@host/database?sslmode=disable
+    #             To connect via Unix socket, use something like postgres:///dbname?host=/var/run/postgresql
+    uri: {{ matrix_mautrix_twitter_database_uri | to_json }}
+    # Maximum number of connections.
+    max_open_conns: 5
+    max_idle_conns: 1
+    # Maximum connection idle time and lifetime before they're closed. Disabled if null.
+    # Parsed with https://pkg.go.dev/time#ParseDuration
+    max_conn_idle_time: null
+    max_conn_lifetime: null
 
-# Python logging configuration.
+# Homeserver details.
+homeserver:
+    # The address that this appservice can use to connect to the homeserver.
+    # Local addresses without HTTPS are generally recommended when the bridge is running on the same machine,
+    # but https also works if they run on different machines.
+    address: {{ matrix_mautrix_twitter_homeserver_address | to_json }}
+    # The domain of the homeserver (also known as server_name, used for MXIDs, etc).
+    domain: {{ matrix_mautrix_twitter_homeserver_domain | to_json }}
+
+    # What software is the homeserver running?
+    # Standard Matrix homeservers like Synapse, Dendrite and Conduit should just use "standard" here.
+    software: standard
+    # The URL to push real-time bridge status to.
+    # If set, the bridge will make POST requests to this URL whenever a user's remote network connection state changes.
+    # The bridge will use the appservice as_token to authorize requests.
+    status_endpoint:
+    # Endpoint for reporting per-message status.
+    # If set, the bridge will make POST requests to this URL when processing a message from Matrix.
+    # It will make one request when receiving the message (step BRIDGE), one after decrypting if applicable
+    # (step DECRYPTED) and one after sending to the remote network (step REMOTE). Errors will also be reported.
+    # The bridge will use the appservice as_token to authorize requests.
+    message_send_checkpoint_endpoint:
+    # Does the homeserver support https://github.com/matrix-org/matrix-spec-proposals/pull/2246?
+    async_media: false
+
+    # Should the bridge use a websocket for connecting to the homeserver?
+    # The server side is currently not documented anywhere and is only implemented by mautrix-wsproxy,
+    # mautrix-asmux (deprecated), and hungryserv (proprietary).
+    websocket: false
+    # How often should the websocket be pinged? Pinging will be disabled if this is zero.
+    ping_interval_seconds: 0
+
+# Application service host/registration related details.
+# Changing these values requires regeneration of the registration (except when noted otherwise)
+appservice:
+    # The address that the homeserver can use to connect to this appservice.
+    # Like the homeserver address, a local non-https address is recommended when the bridge is on the same machine.
+    # If the bridge is elsewhere, you must secure the connection yourself (e.g. with https or wireguard)
+    # If you want to use https, you need to use a reverse proxy. The bridge does not have TLS support built in.
+    address: {{ matrix_mautrix_twitter_appservice_address | to_json }}
+    # A public address that external services can use to reach this appservice.
+    # This is only needed for things like public media. A reverse proxy is generally necessary when using this field.
+    # This value doesn't affect the registration file.
+    public_address: {{ matrix_mautrix_twitter_appservice_public_address | to_json }}
+
+    # The hostname and port where this appservice should listen.
+    # For Docker, you generally have to change the hostname to 0.0.0.0.
+    hostname: 0.0.0.0
+    port: 29327
+
+    # The unique ID of this appservice.
+    id: twitter
+    # Appservice bot details.
+    bot:
+        # Username of the appservice bot.
+        username: {{ matrix_mautrix_twitter_appservice_bot_username | to_json }}
+        # Display name and avatar for bot. Set to "remove" to remove display name/avatar, leave empty
+        # to leave display name/avatar as-is.
+        displayname: {{ matrix_mautrix_twitter_appservice_bot_displayname | to_json }}
+        avatar: {{ matrix_mautrix_twitter_appservice_bot_avatar | to_json }}
+
+    # Whether to receive ephemeral events via appservice transactions.
+    ephemeral_events: true
+    # Should incoming events be handled asynchronously?
+    # This may be necessary for large public instances with lots of messages going through.
+    # However, messages will not be guaranteed to be bridged in the same order they were sent in.
+    # This value doesn't affect the registration file.
+    async_transactions: false
+    # Whether to use MSC4190 instead of appservice login to create the bridge bot device.
+    # Requires the homeserver to support MSC4190 and the device masquerading parts of MSC3202.
+    # Only relevant when using end-to-bridge encryption, required when using encryption with next-gen auth (MSC3861).
+    msc4190: false
+
+    # Authentication tokens for AS <-> HS communication. Autogenerated; do not modify.
+    as_token: {{ matrix_mautrix_twitter_appservice_token | to_json }}
+    hs_token: {{ matrix_mautrix_twitter_homeserver_token | to_json }}
+
+    # Localpart template of MXIDs for remote users.
+    # {% raw %}{{.}}{% endraw %} is replaced with the internal ID of the user.
+    username_template: "{% raw %}twitter_{{.}}{% endraw %}"
+
+# Config options that affect the Matrix connector of the bridge.
+matrix:
+    # Whether the bridge should send the message status as a custom com.beeper.message_send_status event.
+    message_status_events: false
+    # Whether the bridge should send a read receipt after successfully bridging a message.
+    delivery_receipts: false
+    # Whether the bridge should send error notices via m.notice events when a message fails to bridge.
+    message_error_notices: true
+    # Whether the bridge should update the m.direct account data event when double puppeting is enabled.
+    sync_direct_chat_list: true
+    # Whether created rooms should have federation enabled. If false, created portal rooms
+    # will never be federated. Changing this option requires recreating rooms.
+    federate_rooms: {{ matrix_mautrix_twitter_matrix_federate_rooms | to_json }}
+    # The threshold as bytes after which the bridge should roundtrip uploads via the disk
+    # rather than keeping the whole file in memory.
+    upload_file_threshold: 5242880
+
+# Segment-compatible analytics endpoint for tracking some events, like provisioning API login and encryption errors.
+analytics:
+    # API key to send with tracking requests. Tracking is disabled if this is null.
+    token: null
+    # Address to send tracking requests to.
+    url: https://api.segment.io/v1/track
+    # Optional user ID for tracking events. If null, defaults to using Matrix user ID.
+    user_id: null
+
+# Settings for provisioning API
+provisioning:
+    # Prefix for the provisioning API paths.
+    prefix: /_matrix/provision
+    # Shared secret for authentication. If set to "generate" or null, a random secret will be generated,
+    # or if set to "disable", the provisioning API will be disabled.
+    shared_secret: {{ matrix_mautrix_twitter_provisioning_shared_secret | to_json }}
+    # Whether to allow provisioning API requests to be authed using Matrix access tokens.
+    # This follows the same rules as double puppeting to determine which server to contact to check the token,
+    # which means that by default, it only works for users on the same server as the bridge.
+    allow_matrix_auth: true
+    # Enable debug API at /debug with provisioning authentication.
+    debug_endpoints: false
+
+# Some networks require publicly accessible media download links (e.g. for user avatars when using Discord webhooks).
+# These settings control whether the bridge will provide such public media access.
+public_media:
+    # Should public media be enabled at all?
+    # The public_address field under the appservice section MUST be set when enabling public media.
+    enabled: false
+    # A key for signing public media URLs.
+    # If set to "generate", a random key will be generated.
+    signing_key: ""
+    # Number of seconds that public media URLs are valid for.
+    # If set to 0, URLs will never expire.
+    expiry: 0
+    # Length of hash to use for public media URLs. Must be between 0 and 32.
+    hash_length: 32
+
+# Settings for converting remote media to custom mxc:// URIs instead of reuploading.
+# More details can be found at https://docs.mau.fi/bridges/go/discord/direct-media.html
+direct_media:
+    # Should custom mxc:// URIs be used instead of reuploading media?
+    enabled: false
+    # The server name to use for the custom mxc:// URIs.
+    # This server name will effectively be a real Matrix server, it just won't implement anything other than media.
+    # You must either set up .well-known delegation from this domain to the bridge, or proxy the domain directly to the bridge.
+    server_name: discord-media.example.com
+    # Optionally a custom .well-known response. This defaults to `server_name:443`
+    well_known_response:
+    # Optionally specify a custom prefix for the media ID part of the MXC URI.
+    media_id_prefix:
+    # If the remote network supports media downloads over HTTP, then the bridge will use MSC3860/MSC3916
+    # media download redirects if the requester supports it. Optionally, you can force redirects
+    # and not allow proxying at all by setting this to false.
+    # This option does nothing if the remote network does not support media downloads over HTTP.
+    allow_proxy: true
+    # Matrix server signing key to make the federation tester pass, same format as synapse's .signing.key file.
+    # This key is also used to sign the mxc:// URIs to ensure only the bridge can generate them.
+    server_key: ""
+
+# Settings for backfilling messages.
+# Note that the exact way settings are applied depends on the network connector.
+# See https://docs.mau.fi/bridges/general/backfill.html for more details.
+backfill:
+    # Whether to do backfilling at all.
+    enabled: {{ matrix_mautrix_twitter_backfill_enabled | to_json }}
+    # Maximum number of messages to backfill in empty rooms.
+    max_initial_messages: {{ matrix_mautrix_twitter_backfill_max_initial_messages | to_json }}
+    # Maximum number of missed messages to backfill after bridge restarts.
+    max_catchup_messages: {{ matrix_mautrix_twitter_backfill_max_catchup_messages | to_json }}
+    # If a backfilled chat is older than this number of hours,
+    # mark it as read even if it's unread on the remote network.
+    unread_hours_threshold: 720
+    # Settings for backfilling threads within other backfills.
+    threads:
+        # Maximum number of messages to backfill in a new thread.
+        max_initial_messages: 50
+    # Settings for the backwards backfill queue. This only applies when connecting to
+    # Beeper as standard Matrix servers don't support inserting messages into history.
+    queue:
+        # Should the backfill queue be enabled?
+        enabled: false
+        # Number of messages to backfill in one batch.
+        batch_size: 100
+        # Delay between batches in seconds.
+        batch_delay: 20
+        # Maximum number of batches to backfill per portal.
+        # If set to -1, all available messages will be backfilled.
+        max_batches: -1
+        # Optional network-specific overrides for max batches.
+        # Interpretation of this field depends on the network connector.
+        max_batches_override: {}
+
+# Settings for enabling double puppeting
+double_puppet:
+    # Servers to always allow double puppeting from.
+    # This is only for other servers and should NOT contain the server the bridge is on.
+    servers: {}
+    # Whether to allow client API URL discovery for other servers. When using this option,
+    # users on other servers can use double puppeting even if their server URLs aren't
+    # explicitly added to the servers map above.
+    allow_discovery: false
+    # Shared secrets for automatic double puppeting.
+    # See https://docs.mau.fi/bridges/general/double-puppeting.html for instructions.
+    secrets: {{ matrix_mautrix_twitter_double_puppet_secrets | to_json }}
+
+# End-to-bridge encryption support options.
 #
-# See section 16.7.2 of the Python documentation for more info:
-# https://docs.python.org/3.6/library/logging.config.html#configuration-dictionary-schema
+# See https://docs.mau.fi/bridges/general/end-to-bridge-encryption.html for more info.
+encryption:
+    # Whether to enable encryption at all. If false, the bridge will not function in encrypted rooms.
+    allow: {{ matrix_mautrix_twitter_bridge_encryption_allow | to_json }}
+    # Whether to force-enable encryption in all bridged rooms.
+    default: {{ matrix_mautrix_twitter_bridge_encryption_default | to_json }}
+    # Whether to require all messages to be encrypted and drop any unencrypted messages.
+    require: {{ matrix_mautrix_twitter_bridge_encryption_require | to_json }}
+    # Whether to use MSC2409/MSC3202 instead of /sync long polling for receiving encryption-related data.
+    # This option is not yet compatible with standard Matrix servers like Synapse and should not be used.
+    appservice: {{ matrix_mautrix_twitter_bridge_encryption_appservice | to_json }}
+    # Enable key sharing? If enabled, key requests for rooms where users are in will be fulfilled.
+    # You must use a client that supports requesting keys from other users to use this feature.
+    allow_key_sharing: {{ matrix_mautrix_twitter_bridge_encryption_key_sharing_allow | to_json }}
+    # Pickle key for encrypting encryption keys in the bridge database.
+    # If set to generate, a random key will be generated.
+    pickle_key: {{ matrix_mautrix_twitter_bridge_encryption_pickle_key | to_json }}
+    # Options for deleting megolm sessions from the bridge.
+    delete_keys:
+        # Beeper-specific: delete outbound sessions when hungryserv confirms
+        # that the user has uploaded the key to key backup.
+        delete_outbound_on_ack: false
+        # Don't store outbound sessions in the inbound table.
+        dont_store_outbound: false
+        # Ratchet megolm sessions forward after decrypting messages.
+        ratchet_on_decrypt: false
+        # Delete fully used keys (index >= max_messages) after decrypting messages.
+        delete_fully_used_on_decrypt: false
+        # Delete previous megolm sessions from same device when receiving a new one.
+        delete_prev_on_new_session: false
+        # Delete megolm sessions received from a device when the device is deleted.
+        delete_on_device_delete: false
+        # Periodically delete megolm sessions when 2x max_age has passed since receiving the session.
+        periodically_delete_expired: false
+        # Delete inbound megolm sessions that don't have the received_at field used for
+        # automatic ratcheting and expired session deletion. This is meant as a migration
+        # to delete old keys prior to the bridge update.
+        delete_outdated_inbound: false
+    # What level of device verification should be required from users?
+    #
+    # Valid levels:
+    #   unverified - Send keys to all device in the room.
+    #   cross-signed-untrusted - Require valid cross-signing, but trust all cross-signing keys.
+    #   cross-signed-tofu - Require valid cross-signing, trust cross-signing keys on first use (and reject changes).
+    #   cross-signed-verified - Require valid cross-signing, plus a valid user signature from the bridge bot.
+    #                           Note that creating user signatures from the bridge bot is not currently possible.
+    #   verified - Require manual per-device verification
+    #              (currently only possible by modifying the `trust` column in the `crypto_device` database table).
+    verification_levels:
+        # Minimum level for which the bridge should send keys to when bridging messages from the remote network to Matrix.
+        receive: unverified
+        # Minimum level that the bridge should accept for incoming Matrix messages.
+        send: unverified
+        # Minimum level that the bridge should require for accepting key requests.
+        share: cross-signed-tofu
+    # Options for Megolm room key rotation. These options allow you to configure the m.room.encryption event content.
+    # See https://spec.matrix.org/v1.10/client-server-api/#mroomencryption for more information about that event.
+    rotation:
+        # Enable custom Megolm room key rotation settings. Note that these
+        # settings will only apply to rooms created after this option is set.
+        enable_custom: false
+        # The maximum number of milliseconds a session should be used
+        # before changing it. The Matrix spec recommends 604800000 (a week)
+        # as the default.
+        milliseconds: 604800000
+        # The maximum number of messages that should be sent with a given a
+        # session before changing it. The Matrix spec recommends 100 as the
+        # default.
+        messages: 100
+        # Disable rotating keys when a user's devices change?
+        # You should not enable this option unless you understand all the implications.
+        disable_device_change_key_rotation: false
+
+# Logging config. See https://github.com/tulir/zeroconfig for details.
 logging:
-    version: 1
-    formatters:
-        colored:
-            (): mautrix_twitter.util.ColorFormatter
-            format: "[%(asctime)s] [%(levelname)s@%(name)s] %(message)s"
-        normal:
-            format: "[%(asctime)s] [%(levelname)s@%(name)s] %(message)s"
-    handlers:
-        console:
-            class: logging.StreamHandler
-            formatter: colored
-    loggers:
-        mau:
-            level: {{ matrix_mautrix_twitter_logging_level|to_json }}
-        aiohttp:
-            level: {{ matrix_mautrix_twitter_logging_level|to_json }}
-    root:
-        level: {{ matrix_mautrix_twitter_logging_level|to_json }}
-        handlers: [console]
+    min_level: {{ matrix_mautrix_twitter_logging_level | to_json }}
+    writers:
+        - type: stdout
+          format: pretty-colored

roles/custom/matrix-bridge-mautrix-twitter/templates/systemd/matrix-mautrix-twitter.service.j2

@@ -30,7 +30,7 @@ ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
 			{{ arg }} \
 			{% endfor %}
 			{{ matrix_mautrix_twitter_docker_image }} \
-			python3 -m mautrix_twitter -c /config/config.yaml --no-update
+			/usr/bin/mautrix-twitter -c /config/config.yaml -r /config/registration.yaml --no-update
 
 {% for network in matrix_mautrix_twitter_container_additional_networks %}
 ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-mautrix-twitter

roles/custom/matrix-bridge-mautrix-whatsapp/defaults/main.yml

@@ -9,7 +9,7 @@ matrix_mautrix_whatsapp_container_image_self_build_repo: "https://mau.dev/mautri
 matrix_mautrix_whatsapp_container_image_self_build_branch: "{{ 'master' if matrix_mautrix_whatsapp_version == 'latest' else matrix_mautrix_whatsapp_version }}"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/whatsapp
-matrix_mautrix_whatsapp_version: v0.11.1
+matrix_mautrix_whatsapp_version: v0.11.2
 
 # See: https://mau.dev/mautrix/whatsapp/container_registry
 matrix_mautrix_whatsapp_docker_image: "{{ matrix_mautrix_whatsapp_docker_image_name_prefix }}mautrix/whatsapp:{{ matrix_mautrix_whatsapp_version }}"

roles/custom/matrix-bridge-mautrix-whatsapp/templates/config.yaml.j2

@@ -384,7 +384,7 @@ direct_media:
     allow_proxy: true
     # Matrix server signing key to make the federation tester pass, same format as synapse's .signing.key file.
     # This key is also used to sign the mxc:// URIs to ensure only the bridge can generate them.
-    server_key: generate
+    server_key: ""
 
 # Settings for backfilling messages.
 # Note that the exact way settings are applied depends on the network connector.

roles/custom/matrix-bridge-mx-puppet-discord/defaults/main.yml

@@ -33,14 +33,14 @@ matrix_mx_puppet_discord_appservice_address: 'http://matrix-mx-puppet-discord:{{
 
 matrix_mx_puppet_discord_bridge_mediaUrl: "{{ matrix_homeserver_url }}"  # noqa var-naming
 
-# "@user:example.com" to allow a specific user
+# "@alice:example.com" to allow a specific user
 # "@.*:example.com" to allow users on a specific homeserver
 # "@.*" to allow anyone
 matrix_mx_puppet_discord_provisioning_whitelist:
   - "@.*:{{ matrix_domain | regex_escape }}"
 
 # Leave empty to disable blacklist
-# "@user:example.com" to disallow a specific user
+# "@bob:example.com" to disallow a specific user
 # "@.*:example.com" to disallow users on a specific homeserver
 matrix_mx_puppet_discord_provisioning_blacklist: []
 

roles/custom/matrix-bridge-mx-puppet-discord/templates/config.yaml.j2

@@ -31,7 +31,7 @@ provisioning:
   # Regex of Matrix IDs allowed to use the puppet bridge
   whitelist: {{ matrix_mx_puppet_discord_provisioning_whitelist|to_json }}
     # Allow a specific user
-    #- "@user:example\\.com"
+    #- "@alice:example\\.com"
     # Allow users on a specific homeserver
     #- "@.*:example\\.com"
     # Allow anyone
@@ -39,7 +39,7 @@ provisioning:
   # Regex of Matrix IDs forbidden from using the puppet bridge
   #blacklist:
     # Disallow a specific user
-    #- "@user:example\\.com"
+    #- "@bob:example\\.com"
     # Disallow users on a specific homeserver
     #- "@.*:example\\.com"
   blacklist: {{ matrix_mx_puppet_discord_provisioning_blacklist|to_json }}

roles/custom/matrix-bridge-mx-puppet-groupme/defaults/main.yml

@@ -29,14 +29,14 @@ matrix_mx_puppet_groupme_homeserver_address: ""
 matrix_mx_puppet_groupme_homeserver_domain: '{{ matrix_domain }}'
 matrix_mx_puppet_groupme_appservice_address: 'http://matrix-mx-puppet-groupme:{{ matrix_mx_puppet_groupme_appservice_port }}'
 
-# "@user:example.com" to allow a specific user
+# "@alice:example.com" to allow a specific user
 # "@.*:example.com" to allow users on a specific homeserver
 # "@.*" to allow anyone
 matrix_mx_puppet_groupme_provisioning_whitelist:
   - "@.*:{{ matrix_domain | regex_escape }}"
 
 # Leave empty to disable blacklist
-# "@user:example.com" to disallow a specific user
+# "@bob:example.com" to disallow a specific user
 # "@.*:example.com" to disallow users on a specific homeserver
 matrix_mx_puppet_groupme_provisioning_blacklist: []
 

roles/custom/matrix-bridge-mx-puppet-groupme/templates/config.yaml.j2

@@ -31,7 +31,7 @@ provisioning:
   # Regex of Matrix IDs allowed to use the puppet bridge
   whitelist: {{ matrix_mx_puppet_groupme_provisioning_whitelist|to_json }}
     # Allow a specific user
-    #- "@user:example\\.com"
+    #- "@alice:example\\.com"
     # Allow users on a specific homeserver
     #- "@.*:example\\.com"
     # Allow anyone
@@ -39,7 +39,7 @@ provisioning:
   # Regex of Matrix IDs forbidden from using the puppet bridge
   #blacklist:
     # Disallow a specific user
-    #- "@user:example\\.com"
+    #- "@bob:example\\.com"
     # Disallow users on a specific homeserver
     #- "@.*:example\\.com"
   blacklist: {{ matrix_mx_puppet_groupme_provisioning_blacklist|to_json }}

roles/custom/matrix-bridge-mx-puppet-instagram/defaults/main.yml

@@ -24,14 +24,14 @@ matrix_mx_puppet_instagram_homeserver_address: ""
 matrix_mx_puppet_instagram_homeserver_domain: '{{ matrix_domain }}'
 matrix_mx_puppet_instagram_appservice_address: 'http://matrix-mx-puppet-instagram:{{ matrix_mx_puppet_instagram_appservice_port }}'
 
-# "@user:example.com" to allow a specific user
+# "@alice:example.com" to allow a specific user
 # "@.*:example.com" to allow users on a specific homeserver
 # "@.*" to allow anyone
 matrix_mx_puppet_instagram_provisioning_whitelist:
   - "@.*:{{ matrix_domain | regex_escape }}"
 
 # Leave empty to disable blacklist
-# "@user:example.com" to disallow a specific user
+# "@bob:example.com" to disallow a specific user
 # "@.*:example.com" to disallow users on a specific homeserver
 matrix_mx_puppet_instagram_provisioning_blacklist: []
 

roles/custom/matrix-bridge-mx-puppet-instagram/templates/config.yaml.j2

@@ -24,7 +24,7 @@ provisioning:
   # Regex of Matrix IDs allowed to use the puppet bridge
   whitelist: {{ matrix_mx_puppet_instagram_provisioning_whitelist|to_json }}
     # Allow a specific user
-    #- "@user:example\\.com"
+    #- "@alice:example\\.com"
     # Allow users on a specific homeserver
     #- "@.*:example\\.com"
     # Allow anyone
@@ -32,7 +32,7 @@ provisioning:
   # Regex of Matrix IDs forbidden from using the puppet bridge
   #blacklist:
     # Disallow a specific user
-    #- "@user:example\\.com"
+    #- "@bob:example\\.com"
     # Disallow users on a specific homeserver
     #- "@.*:example\\.com"
   blacklist: {{ matrix_mx_puppet_instagram_provisioning_blacklist|to_json }}

roles/custom/matrix-bridge-mx-puppet-slack/defaults/main.yml

@@ -42,14 +42,14 @@ matrix_mx_puppet_slack_oauth_enabled: true
 matrix_mx_puppet_slack_oauth_redirect_path: "{{ matrix_mx_puppet_slack_path_prefix }}"
 matrix_mx_puppet_slack_oauth_redirect_uri: '{{ matrix_mx_puppet_slack_scheme }}://{{ matrix_mx_puppet_slack_hostname }}{{ matrix_mx_puppet_slack_oauth_redirect_path }}'
 
-# "@user:example.com" to allow a specific user
+# "@alice:example.com" to allow a specific user
 # "@.*:example.com" to allow users on a specific homeserver
 # "@.*" to allow anyone
 matrix_mx_puppet_slack_provisioning_whitelist:
   - "@.*:{{ matrix_domain | regex_escape }}"
 
 # Leave empty to disable blacklist
-# "@user:example.com" to disallow a specific user
+# "@bob:example.com" to disallow a specific user
 # "@.*:example.com" to disallow users on a specific homeserver
 matrix_mx_puppet_slack_provisioning_blacklist: []