pyrox.dev
lol
nixos/mjolnir: convert manual chapter to MD
+208
-84
+110
nixos/modules/services/matrix/mjolnir.md
+110
nixos/modules/services/matrix/mjolnir.md
···
1
+
# Mjolnir (Matrix Moderation Tool) {#module-services-mjolnir}
2
+
3
+
This chapter will show you how to set up your own, self-hosted
4
+
[Mjolnir](https://github.com/matrix-org/mjolnir) instance.
5
+
6
+
As an all-in-one moderation tool, it can protect your server from
7
+
malicious invites, spam messages, and whatever else you don't want.
8
+
In addition to server-level protection, Mjolnir is great for communities
9
+
wanting to protect their rooms without having to use their personal
10
+
accounts for moderation.
11
+
12
+
The bot by default includes support for bans, redactions, anti-spam,
13
+
server ACLs, room directory changes, room alias transfers, account
14
+
deactivation, room shutdown, and more.
15
+
16
+
See the [README](https://github.com/matrix-org/mjolnir#readme)
17
+
page and the [Moderator's guide](https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md)
18
+
for additional instructions on how to setup and use Mjolnir.
19
+
20
+
For [additional settings](#opt-services.mjolnir.settings)
21
+
see [the default configuration](https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml).
22
+
23
+
## Mjolnir Setup {#module-services-mjolnir-setup}
24
+
25
+
First create a new Room which will be used as a management room for Mjolnir. In
26
+
this room, Mjolnir will log possible errors and debugging information. You'll
27
+
need to set this Room-ID in [services.mjolnir.managementRoom](#opt-services.mjolnir.managementRoom).
28
+
29
+
Next, create a new user for Mjolnir on your homeserver, if not present already.
30
+
31
+
The Mjolnir Matrix user expects to be free of any rate limiting.
32
+
See [Synapse #6286](https://github.com/matrix-org/synapse/issues/6286)
33
+
for an example on how to achieve this.
34
+
35
+
If you want Mjolnir to be able to deactivate users, move room aliases, shutdown rooms, etc.
36
+
you'll need to make the Mjolnir user a Matrix server admin.
37
+
38
+
Now invite the Mjolnir user to the management room.
39
+
40
+
It is recommended to use [Pantalaimon](https://github.com/matrix-org/pantalaimon),
41
+
so your management room can be encrypted. This also applies if you are looking to moderate an encrypted room.
42
+
43
+
To enable the Pantalaimon E2E Proxy for mjolnir, enable
44
+
[services.mjolnir.pantalaimon](#opt-services.mjolnir.pantalaimon.enable). This will
45
+
autoconfigure a new Pantalaimon instance, which will connect to the homeserver
46
+
set in [services.mjolnir.homeserverUrl](#opt-services.mjolnir.homeserverUrl) and Mjolnir itself
47
+
will 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
+
69
+
If you are using a managed ["Element Matrix Services (EMS)"](https://ems.element.io/)
70
+
server, you will need to consent to the terms and conditions. Upon startup, an error
71
+
log entry with a URL to the consent page will be generated.
72
+
73
+
## Synapse Antispam Module {#module-services-mjolnir-matrix-synapse-antispam}
74
+
75
+
A Synapse module is also available to apply the same rulesets the bot
76
+
uses across an entire homeserver.
77
+
78
+
To use the Antispam Module, add `matrix-synapse-plugins.matrix-synapse-mjolnir-antispam`
79
+
to 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
+
```
+2
nixos/modules/services/matrix/mjolnir.nix
+2
nixos/modules/services/matrix/mjolnir.nix
···
236
236
};
237
237
238
238
meta = {
239
+
# Don't edit the docbook xml directly, edit the md and generate it:
240
+
# `pandoc mjolnir.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > mjolnir.xml`
239
241
doc = ./mjolnir.xml;
240
242
maintainers = with maintainers; [ jojosch ];
241
243
};
+96
-84
nixos/modules/services/matrix/mjolnir.xml
+96
-84
nixos/modules/services/matrix/mjolnir.xml
···
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>
1
+
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-mjolnir">
2
+
<title>Mjolnir (Matrix Moderation Tool)</title>
35
3
<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.
4
+
This chapter will show you how to set up your own, self-hosted
5
+
<link xlink:href="https://github.com/matrix-org/mjolnir">Mjolnir</link>
6
+
instance.
47
7
</para>
48
8
<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.
9
+
As an all-in-one moderation tool, it can protect your server from
10
+
malicious invites, spam messages, and whatever else you don't want.
11
+
In addition to server-level protection, Mjolnir is great for
12
+
communities wanting to protect their rooms without having to use
13
+
their personal accounts for moderation.
51
14
</para>
52
15
<para>
53
-
Now invite the Mjolnir user to the management room.
16
+
The bot by default includes support for bans, redactions, anti-spam,
17
+
server ACLs, room directory changes, room alias transfers, account
18
+
deactivation, room shutdown, and more.
54
19
</para>
55
20
<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.
21
+
See the
22
+
<link xlink:href="https://github.com/matrix-org/mjolnir#readme">README</link>
23
+
page and the
24
+
<link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md">Moderator's
25
+
guide</link> for additional instructions on how to setup and use
26
+
Mjolnir.
58
27
</para>
59
28
<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.
29
+
For <link linkend="opt-services.mjolnir.settings">additional
30
+
settings</link> see
31
+
<link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml">the
32
+
default configuration</link>.
65
33
</para>
66
-
<programlisting>
34
+
<section xml:id="module-services-mjolnir-setup">
35
+
<title>Mjolnir Setup</title>
36
+
<para>
37
+
First create a new Room which will be used as a management room
38
+
for Mjolnir. In this room, Mjolnir will log possible errors and
39
+
debugging information. You'll need to set this Room-ID in
40
+
<link linkend="opt-services.mjolnir.managementRoom">services.mjolnir.managementRoom</link>.
41
+
</para>
42
+
<para>
43
+
Next, create a new user for Mjolnir on your homeserver, if not
44
+
present already.
45
+
</para>
46
+
<para>
47
+
The Mjolnir Matrix user expects to be free of any rate limiting.
48
+
See
49
+
<link xlink:href="https://github.com/matrix-org/synapse/issues/6286">Synapse
50
+
#6286</link> for an example on how to achieve this.
51
+
</para>
52
+
<para>
53
+
If you want Mjolnir to be able to deactivate users, move room
54
+
aliases, shutdown rooms, etc. you'll need to make the Mjolnir user
55
+
a Matrix server admin.
56
+
</para>
57
+
<para>
58
+
Now invite the Mjolnir user to the management room.
59
+
</para>
60
+
<para>
61
+
It is recommended to use
62
+
<link xlink:href="https://github.com/matrix-org/pantalaimon">Pantalaimon</link>,
63
+
so your management room can be encrypted. This also applies if you
64
+
are looking to moderate an encrypted room.
65
+
</para>
66
+
<para>
67
+
To enable the Pantalaimon E2E Proxy for mjolnir, enable
68
+
<link linkend="opt-services.mjolnir.pantalaimon.enable">services.mjolnir.pantalaimon</link>.
69
+
This will autoconfigure a new Pantalaimon instance, which will
70
+
connect to the homeserver set in
71
+
<link linkend="opt-services.mjolnir.homeserverUrl">services.mjolnir.homeserverUrl</link>
72
+
and Mjolnir itself will be configured to connect to the new
73
+
Pantalaimon instance.
74
+
</para>
75
+
<programlisting>
67
76
{
68
77
services.mjolnir = {
69
78
enable = true;
70
-
homeserverUrl = "https://matrix.domain.tld";
79
+
homeserverUrl = "https://matrix.domain.tld";
71
80
pantalaimon = {
72
81
enable = true;
73
-
username = "mjolnir";
74
-
passwordFile = "/run/secrets/mjolnir-password";
82
+
username = "mjolnir";
83
+
passwordFile = "/run/secrets/mjolnir-password";
75
84
};
76
85
protectedRooms = [
77
-
"https://matrix.to/#/!xxx:domain.tld"
86
+
"https://matrix.to/#/!xxx:domain.tld"
78
87
];
79
-
managementRoom = "!yyy:domain.tld";
88
+
managementRoom = "!yyy:domain.tld";
80
89
};
81
90
}
82
91
</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 <literal>matrix-synapse-plugins.matrix-synapse-mjolnir-antispam</literal>
101
-
to the Synapse plugin list and enable the <literal>mjolnir.Module</literal> module.
102
-
</para>
103
-
<programlisting>
92
+
<section xml:id="module-services-mjolnir-setup-ems">
93
+
<title>Element Matrix Services (EMS)</title>
94
+
<para>
95
+
If you are using a managed
96
+
<link xlink:href="https://ems.element.io/">"Element Matrix
97
+
Services (EMS)"</link> server, you will need to consent to
98
+
the terms and conditions. Upon startup, an error log entry with
99
+
a URL to the consent page will be generated.
100
+
</para>
101
+
</section>
102
+
</section>
103
+
<section xml:id="module-services-mjolnir-matrix-synapse-antispam">
104
+
<title>Synapse Antispam Module</title>
105
+
<para>
106
+
A Synapse module is also available to apply the same rulesets the
107
+
bot uses across an entire homeserver.
108
+
</para>
109
+
<para>
110
+
To use the Antispam Module, add
111
+
<literal>matrix-synapse-plugins.matrix-synapse-mjolnir-antispam</literal>
112
+
to the Synapse plugin list and enable the
113
+
<literal>mjolnir.Module</literal> module.
114
+
</para>
115
+
<programlisting>
104
116
{
105
117
services.matrix-synapse = {
106
118
plugins = with pkgs; [
···
125
137
# to already be joined to the room - Mjolnir will not automatically join
126
138
# these rooms.
127
139
ban_lists:
128
-
- "!roomid:example.org"
140
+
- "!roomid:example.org"
129
141
'';
130
142
};
131
143
}
132
144
</programlisting>
133
-
</section>
145
+
</section>
134
146
</chapter>