1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
<!-- Do not edit this file directly, edit its companion .md instead
and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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;
homeserverUrl = "https://matrix.domain.tld";
pantalaimon = {
enable = true;
username = "mjolnir";
passwordFile = "/run/secrets/mjolnir-password";
};
protectedRooms = [
"https://matrix.to/#/!xxx:domain.tld"
];
managementRoom = "!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/"><quote>Element Matrix
Services (EMS)</quote></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
<literal>matrix-synapse-plugins.matrix-synapse-mjolnir-antispam</literal>
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>
|
