Start Updating Mjolnir CFG from Initial to Current

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

@@ -1,136 +1,184 @@
-# Where the homeserver is located (client-server URL). This should point at
+# Endpoint URL that Mjolnir uses to interact with the matrix homeserver (client-server API),
-# pantalaimon if you're using that.
+# set this to the pantalaimon URL if you're using that.
 homeserverUrl: "{{ matrix_homeserver_url }}"
 
-# The access token for the bot to use. Do not populate if using Pantalaimon.
+# 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 }}"
+
+# Matrix Access Token to use, Mjolnir will only use this if pantalaimon.use is false.
 accessToken: "{{ matrix_bot_mjolnir_access_token }}"
 
-# Pantalaimon options (https://github.com/matrix-org/pantalaimon)
+# Options related to Pantalaimon (https://github.com/matrix-org/pantalaimon)
 #pantalaimon:
-#  # If true, accessToken above is ignored and the username/password below will be
+#  # Whether or not Mjolnir will use pantalaimon to access the matrix homeserver,
-#  # used instead. The access token of the bot will be stored in the dataPath.
+#  # 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 to login with. Can be removed after the bot has logged in once and
+#  # The password Mjolnir will login with.
-#  # stored the access token.
+#  #
+#  # After successfully logging in once, this will be ignored, so this value can be blanked after first startup.
 #  password: your_password
 
-# The directory the bot should store various bits of information in
+# The path Mjolnir will store its state/data in, leave default ("/data/storage") when using containers.
 dataPath: "/data"
 
-# If true (the default), only users in the `managementRoom` can invite the bot
+# If true (the default), Mjolnir will only accept invites from users present in managementRoom.
-# to new rooms.
 autojoinOnlyIfManager: true
 
-# If `autojoinOnlyIfManager` is false, only the members in this group can invite
+# If `autojoinOnlyIfManager` is false, only the members in this space can invite
 # the bot to new rooms.
-#acceptInvitesFromGroup: '+example:example.org'
+#acceptInvitesFromSpace: "!example:example.org"
 
-# If the bot is invited to a room and it won't accept the invite (due to the
+# Whether Mjolnir should report ignored invites to the management room (if autojoinOnlyIfManager is true).
-# conditions above), report it to the management room. Defaults to disabled (no
-# reporting).
 recordIgnoredInvites: false
 
-# The room ID where people can use the bot. The bot has no access controls, so
+# The room ID (or room alias) of the management room, anyone in this room can issue commands to Mjolnir.
-# anyone in this room can use the bot - secure your room!
+#
+# Mjolnir has no more granular access controls other than this, be sure you trust everyone in this room - secure it!
+#
 # 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.
+#
+# 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 }}"
 
-# Set to false to make the management room a bit quieter.
+# 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.
 verboseLogging: false
 
-# The log level for the logs themselves. One of DEBUG, INFO, WARN, and ERROR.
+# The log level of terminal (or container) output,
+# can be one of DEBUG, INFO, WARN and ERROR, in increasing order of importance and severity.
+#
 # This should be at INFO or DEBUG in order to get support for Mjolnir problems.
 logLevel: "INFO"
 
-# Set to false to disable synchronizing the ban lists on startup. If true, this
+# Whether or not Mjolnir should synchronize policy lists immediately after startup.
-# is the same as running !mjolnir sync immediately after startup.
+# Equivalent to running '!mjolnir sync'.
 syncOnStartup: true
 
-# Set to false to prevent Mjolnir from checking its permissions on startup. This
+# Whether or not Mjolnir should check moderation permissions in all protected rooms on startup.
-# is recommended to be left as "true" to catch room permission problems (state
+# Equivalent to running `!mjolnir verify`.
-# resets, etc) before Mjolnir is needed.
 verifyPermissionsOnStartup: true
 
-# If true, Mjolnir won't actually ban users or apply server ACLs, but will
+# Whether or not Mjolnir should actually apply bans and policy lists,
-# think it has. This is useful to see what it does in a scenario where the
+# turn on to trial some untrusted configuration or lists.
-# bot might not be trusted fully, yet. Default false (do bans/ACLs).
 noop: false
 
-# Set to true to use /joined_members instead of /state to figure out who is
+# Whether Mjolnir should check member lists quicker (by using a different endpoint),
-# in the room. Using /state is preferred because it means that users are
+# keep in mind that enabling this will miss invited (but not joined) users.
-# banned when they are invited instead of just when they join, though if your
+#
-# server struggles with /state requests then set this to true.
+# 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 automatically redact a user's
+# A case-insensitive list of ban reasons to have the bot also automatically redact the user's messages for.
-# messages for. Typically this is useful to avoid having to type two commands
+#
-# to the bot. Use asterisks to represent globs (ie: "spam*testing" would match
+# If the bot sees you ban a user with a reason that is an (exact case-insensitive) match to this list,
-# "spam for testing" as well as "spamtesting").
+# it will also remove the user's messages automatically.
+#
+# Typically this is useful to avoid having to give two commands to the bot.
+# Advanced: Use asterisks to have the reason match using "globs"
+# (f.e. "spam*testing" would match "spam for testing" as well as "spamtesting").
+#
+# See here for more info: https://www.digitalocean.com/community/tools/glob
+# Note: Keep in mind that glob is NOT regex!
 automaticallyRedactForReasons:
- - "spam"
+  - "spam"
- - "advertising"
+  - "advertising"
 
