pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="module-services-mjolnir">
6 <title>Mjolnir (Matrix Moderation Tool)</title>
7 <para>
8 This chapter will show you how to set up your own, self-hosted
9 <link xlink:href="https://github.com/matrix-org/mjolnir">Mjolnir</link>
10 instance.
11 </para>
12 <para>
13 As an all-in-one moderation tool, it can protect your server from
14 malicious invites, spam messages, and whatever else you don't want.
15 In addition to server-level protection, Mjolnir is great for communities
16 wanting to protect their rooms without having to use their personal
17 accounts for moderation.
18 </para>
19 <para>
20 The bot by default includes support for bans, redactions, anti-spam,
21 server ACLs, room directory changes, room alias transfers, account
22 deactivation, room shutdown, and more.
23 </para>
24 <para>
25 See the <link xlink:href="https://github.com/matrix-org/mjolnir#readme">README</link>
26 page and the <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md">Moderator's guide</link>
27 for additional instructions on how to setup and use Mjolnir.
28 </para>
29 <para>
30 For <link linkend="opt-services.mjolnir.settings">additional settings</link>
31 see <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml">the default configuration</link>.
32 </para>
33 <section xml:id="module-services-mjolnir-setup">
34 <title>Mjolnir Setup</title>
35 <para>
36 First create a new Room which will be used as a management room for Mjolnir. In
37 this room, Mjolnir will log possible errors and debugging information. You'll
38 need to set this Room-ID in <link linkend="opt-services.mjolnir.managementRoom">services.mjolnir.managementRoom</link>.
39 </para>
40 <para>
41 Next, create a new user for Mjolnir on your homeserver, if not present already.
42 </para>
43 <para>
44 The Mjolnir Matrix user expects to be free of any rate limiting.
45 See <link xlink:href="https://github.com/matrix-org/synapse/issues/6286">Synapse #6286</link>
46 for an example on how to achieve this.
47 </para>
48 <para>
49 If you want Mjolnir to be able to deactivate users, move room aliases, shutdown rooms, etc.
50 you'll need to make the Mjolnir user a Matrix server admin.
51 </para>
52 <para>
53 Now invite the Mjolnir user to the management room.
54 </para>
55 <para>
56 It is recommended to use <link xlink:href="https://github.com/matrix-org/pantalaimon">Pantalaimon</link>,
57 so your management room can be encrypted. This also applies if you are looking to moderate an encrypted room.
58 </para>
59 <para>
60 To enable the Pantalaimon E2E Proxy for mjolnir, enable
61 <link linkend="opt-services.mjolnir.pantalaimon.enable">services.mjolnir.pantalaimon</link>. This will
62 autoconfigure a new Pantalaimon instance, which will connect to the homeserver
63 set in <link linkend="opt-services.mjolnir.homeserverUrl">services.mjolnir.homeserverUrl</link> and Mjolnir itself
64 will be configured to connect to the new Pantalaimon instance.
65 </para>
66<programlisting>
67{
68 services.mjolnir = {
69 enable = true;
70 <link linkend="opt-services.mjolnir.homeserverUrl">homeserverUrl</link> = "https://matrix.domain.tld";
71 <link linkend="opt-services.mjolnir.pantalaimon">pantalaimon</link> = {
72 <link linkend="opt-services.mjolnir.pantalaimon.enable">enable</link> = true;
73 <link linkend="opt-services.mjolnir.pantalaimon.username">username</link> = "mjolnir";
74 <link linkend="opt-services.mjolnir.pantalaimon.passwordFile">passwordFile</link> = "/run/secrets/mjolnir-password";
75 };
76 <link linkend="opt-services.mjolnir.protectedRooms">protectedRooms</link> = [
77 "https://matrix.to/#/!xxx:domain.tld"
78 ];
79 <link linkend="opt-services.mjolnir.managementRoom">managementRoom</link> = "!yyy:domain.tld";
80 };
81}
82</programlisting>
83 <section xml:id="module-services-mjolnir-setup-ems">
84 <title>Element Matrix Services (EMS)</title>
85 <para>
86 If you are using a managed <link xlink:href="https://ems.element.io/">"Element Matrix Services (EMS)"</link>
87 server, you will need to consent to the terms and conditions. Upon startup, an error
88 log entry with a URL to the consent page will be generated.
89 </para>
90 </section>
91 </section>
92
93 <section xml:id="module-services-mjolnir-matrix-synapse-antispam">
94 <title>Synapse Antispam Module</title>
95 <para>
96 A Synapse module is also available to apply the same rulesets the bot
97 uses across an entire homeserver.
98 </para>
99 <para>
100 To use the Antispam Module, add <package>matrix-synapse-plugins.matrix-synapse-mjolnir-antispam</package>
101 to the Synapse plugin list and enable the <literal>mjolnir.AntiSpam</literal> module.
102 </para>
103<programlisting>
104{
105 services.matrix-synapse = {
106 plugins = with pkgs; [
107 matrix-synapse-plugins.matrix-synapse-mjolnir-antispam
108 ];
109 extraConfig = ''
110 modules:
111 - module: mjolnir.AntiSpam
112 config:
113 # Prevent servers/users in the ban lists from inviting users on this
114 # server to rooms. Default true.
115 block_invites: true
116 # Flag messages sent by servers/users in the ban lists as spam. Currently
117 # this means that spammy messages will appear as empty to users. Default
118 # false.
119 block_messages: false
120 # Remove users from the user directory search by filtering matrix IDs and
121 # display names by the entries in the user ban list. Default false.
122 block_usernames: false
123 # The room IDs of the ban lists to honour. Unlike other parts of Mjolnir,
124 # this list cannot be room aliases or permalinks. This server is expected
125 # to already be joined to the room - Mjolnir will not automatically join
126 # these rooms.
127 ban_lists:
128 - "!roomid:example.org"
129 '';
130 };
131}
132</programlisting>
133 </section>
134</chapter>