diff options
Diffstat (limited to 'nixos/modules/services/matrix/mjolnir.xml')
-rw-r--r-- | nixos/modules/services/matrix/mjolnir.xml | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/nixos/modules/services/matrix/mjolnir.xml b/nixos/modules/services/matrix/mjolnir.xml new file mode 100644 index 00000000000..b07abe33979 --- /dev/null +++ b/nixos/modules/services/matrix/mjolnir.xml @@ -0,0 +1,134 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="module-services-mjolnir"> + <title>Mjolnir (Matrix Moderation Tool)</title> + <para> + This chapter will show you how to set up your own, self-hosted + <link xlink:href="https://github.com/matrix-org/mjolnir">Mjolnir</link> + instance. + </para> + <para> + As an all-in-one moderation tool, it can protect your server from + malicious invites, spam messages, and whatever else you don't want. + In addition to server-level protection, Mjolnir is great for communities + wanting to protect their rooms without having to use their personal + accounts for moderation. + </para> + <para> + The bot by default includes support for bans, redactions, anti-spam, + server ACLs, room directory changes, room alias transfers, account + deactivation, room shutdown, and more. + </para> + <para> + See the <link xlink:href="https://github.com/matrix-org/mjolnir#readme">README</link> + page and the <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md">Moderator's guide</link> + for additional instructions on how to setup and use Mjolnir. + </para> + <para> + For <link linkend="opt-services.mjolnir.settings">additional settings</link> + see <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml">the default configuration</link>. + </para> + <section xml:id="module-services-mjolnir-setup"> + <title>Mjolnir Setup</title> + <para> + First create a new Room which will be used as a management room for Mjolnir. In + this room, Mjolnir will log possible errors and debugging information. You'll + need to set this Room-ID in <link linkend="opt-services.mjolnir.managementRoom">services.mjolnir.managementRoom</link>. + </para> + <para> + Next, create a new user for Mjolnir on your homeserver, if not present already. + </para> + <para> + The Mjolnir Matrix user expects to be free of any rate limiting. + See <link xlink:href="https://github.com/matrix-org/synapse/issues/6286">Synapse #6286</link> + for an example on how to achieve this. + </para> + <para> + If you want Mjolnir to be able to deactivate users, move room aliases, shutdown rooms, etc. + you'll need to make the Mjolnir user a Matrix server admin. + </para> + <para> + Now invite the Mjolnir user to the management room. + </para> + <para> + It is recommended to use <link xlink:href="https://github.com/matrix-org/pantalaimon">Pantalaimon</link>, + so your management room can be encrypted. This also applies if you are looking to moderate an encrypted room. + </para> + <para> + To enable the Pantalaimon E2E Proxy for mjolnir, enable + <link linkend="opt-services.mjolnir.pantalaimon.enable">services.mjolnir.pantalaimon</link>. This will + autoconfigure a new Pantalaimon instance, which will connect to the homeserver + set in <link linkend="opt-services.mjolnir.homeserverUrl">services.mjolnir.homeserverUrl</link> and Mjolnir itself + will be configured to connect to the new Pantalaimon instance. + </para> +<programlisting> +{ + services.mjolnir = { + enable = true; + <link linkend="opt-services.mjolnir.homeserverUrl">homeserverUrl</link> = "https://matrix.domain.tld"; + <link linkend="opt-services.mjolnir.pantalaimon">pantalaimon</link> = { + <link linkend="opt-services.mjolnir.pantalaimon.enable">enable</link> = true; + <link linkend="opt-services.mjolnir.pantalaimon.username">username</link> = "mjolnir"; + <link linkend="opt-services.mjolnir.pantalaimon.passwordFile">passwordFile</link> = "/run/secrets/mjolnir-password"; + }; + <link linkend="opt-services.mjolnir.protectedRooms">protectedRooms</link> = [ + "https://matrix.to/#/!xxx:domain.tld" + ]; + <link linkend="opt-services.mjolnir.managementRoom">managementRoom</link> = "!yyy:domain.tld"; + }; +} +</programlisting> + <section xml:id="module-services-mjolnir-setup-ems"> + <title>Element Matrix Services (EMS)</title> + <para> + If you are using a managed <link xlink:href="https://ems.element.io/">"Element Matrix Services (EMS)"</link> + server, you will need to consent to the terms and conditions. Upon startup, an error + log entry with a URL to the consent page will be generated. + </para> + </section> + </section> + + <section xml:id="module-services-mjolnir-matrix-synapse-antispam"> + <title>Synapse Antispam Module</title> + <para> + A Synapse module is also available to apply the same rulesets the bot + uses across an entire homeserver. + </para> + <para> + To use the Antispam Module, add <package>matrix-synapse-plugins.matrix-synapse-mjolnir-antispam</package> + to the Synapse plugin list and enable the <literal>mjolnir.Module</literal> module. + </para> +<programlisting> +{ + services.matrix-synapse = { + plugins = with pkgs; [ + matrix-synapse-plugins.matrix-synapse-mjolnir-antispam + ]; + extraConfig = '' + modules: + - module: mjolnir.Module + config: + # Prevent servers/users in the ban lists from inviting users on this + # server to rooms. Default true. + block_invites: true + # Flag messages sent by servers/users in the ban lists as spam. Currently + # this means that spammy messages will appear as empty to users. Default + # false. + block_messages: false + # Remove users from the user directory search by filtering matrix IDs and + # display names by the entries in the user ban list. Default false. + block_usernames: false + # The room IDs of the ban lists to honour. Unlike other parts of Mjolnir, + # this list cannot be room aliases or permalinks. This server is expected + # to already be joined to the room - Mjolnir will not automatically join + # these rooms. + ban_lists: + - "!roomid:example.org" + ''; + }; +} +</programlisting> + </section> +</chapter> |