nixos/mjolnir: convert manual chapter to MD
This commit is contained in:
pennae
parent
5320b4cff8
commit
078707524e
110
nixos/modules/services/matrix/mjolnir.md
Normal file
110
nixos/modules/services/matrix/mjolnir.md
Normal file
@ -0,0 +1,110 @@
|
||||
# Mjolnir (Matrix Moderation Tool) {#module-services-mjolnir}
|
||||
|
||||
This chapter will show you how to set up your own, self-hosted
|
||||
[Mjolnir](https://github.com/matrix-org/mjolnir) instance.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
See the [README](https://github.com/matrix-org/mjolnir#readme)
|
||||
page and the [Moderator's guide](https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md)
|
||||
for additional instructions on how to setup and use Mjolnir.
|
||||
|
||||
For [additional settings](#opt-services.mjolnir.settings)
|
||||
see [the default configuration](https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml).
|
||||
|
||||
## Mjolnir Setup {#module-services-mjolnir-setup}
|
||||
|
||||
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 [services.mjolnir.managementRoom](#opt-services.mjolnir.managementRoom).
|
||||
|
||||
Next, create a new user for Mjolnir on your homeserver, if not present already.
|
||||
|
||||
The Mjolnir Matrix user expects to be free of any rate limiting.
|
||||
See [Synapse #6286](https://github.com/matrix-org/synapse/issues/6286)
|
||||
for an example on how to achieve this.
|
||||
|
||||
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.
|
||||
|
||||
Now invite the Mjolnir user to the management room.
|
||||
|
||||
It is recommended to use [Pantalaimon](https://github.com/matrix-org/pantalaimon),
|
||||
so your management room can be encrypted. This also applies if you are looking to moderate an encrypted room.
|
||||
|
||||
To enable the Pantalaimon E2E Proxy for mjolnir, enable
|
||||
[services.mjolnir.pantalaimon](#opt-services.mjolnir.pantalaimon.enable). This will
|
||||
autoconfigure a new Pantalaimon instance, which will connect to the homeserver
|
||||
set in [services.mjolnir.homeserverUrl](#opt-services.mjolnir.homeserverUrl) and Mjolnir itself
|
||||
will be configured to connect to the new Pantalaimon instance.
|
||||
|
||||
```
|
||||
{
|
||||
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";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Element Matrix Services (EMS) {#module-services-mjolnir-setup-ems}
|
||||
|
||||
If you are using a managed ["Element Matrix Services (EMS)"](https://ems.element.io/)
|
||||
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.
|
||||
|
||||
## Synapse Antispam Module {#module-services-mjolnir-matrix-synapse-antispam}
|
||||
|
||||
A Synapse module is also available to apply the same rulesets the bot
|
||||
uses across an entire homeserver.
|
||||
|
||||
To use the Antispam Module, add `matrix-synapse-plugins.matrix-synapse-mjolnir-antispam`
|
||||
to the Synapse plugin list and enable the `mjolnir.Module` module.
|
||||
|
||||
```
|
||||
{
|
||||
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"
|
||||
'';
|
||||
};
|
||||
}
|
||||
```
|
||||
@ -236,6 +236,8 @@ in
|
||||
};
|
||||
|
||||
meta = {
|
||||
# Don't edit the docbook xml directly, edit the md and generate it:
|
||||
# `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`
|
||||
doc = ./mjolnir.xml;
|
||||
maintainers = with maintainers; [ jojosch ];
|
||||
};
|
||||
|
||||
@ -1,106 +1,118 @@
|
||||
<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>
|
||||
<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>
|
||||
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>.
|
||||
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>
|
||||
Next, create a new user for Mjolnir on your homeserver, if not present already.
|
||||
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 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.
|
||||
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>
|
||||
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.
|
||||
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>
|
||||
Now invite the Mjolnir user to the management room.
|
||||
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>
|
||||
<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>
|
||||
<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";
|
||||
homeserverUrl = "https://matrix.domain.tld";
|
||||
pantalaimon = {
|
||||
enable = true;
|
||||
username = "mjolnir";
|
||||
passwordFile = "/run/secrets/mjolnir-password";
|
||||
username = "mjolnir";
|
||||
passwordFile = "/run/secrets/mjolnir-password";
|
||||
};
|
||||
protectedRooms = [
|
||||
"https://matrix.to/#/!xxx:domain.tld"
|
||||
"https://matrix.to/#/!xxx:domain.tld"
|
||||
];
|
||||
managementRoom = "!yyy: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/">"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 <literal>matrix-synapse-plugins.matrix-synapse-mjolnir-antispam</literal>
|
||||
to the Synapse plugin list and enable the <literal>mjolnir.Module</literal> module.
|
||||
</para>
|
||||
<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
|
||||
<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; [
|
||||
@ -125,10 +137,10 @@
|
||||
# to already be joined to the room - Mjolnir will not automatically join
|
||||
# these rooms.
|
||||
ban_lists:
|
||||
- "!roomid:example.org"
|
||||
- "!roomid:example.org"
|
||||
'';
|
||||
};
|
||||
}
|
||||
</programlisting>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user