-# A list of rooms to protect (matrix.to URLs)
+# A list of rooms to protect. Mjolnir 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 '!mjolnir rooms add' to have it stay protected regardless if this config value changes.
+#
+# Note: These must be matrix.to URLs
 #protectedRooms:
 #  - "https://matrix.to/#/#yourroom:example.org"
 
-# Set this option to true to protect every room the bot is joined to. Note that
+# Whether or not to add all joined rooms to the "protected rooms" list
-# this effectively makes the protectedRooms and associated commands useless because
+# (excluding the management room and watched policy list rooms, see below).
-# the bot by nature must be joined to the room to protect it.
 #
-# Note: the management room is *excluded* from this condition. Add it to the
+# Note that this effectively makes the protectedRooms and associated commands useless
-# protected rooms to protect it.
+# for regular rooms.
 #
-# Note: ban list rooms the bot is watching but didn't create will not be protected.
+# Note: the management room is *excluded* from this condition.
-# Manually add these rooms to the protected rooms list if you want them protected.
+# Explicitly add it as a protected room to protect it.
+#
+# Note: Ban list rooms the bot is watching but didn't create will not be protected.
+# Explicitly add these rooms as a protected room list if you want them protected.
 protectAllJoinedRooms: false
 
+# Increase this delay to have Mjölnir wait longer between two consecutive backgrounded
+# operations. The total duration of operations will be longer, but the homeserver won't
+# be affected as much. Conversely, decrease this delay to have Mjölnir chain operations
+# faster. The total duration of operations will generally be shorter, but the performance
+# of the homeserver may be more impacted.
+backgroundDelayMS: 500
+
+# Server administration commands, these commands will only work if Mjolnir is
+# a global server administrator, and the bot's server is a Synapse instance.
+#admin:
+#  # Whether or not Mjolnir 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:
-  # If true, Mjolnir will respond to commands like !help and !ban instead of
+  # Whether or not the `!mjolnir` prefix is necessary to submit commands.
-  # requiring a prefix. This is useful if Mjolnir is the only bot running in
-  # your management room.
   #
-  # Note that Mjolnir can be pinged by display name instead of having to use
+  # If `true`, will allow commands like `!ban`, `!help`, etc.
+  #
+  # Note: Mjolnir can also be pinged by display name instead of having to use
   # the !mjolnir prefix. For example, "my_moderator_bot: ban @spammer:example.org"
-  # will ban a user.
+  # will address only my_moderator_bot.
   allowNoPrefix: false
 
-  # In addition to the bot's display name, !mjolnir, and optionally no prefix
+  # Any additional bot prefixes that Mjolnir will listen to. i.e. adding `mod` will allow `!mod help`.
-  # above, the bot will respond to these names. The items here can be used either
-  # as display names or prefixed with exclamation points.
   additionalPrefixes:
     - "mjolnir_bot"
 
-  # If true, ban commands that use wildcard characters require confirmation with
+  # Whether or not commands with a wildcard (*) will require an additional `--force` argument
-  # an extra `--force` argument
+  # in the command to be able to be submitted.
   confirmWildcardBan: true
 
-# Configuration specific to certain toggleable protections
+# Configuration specific to certain toggle-able protections
 #protections:
 #  # Configuration for the wordlist plugin, which can ban users based if they say certain
 #  # blocked words shortly after joining.
 #  wordlist:
-#    # A list of words which should be monitored by the bot.  These will match if any part
+#    # A list of case-insensitive keywords that the WordList protection will watch for from new users.
-#    # of the word is present in the message in any case.  e.g. "hello" also matches
+#    #
-#    # "HEllO".  Additionally, regular expressions can be used.
+#    # 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/
 #    words:
-#      - "CaSe"
+#      - "LoReM"
-#      - "InSeNsAtIve"
+#      - "IpSuM"
-#      - "WoRd"
+#      - "DoLoR"
-#      - "LiSt"
+#      - "aMeT"
 #
-#    # How long after a user joins the server should the bot monitor their messages.  After
+#    # For how long (in minutes) the user is "new" to the WordList plugin.
-#    # this time, users can say words from the wordlist without being banned automatically.
+#    #
-#    # Set to zero to disable (users will always be banned if they say a bad word)
+#    # After this time, the user will no longer be banned for using a word in the above wordlist.
+#    #
+#    # Set to zero to disable the timeout and make users *always* appear "new".
+#    # (users will always be banned if they say a bad word)
 #    minutesBeforeTrusting: 20
 
-# Options for monitoring the health of the bot
+# Options for advanced monitoring of the health of the bot.
 health:
   # healthz options. These options are best for use in container environments
   # like Kubernetes to detect how healthy the service is. The bot will report
@@ -160,3 +208,39 @@ health:
     # The HTTP status code which reports that the bot is not healthy/ready.
     # Defaults to 418.
     unhealthyStatus: 418
+
+# Options for exposing web APIs.
+#web:
+#  # Whether to enable web APIs.
+#  enabled: false
+#
+#  # The port to expose the webserver on. Defaults to 8080.
+#  port: 8080
+#
+#  # The address to listen for requests on. Defaults to only the current
+#  # computer.
+#  address: localhost
+#
+#  # 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}
+#  # and display readable abuse reports in the moderation room.
+#  #
+#  # If you wish to take advantage of this feature, you will need
+#  # to configure a reverse proxy, see e.g. test/nginx.conf
+#  abuseReporting:
+#    # Whether to enable this feature.
+#    enabled: false
+
+# 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: true
+
+# Whether or not new reports, received either by webapi or polling,
+# should be printed to our managementRoom.
+displayReports: true