Draupnir 2.0.0 (#3941)

* Draupnir 2.0.0 The config getting changes all over the place is because of 2.0 having removed a lot of config options due to the code being removed. * Update Draupnir Documentation to reflect state as of 2.0.0 * Apply Review Feedback Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com> * Change Room IDs found in code review to not conform to playbook standard. Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com> * Further Integrate Code Review Feedback * Apply remaining suggestions from code review. Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com> * Apply Configuration Review Feedback Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com> * Add Self Registration and Native Login to Draupnir * Rework Draupnir Documentation to Remove Pantalaimon * Set bot.draupnir as default username for the bot in config * Draupnir 2.0.1 * Integrate Review Feedback on Structure of Docs Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com> * Further Restructure Docs and tweak variables in response. * Only auto-create draupnir user if a password has been set The Draupnir role supports configuring it with either an access token or with a password. When a password is not assigned (which means the access token mode is used), the user is to be created manually. * Add ensure-matrix-users-created tag Now that the Draupnir user may be auto-created in certain configurations (if a password is assigned), it's useful to have the tag there. --------- Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com> Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2025-01-18 20:25:30 +01:00
parent 3e06e4be63
commit f15c0a46be
8 changed files with 203 additions and 155 deletions
--- a/roles/custom/matrix-appservice-draupnir-for-all/defaults/main.yml
+++ b/roles/custom/matrix-appservice-draupnir-for-all/defaults/main.yml
@ -5,7 +5,7 @@
 matrix_appservice_draupnir_for_all_enabled: true

 # renovate: datasource=docker depName=gnuxie/draupnir
-matrix_appservice_draupnir_for_all_version: "1.87.0"
+matrix_appservice_draupnir_for_all_version: "v2.0.1"

 matrix_appservice_draupnir_for_all_container_image_self_build: false
 matrix_appservice_draupnir_for_all_container_image_self_build_repo: "https://github.com/the-draupnir-project/Draupnir.git"
--- a/roles/custom/matrix-appservice-draupnir-for-all/templates/production-bots.yaml.j2
+++ b/roles/custom/matrix-appservice-draupnir-for-all/templates/production-bots.yaml.j2
@ -4,20 +4,10 @@
 # This should be at INFO or DEBUG in order to get support for Draupnir problems.
 logLevel: "INFO"

-# Whether or not Draupnir should synchronize policy lists immediately after startup.
-# Equivalent to running '!draupnir sync'.
-syncOnStartup: true
-
 # Whether or not Draupnir should check moderation permissions in all protected rooms on startup.
 # Equivalent to running `!draupnir verify`.
 verifyPermissionsOnStartup: true

-# Whether Draupnir should check member lists quicker (by using a different endpoint),
-# keep in mind that enabling this will miss invited (but not joined) users.
-#
-# Turn on if your bot is in (very) large rooms, or in large amounts of rooms.
-fasterMembershipChecks: false
-
 # A case-insensitive list of ban reasons to have the bot also automatically redact the user's messages for.
 #
 # If the bot sees you ban a user with a reason that is an (exact case-insensitive) match to this list,
@ -70,14 +60,10 @@ commands:
    - "draupnir_bot"
    - "draupnir"

-  # Whether or not commands with a wildcard (*) will require an additional `--force` argument
-  # in the command to be able to be submitted.
-  confirmWildcardBan: true
-
  # The default reasons to be prompted with if the reason is missing from a ban command.
  ban:
-    defaultReasons: 
+    defaultReasons:
      - "spam"
      - "brigading"
      - "harassment"
-      - "disagreement"
+      - "disagreement"
--- a/roles/custom/matrix-bot-draupnir/defaults/main.yml
+++ b/roles/custom/matrix-bot-draupnir/defaults/main.yml
@ -5,7 +5,7 @@
 matrix_bot_draupnir_enabled: true

 # renovate: datasource=docker depName=gnuxie/draupnir
-matrix_bot_draupnir_version: "v1.87.0"
+matrix_bot_draupnir_version: "v2.0.1"

 matrix_bot_draupnir_container_image_self_build: false
 matrix_bot_draupnir_container_image_self_build_repo: "https://github.com/the-draupnir-project/Draupnir.git"
@ -49,8 +49,20 @@ matrix_bot_draupnir_systemd_wanted_services_list: []
 # Whether Draupnir should talk to the homeserver through Pantalaimon
 # If true, then other variables must be provided including pointing
 # `matrix_bot_draupnir_homeserver_url` to the Pantalaimon URL.
+# Enabling this option is discouraged, because Draupnir does not support
+# running with Pantalaimon as it would break all workflows that involve answering
+# prompts with reactions. (Hint: a lot of workflows rely on them.)
 matrix_bot_draupnir_pantalaimon_use: false

+# If you choose to accept the risks of using Pantalaimon in your installation
+# against the upstream advice, you can enable this to disable the warning about it.
+matrix_bot_draupnir_pantalaimon_breakage_ignore: false
+
+# Tells the bot if it should use its native E2EE support in the form of experimental Rust Crypto in the bot SDK.
+# This option is mutually exclusive with `matrix_bot_draupnir_pantalaimon_use`.
+# Rust Crypto requires a clean access token that has not touched E2EE so curl is recommended as a method to obtain it.
+matrix_bot_draupnir_enable_experimental_rust_crypto: false
+
 # The access token for the bot user. Required when NOT using Pantalaimon.
 # (Otherwise provide `matrix_bot_draupnir_pantalaimon_username` and `matrix_bot_draupnir_pantalaimon_password` instead.)
 matrix_bot_draupnir_access_token: ""
@ -60,6 +72,15 @@ matrix_bot_draupnir_access_token: ""
 matrix_bot_draupnir_pantalaimon_username: ""
 matrix_bot_draupnir_pantalaimon_password: ""

+# Username and password the bot uses for logging in directly. If using Pantalimon
+# these values become the values of `matrix_bot_draupnir_pantalaimon_username` and `matrix_bot_draupnir_pantalaimon_password`
+matrix_bot_draupnir_login: "{{ matrix_bot_draupnir_pantalaimon_username if matrix_bot_draupnir_pantalaimon_use == 'true' else 'bot.draupnir' }}"
+matrix_bot_draupnir_password: "{{ matrix_bot_draupnir_pantalaimon_password }}"
+
+# Controls if we activate the pantalaimon config block for now. This configuration block is proable to change name for our usecase
+# due to a Draupnir push to scrub Pantalaimon from the codebase.
+matrix_bot_draupnir_login_native: ""
+
 # 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.
@ -84,6 +105,11 @@ matrix_bot_draupnir_raw_homeserver_url: ""
 # Its Exposed here because its common enough to be valid to expose.
 matrix_bot_draupnir_disable_server_acl: "false"

+# Controls if the room state backing store is activated.
+# Room state backing store makes restarts of the bot lightning fast as the bot does not suffer from amnesia.
+# This config option has diminished improvements for bots on extremely fast homeservers or very very small bots on fast homeservers.
+matrix_bot_draupnir_enable_room_state_backing_store: "true"
+
 # Default configuration template which covers the generic use case.
 # You can customize it by controlling the various variables inside it.
 #
--- a/roles/custom/matrix-bot-draupnir/tasks/validate_config.yml
+++ b/roles/custom/matrix-bot-draupnir/tasks/validate_config.yml
@ -5,6 +5,7 @@
    msg: "The `{{ item.name }}` variable must be defined and have a non-null value."
  with_items:
    - {'name': 'matrix_bot_draupnir_access_token', when: "{{ not matrix_bot_draupnir_pantalaimon_use }}"}
+    - {'name': 'matrix_bot_draupnir_access_token', when: "{{ matrix_bot_draupnir_enable_experimental_rust_crypto }}"}
    - {'name': 'matrix_bot_draupnir_management_room', when: true}
    - {'name': 'matrix_bot_draupnir_container_network', when: true}
    - {'name': 'matrix_bot_draupnir_homeserver_url', when: true}
@ -18,4 +19,19 @@
    msg: "The `{{ item.name }}` variable must be undefined or have a null value."
  with_items:
    - {'name': 'matrix_bot_draupnir_access_token', when: "{{ matrix_bot_draupnir_pantalaimon_use }}"}
+    - {'name': 'matrix_bot_draupnir_access_token', when: "{{ matrix_bot_draupnir_login_native }}"}
+    - {'name': 'matrix_bot_draupnir_pantalaimon_use', when: "{{  matrix_bot_draupnir_enable_experimental_rust_crypto }}"}
  when: "item.when | bool and not (vars[item.name] == '' or vars[item.name] is none)"
+
+- when: "matrix_bot_draupnir_pantalaimon_use == 'true' and matrix_bot_draupnir_pantalaimon_breakage_ignore == 'false'"
+  block:
+    - name: Inject warning if Pantalaimon is used together with Draupnir
+      ansible.builtin.set_fact:
+        devture_playbook_runtime_messages_list: |
+          {{
+            devture_playbook_runtime_messages_list | default([])
+            +
+            [
+              "Note: Draupnir does not support running with Pantalaimon as it would break all workflows that involve answering prompts with reactions. To enable E2EE for Draupnir, it is recommended to use matrix_bot_draupnir_enable_experimental_rust_crypto instead. This warning can be disabled by setting matrix_bot_draupnir_pantalaimon_breakage_ignore to true."
+            ]
+          }}
--- a/roles/custom/matrix-bot-draupnir/templates/production.yaml.j2
+++ b/roles/custom/matrix-bot-draupnir/templates/production.yaml.j2
@ -1,5 +1,4 @@
 # Endpoint URL that Draupnir uses to interact with the Matrix homeserver (client-server API),
-# set this to the pantalaimon URL if you're using that.
 homeserverUrl: {{ matrix_bot_draupnir_homeserver_url | to_json }}

 # Endpoint URL that Draupnir could use to fetch events related to reports (client-server API and /_synapse/),
@ -7,29 +6,36 @@ homeserverUrl: {{ matrix_bot_draupnir_homeserver_url | to_json }}
 rawHomeserverUrl: {{ matrix_bot_draupnir_raw_homeserver_url | to_json }}

 # Matrix Access Token to use, Draupnir will only use this if pantalaimon.use is false.
+# This option can be loaded from a file by passing "--access-token-path <path>" at the command line,
+# which would allow using secret management systems such as systemd's service credentials.
 accessToken: {{ matrix_bot_draupnir_access_token | to_json }}

-{% if matrix_bot_draupnir_pantalaimon_use %}
+{% if matrix_bot_draupnir_pantalaimon_use or matrix_bot_draupnir_login_native %}
 # Options related to Pantalaimon (https://github.com/matrix-org/pantalaimon)
 pantalaimon:
-  # Whether or not Draupnir 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.
+  # Set to `true` when the bot is to login and fetch the access token on its own.
  #
  # Draupnir 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_draupnir_pantalaimon_username | to_json }}
+  username: {{ matrix_bot_draupnir_login | to_json }}

  # The password Draupnir will login with.
  #
  # After successfully logging in once, this will be ignored, so this value can be blanked after first startup.
-  password: {{ matrix_bot_draupnir_pantalaimon_password | to_json }}
+  # This option can be loaded from a file by passing "--password-path <path>" at the command line,
+  # which would allow using secret management systems such as systemd's service credentials.
+  password: {{ matrix_bot_draupnir_password | to_json }}
 {% endif %}

+# Experimental usage of the matrix-bot-sdk rust crypto. This can not be used with Pantalaimon.
+# Make sure Pantalaimon is disabled in Draupnir's configuration.
+#
+# Warning: At this time this is not considered production safe.
+experimentalRustCrypto: {{ matrix_bot_draupnir_enable_experimental_rust_crypto | to_json }}
+
 # The path Draupnir will store its state/data in, leave default ("/data/storage") when using containers.
 dataPath: "/data"

@ -57,7 +63,7 @@ managementRoom: {{ matrix_bot_draupnir_management_room | to_json }}
 # Running with verboseLogging is unsupported.
 # Whether Draupnir should log a lot more messages in the room,
 # mainly involves "all-OK" messages, and debugging messages for when Draupnir checks bans in a room.
-#verboseLogging: false
+verboseLogging: false

 # The log level of terminal (or container) output,
 # can be one of DEBUG, INFO, WARN and ERROR, in increasing order of importance and severity.
@ -81,12 +87,6 @@ noop: false
 # DO NOT change this to `true` unless you are very confident that you know what you are doing.
 disableServerACL: {{ matrix_bot_draupnir_disable_server_acl | to_json }}

-# Whether Draupnir should check member lists quicker (by using a different endpoint),
-# keep in mind that enabling this will miss invited (but not joined) users.
-#
-# Turn on if your bot is in (very) large rooms, or in large amounts of rooms.
-fasterMembershipChecks: false
-
 # A case-insensitive list of ban reasons to have the bot also automatically redact the user's messages for.
 #
 # If the bot sees you ban a user with a reason that is an (exact case-insensitive) match to this list,
@ -102,15 +102,6 @@ automaticallyRedactForReasons:
  - "spam"
  - "advertising"

-# A list of rooms to protect. Draupnir will add this to the list it knows from its account data.
-#
-# It won't, however, add it to the account data.
-# Manually add the room via '!draupnir rooms add' to have it stay protected regardless if this config value changes.
-#
-# Note: These must be matrix.to URLs
-#protectedRooms:
-#  - "https://matrix.to/#/#matrix:example.org"
-
 # Whether or not to add all joined rooms to the "protected rooms" list
 # (excluding the management room and watched policy list rooms, see below).
 #
@ -131,15 +122,18 @@ protectAllJoinedRooms: false
 # of the homeserver may be more impacted.
 backgroundDelayMS: 500

+# FIXME: This configuration option is currently broken in the playbook as admin APIs cannot
+# be accessed from containers. See https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3389
+# and https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3308
 # Server administration commands, these commands will only work if Draupnir is
 # a global server administrator, and the bot's server is a Synapse instance.
-admin:
-  # Whether or not Draupnir can temporarily take control of any eligible account from the local homeserver who's in the room
-  # (with enough permissions) to "make" a user an admin.
-  #
-  # This only works if a local user with enough admin permissions is present in the room.
-  enableMakeRoomAdminCommand: false
-
+#admin:
+#  # Whether or not Draupnir can temporarily take control of any eligible account from the local homeserver who's in the room
+#  # (with enough permissions) to "make" a user an admin.
+#  #
+#  # This only works if a local user with enough admin permissions is present in the room.
+#  enableMakeRoomAdminCommand: false
+#
 # Misc options for command handling and commands
 commands:
  # Whether or not the `!draupnir` prefix is necessary to submit commands.
@ -157,10 +151,6 @@ commands:
    - "draupnir_bot"
    - "draupnir"

-  # Whether or not commands with a wildcard (*) will require an additional `--force` argument
-  # in the command to be able to be submitted.
-  confirmWildcardBan: true
-
  # The default reasons to be prompted with if the reason is missing from a ban command.
  ban:
    defaultReasons:
@ -178,10 +168,9 @@ commands:
 #    #
 #    # WordList will ban users who use these words when first joining a room, so take caution when selecting them.
 #    #
-#    # For advanced usage, regex can also be used, see the following links for more information;
-#    #  - https://www.digitalocean.com/community/tutorials/an-introduction-to-regular-expressions
-#    #  - https://regexr.com/
-#    #  - https://regexone.com/
+#    # The word list protection does not support regular expressions at this time.
+#    # The configuration in the past stated support for Regex erroneously.
+#    #
 #    words:
 #      - "LoReM"
 #      - "IpSuM"
@ -196,6 +185,31 @@ commands:
 #    # (users will always be banned if they say a bad word)
 #    minutesBeforeTrusting: 20

+# The room state backing store writes a copy of the room state for all protected
+# rooms to the data directory.
+# It is recommended to enable this option unless you deploy Draupnir close to the
+# homeserver and know that Draupnir is starting up quickly. If your homeserver can
+# respond quickly to Draupnir's requests for `/state` then you might not need this option.
+roomStateBackingStore:
+  enabled: {{ matrix_bot_draupnir_enable_room_state_backing_store | to_json }}
+
+# Safe mode provides recovery options for some failure modes when Draupnir
+# fails to start. For example, if the bot fails to resolve a room alias in
+# a watched list, or if the server has parted from a protected room and can't
+# find a way back in. Safe mode will provide different options to recover from
+# these. Such as unprotecting the room or unwatching the policy list.
+# By default Draupnir will boot into safe mode only when the failure mode
+# is recoverable.
+# It may be desirable to prevent the bot from starting into safe mode if you have
+# a pager system when Draupnir is down, as Draupnir could prevent your monitoring
+# system from identifying a failure to start.
+#safeMode:
+#  # The option for entering safe mode when Draupnir fails to start up.
+#  # - "RecoveryOnly" will only start the bot in safe mode when there are recovery options available. This is the default.
+#  # - "Never" will never start the bot in safe mode when Draupnir fails to start normally.
+#  # - "Always" will always start the bot in safe mode when Draupnir fails to start normally.
+#  bootOption: RecoveryOnly
+
 # Options for advanced monitoring of the health of the bot.
 health:
  # healthz options. These options are best for use in container environments
@ -227,6 +241,18 @@ health:
    # Defaults to 418.
    unhealthyStatus: 418

+  # Sentry options. Sentry is a tool used to receive/collate/triage runtime
+  # errors and performance issues. Skip this section if you do not wish to use
+  # Sentry.
+  sentry:
+    # The key used to upload Sentry data to the server.
+    # dsn: "https://XXXXXXXXX@example.com/YYY
+
+    # Frequency of performance monitoring.
+    # A number in [0.0, 1.0], where 0.0 means "don't bother with tracing"
+    # and 1.0 means "trace performance at every opportunity".
+    # tracesSampleRate: 0.5
+
 {% if matrix_bot_draupnir_web_enabled %}
 # Options for exposing web APIs.
 web:
@ -238,7 +264,12 @@ web:

  # The address to listen for requests on. Defaults to only the current
  # computer.
-  address: 0.0.0.0
+  address: "0.0.0.0"
+
+  # Alternative setting to open to the entire web. Be careful,
+  # as this will increase your security perimeter:
+  #
+  #  address: "0.0.0.0"

  # A web API designed to intercept Matrix API
  # POST /_matrix/client/r0/rooms/{roomId}/report/{eventId}
@ -251,10 +282,13 @@ web:
    enabled: {{ matrix_bot_draupnir_abuse_reporting_enabled | to_json }}
 {% endif %}

+# FIXME: This configuration option is currently broken in the playbook as admin APIs cannot
+# be accessed from containers. See https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3389
+# and https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3308
 # Whether or not to actively poll synapse for abuse reports, to be used
 # instead of intercepting client calls to synapse's abuse endpoint, when that
 # isn't possible/practical.
-pollReports: false
+#pollReports: false

 # Whether or not new reports, received either by webapi or polling,
 # should be printed to our managementRoom.