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