become -> ansible_become

For some of these, the `ansible_` prefix does not seem to be needed,
but it's the canonical way to do things and it may become required in
newer Ansible versions.

Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3237

docs/configuring-playbook-bot-draupnir.md

@@ -73,7 +73,7 @@ matrix_bot_draupnir_enabled: true
 matrix_bot_draupnir_pantalaimon_use: true
 
 # User name and password for the bot. Required when using Pantalaimon.
-matrix_bot_draupnir_pantalaimon_username: "bot.draupnir"
+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"

docs/configuring-playbook-bot-mjolnir.md

@@ -37,7 +37,9 @@ The following command works on semi up to date Windows 10 installs and All Windo
 
 ## 4. 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. The room must be unencrypted since this role does not support [using Pantalaimon](configuring-playbook-pantalaimon.md) yet.
+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).
 
 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 you can do this by going to the room's settings, clicking Advanced, and then coping the internal room ID. The room ID will look something like `!QvgVuKq0ha8glOLGMG:DOMAIN`.
 
@@ -46,6 +48,47 @@ Finally invite the `@bot.mjolnir:DOMAIN` account you created earlier into the ro
 
 ## 5. 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).
+
+### 5a. Configuration with E2EE support
+
+When using Pantalaimon, Mjolnir will log in to its bot account itself through Pantalaimon, so configure its username and password.
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+
+```yaml
+# 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"
+```
+
+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`:
+
+```yaml
+# Endpoint URL that Mjolnir uses to interact with the matrix homeserver (client-server API).
+# Set this to the pantalaimon URL if you're using that.
+matrix_bot_mjolnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_mjolnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
+
+# Endpoint URL that Mjolnir could use to fetch events related to reports (client-server API and /_synapse/),
+# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
+matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+```
+
+### 5b. 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.DOMAIN/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 the your own values.

docs/configuring-playbook-pantalaimon.md

@@ -4,7 +4,7 @@ The playbook can install and configure the [pantalaimon](https://github.com/matr
 
 See the project's [documentation](https://github.com/matrix-org/pantalaimon) 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 [matrix-bot-draupnir](configuring-playbook-bot-draupnir.md) role and possibly others can use it.
+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.
 
 ## 1. Adjusting the playbook configuration
 

examples/hosts

@@ -2,8 +2,8 @@
 # If you'd rather use a local IP here, make sure to set up `matrix_coturn_turn_external_ip_address`.
 #
 # To connect using a non-root user (and elevate to root with sudo later),
-# replace `ansible_ssh_user=root` with something like this: `ansible_ssh_user=username become=true become_user=root`.
-# If sudo requires a password, either add `become_password=PASSWORD_HERE` to the host line
+# replace `ansible_ssh_user=root` with something like this: `ansible_ssh_user=username ansible_become=true ansible_become_user=root`.
+# If sudo requires a password, either add `ansible_become_password=PASSWORD_HERE` to the host line
 # or tell Ansible to ask you for the password interactively by adding a `--ask-become-pass` (`-K`) flag to all `ansible-playbook` (or `just`) commands.
 #
 # For improved Ansible performance, SSH pipelining is enabled by default in `ansible.cfg`.

group_vars/matrix_servers

@@ -2638,6 +2638,8 @@ matrix_bot_mjolnir_enabled: false
 matrix_bot_mjolnir_systemd_required_services_list_auto: |
   {{
     matrix_addons_homeserver_systemd_services_list
+    +
+    (['matrix-pantalaimon.service'] if matrix_bot_mjolnir_pantalaimon_use else [])
   }}
 
 matrix_bot_mjolnir_container_image_self_build: "{{ matrix_architecture != 'amd64' }}"
@@ -2649,6 +2651,8 @@ matrix_bot_mjolnir_container_additional_networks_auto: |-
     ([] if matrix_addons_homeserver_container_network == '' else [matrix_addons_homeserver_container_network])
   }}
 
+matrix_bot_mjolnir_homeserver_url: "{{ 'http://matrix-pantalaimon:8009' if matrix_bot_mjolnir_pantalaimon_use else matrix_addons_homeserver_client_api_url }}"
+matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
 ######################################################################
 #
 # /matrix-bot-mjolnir

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

@@ -48,13 +48,13 @@ matrix_bot_draupnir_access_token: ""
 
 # User name and password for the bot. Required when using Pantalaimon.
 # (Otherwise provide `matrix_bot_draupnir_access_token` instead.)
-matrix_bot_draupnir_pantalaimon_username: "bot.draupnir"
+matrix_bot_draupnir_pantalaimon_username: ""
 matrix_bot_draupnir_pantalaimon_password: ""
 
 # The room ID where people can use the bot. The bot has no access controls, so
 # anyone in this room can use the bot - secure your room!
 # This should be a room alias or room ID - not a matrix.to URL.
-# Note: draupnir is fairly verbose - expect a lot of messages from it.
+# Note: Draupnir is fairly verbose - expect a lot of messages from it.
 matrix_bot_draupnir_management_room: ""
 
 # Endpoint URL that Draupnir uses to interact with the matrix homeserver (client-server API).

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

@@ -37,15 +37,34 @@ matrix_bot_mjolnir_systemd_required_services_list_custom: []
 # List of systemd services that matrix-bot-mjolnir.service wants
 matrix_bot_mjolnir_systemd_wanted_services_list: []
 
-# The access token for the bot user
+# Whether Mjolnir should talk to the homeserver through Pantalaimon
+# If true, then other variables must be provided including pointing
+# `matrix_bot_mjolnir_homeserver_url` to the Pantalaimon URL.
+matrix_bot_mjolnir_pantalaimon_use: false
+
+# The access token for the bot user. Required when NOT using Pantalaimon.
+# (Otherwise provide `matrix_bot_mjolnir_pantalaimon_username` and `matrix_bot_mjolnir_pantalaimon_password` instead.)
 matrix_bot_mjolnir_access_token: ""
 
+# User name and password for the bot. Required when using Pantalaimon.
+# (Otherwise provide `matrix_bot_mjolnir_access_token` instead.)
+matrix_bot_mjolnir_pantalaimon_username: ""
+matrix_bot_mjolnir_pantalaimon_password: ""
+
 # The room ID where people can use the bot. The bot has no access controls, so
 # anyone in this room can use the bot - secure your room!
 # This should be a room alias or room ID - not a matrix.to URL.
 # Note: Mjolnir is fairly verbose - expect a lot of messages from it.
 matrix_bot_mjolnir_management_room: ""
 
+# Endpoint URL that Mjolnir uses to interact with the matrix homeserver (client-server API).
+# Set this to the pantalaimon URL if you're using that.
+matrix_bot_mjolnir_homeserver_url: ""
+
+# Endpoint URL that Mjolnir could use to fetch events related to reports (client-server API and /_synapse/),
+# only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
+matrix_bot_mjolnir_raw_homeserver_url: ""
+
 # Default configuration template which covers the generic use case.
 # You can customize it by controlling the various variables inside it.
 #

roles/custom/matrix-bot-mjolnir/tasks/validate_config.yml

@@ -1,9 +1,21 @@
 ---
 
-- name: Fail if required variables are undefined
+- name: Fail if required matrix-bot-mjolnir variables are undefined
   ansible.builtin.fail:
-    msg: "The `{{ item }}` variable must be defined and have a non-null value."
+    msg: "The `{{ item.name }}` variable must be defined and have a non-null value."
   with_items:
-    - "matrix_bot_mjolnir_access_token"
-    - "matrix_bot_mjolnir_management_room"
-  when: "vars[item] == '' or vars[item] is none"
+    - {'name': 'matrix_bot_mjolnir_access_token', when: "{{ not matrix_bot_mjolnir_pantalaimon_use }}"}
+    - {'name': 'matrix_bot_mjolnir_management_room', when: true}
+    - {'name': 'matrix_bot_mjolnir_container_network', when: true}
+    - {'name': 'matrix_bot_mjolnir_homeserver_url', when: true}
+    - {'name': 'matrix_bot_mjolnir_raw_homeserver_url', when: true}
+    - {'name': 'matrix_bot_mjolnir_pantalaimon_username', when: "{{ matrix_bot_mjolnir_pantalaimon_use }}"}
+    - {'name': 'matrix_bot_mjolnir_pantalaimon_password', when: "{{ matrix_bot_mjolnir_pantalaimon_use }}"}
+  when: "item.when | bool and (vars[item.name] == '' or vars[item.name] is none)"
+
+- name: Fail if inappropriate variables are defined
+  ansible.builtin.fail:
+    msg: "The `{{ item.name }}` variable must be undefined or have a null value."
+  with_items:
+    - {'name': 'matrix_bot_mjolnir_access_token', when: "{{ matrix_bot_mjolnir_pantalaimon_use }}"}
+  when: "item.when | bool and not (vars[item.name] == '' or vars[item.name] is none)"

roles/custom/matrix-bot-mjolnir/templates/production.yaml.j2

@@ -1,32 +1,34 @@
 # Endpoint URL that Mjolnir uses to interact with the matrix homeserver (client-server API),
 # set this to the pantalaimon URL if you're using that.
-homeserverUrl: "{{ matrix_homeserver_url }}"
+homeserverUrl: {{ matrix_bot_mjolnir_homeserver_url | to_json }}
 
 # Endpoint URL that Mjolnir could use to fetch events related to reports (client-server API and /_synapse/),
 # only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
-rawHomeserverUrl: "{{ matrix_homeserver_url }}"
+rawHomeserverUrl: {{ matrix_bot_mjolnir_raw_homeserver_url | to_json }}
 
 # Matrix Access Token to use, Mjolnir will only use this if pantalaimon.use is false.
-accessToken: "{{ matrix_bot_mjolnir_access_token }}"
+accessToken: {{ matrix_bot_mjolnir_access_token | to_json }}
 
+{% if matrix_bot_mjolnir_pantalaimon_use %}
 # Options related to Pantalaimon (https://github.com/matrix-org/pantalaimon)
-#pantalaimon:
-#  # Whether or not Mjolnir will use pantalaimon to access the matrix homeserver,
-#  # set to `true` if you're using pantalaimon.
-#  #
-#  # Be sure to point homeserverUrl to the pantalaimon instance.
-#  #
-#  # Mjolnir will log in using the given username and password once,
-#  # then store the resulting access token in a file under dataPath.
-#  use: false
-#
-#  # The username to login with.
-#  username: mjolnir
-#
-#  # The password Mjolnir will login with.
-#  #
-#  # After successfully logging in once, this will be ignored, so this value can be blanked after first startup.
-#  password: your_password
+pantalaimon:
+  # Whether or not Mjolnir will use pantalaimon to access the matrix homeserver,
+  # set to `true` if you're using pantalaimon.
+  #
+  # Be sure to point homeserverUrl to the pantalaimon instance.
+  #
+  # Mjolnir will log in using the given username and password once,
+  # then store the resulting access token in a file under dataPath.
+  use: true
+
+  # The username to login with.
+  username: {{ matrix_bot_mjolnir_pantalaimon_username | to_json }}
+
+  # The password Mjolnir will login with.
+  #
+  # After successfully logging in once, this will be ignored, so this value can be blanked after first startup.
+  password: {{ matrix_bot_mjolnir_pantalaimon_password | to_json }}
+{% endif %}
 
 # The path Mjolnir will store its state/data in, leave default ("/data/storage") when using containers.
 dataPath: "/data"
@@ -49,7 +51,7 @@ recordIgnoredInvites: false
 #
 # Note: By default, Mjolnir is fairly verbose - expect a lot of messages in this room.
 # (see verboseLogging to adjust this a bit.)
-managementRoom: "{{ matrix_bot_mjolnir_management_room }}"
+managementRoom: {{ matrix_bot_mjolnir_management_room | to_json }}
 
 # Whether Mjolnir should log a lot more messages in the room,
 # mainly involves "all-OK" messages, and debugging messages for when mjolnir checks bans in a room.