commit 078707524efb010b01f491bfdd672a3a53567bee · pyrox.dev/nixpkgs

+110

nixos/modules/services/matrix/mjolnir.md

···

       1
       1
       +
       # Mjolnir (Matrix Moderation Tool) {#module-services-mjolnir}

     

       2
       2
       +
       

     

       3
       3
       +
       This chapter will show you how to set up your own, self-hosted

     

       4
       4
       +
       [Mjolnir](https://github.com/matrix-org/mjolnir) instance.

     

       5
       5
       +
       

     

       6
       6
       +
       As an all-in-one moderation tool, it can protect your server from

     

       7
       7
       +
       malicious invites, spam messages, and whatever else you don't want.

     

       8
       8
       +
       In addition to server-level protection, Mjolnir is great for communities

     

       9
       9
       +
       wanting to protect their rooms without having to use their personal

     

       10
       10
       +
       accounts for moderation.

     

       11
       11
       +
       

     

       12
       12
       +
       The bot by default includes support for bans, redactions, anti-spam,

     

       13
       13
       +
       server ACLs, room directory changes, room alias transfers, account

     

       14
       14
       +
       deactivation, room shutdown, and more.

     

       15
       15
       +
       

     

       16
       16
       +
       See the [README](https://github.com/matrix-org/mjolnir#readme)

     

       17
       17
       +
       page and the [Moderator's guide](https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md)

     

       18
       18
       +
       for additional instructions on how to setup and use Mjolnir.

     

       19
       19
       +
       

     

       20
       20
       +
       For [additional settings](#opt-services.mjolnir.settings)

     

       21
       21
       +
       see [the default configuration](https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml).

     

       22
       22
       +
       

     

       23
       23
       +
       ## Mjolnir Setup {#module-services-mjolnir-setup}

     

       24
       24
       +
       

     

       25
       25
       +
       First create a new Room which will be used as a management room for Mjolnir. In

     

       26
       26
       +
       this room, Mjolnir will log possible errors and debugging information. You'll

     

       27
       27
       +
       need to set this Room-ID in [services.mjolnir.managementRoom](#opt-services.mjolnir.managementRoom).

     

       28
       28
       +
       

     

       29
       29
       +
       Next, create a new user for Mjolnir on your homeserver, if not present already.

     

       30
       30
       +
       

     

       31
       31
       +
       The Mjolnir Matrix user expects to be free of any rate limiting.

     

       32
       32
       +
       See [Synapse #6286](https://github.com/matrix-org/synapse/issues/6286)

     

       33
       33
       +
       for an example on how to achieve this.

     

       34
       34
       +
       

     

       35
       35
       +
       If you want Mjolnir to be able to deactivate users, move room aliases, shutdown rooms, etc.

     

       36
       36
       +
       you'll need to make the Mjolnir user a Matrix server admin.

     

       37
       37
       +
       

     

       38
       38
       +
       Now invite the Mjolnir user to the management room.

     

       39
       39
       +
       

     

       40
       40
       +
       It is recommended to use [Pantalaimon](https://github.com/matrix-org/pantalaimon),

     

       41
       41
       +
       so your management room can be encrypted. This also applies if you are looking to moderate an encrypted room.

     

       42
       42
       +
       

     

       43
       43
       +
       To enable the Pantalaimon E2E Proxy for mjolnir, enable

     

       44
       44
       +
       [services.mjolnir.pantalaimon](#opt-services.mjolnir.pantalaimon.enable). This will

     

       45
       45
       +
       autoconfigure a new Pantalaimon instance, which will connect to the homeserver

     

       46
       46
       +
       set in [services.mjolnir.homeserverUrl](#opt-services.mjolnir.homeserverUrl) and Mjolnir itself

     

       47
       47
       +
       will be configured to connect to the new Pantalaimon instance.

     

       48
       48
       +
       

     

       49
       49
       +
       ```

     

       50
       50
       +
       {

     

       51
       51
       +
         services.mjolnir = {

     

       52
       52
       +
           enable = true;

     

       53
       53
       +
           homeserverUrl = "https://matrix.domain.tld";

     

       54
       54
       +
           pantalaimon = {

     

       55
       55
       +
              enable = true;

     

       56
       56
       +
              username = "mjolnir";

     

       57
       57
       +
              passwordFile = "/run/secrets/mjolnir-password";

     

       58
       58
       +
           };

     

       59
       59
       +
           protectedRooms = [

     

       60
       60
       +
             "https://matrix.to/#/!xxx:domain.tld"

     

       61
       61
       +
           ];

     

       62
       62
       +
           managementRoom = "!yyy:domain.tld";

     

       63
       63
       +
         };

     

       64
       64
       +
       }

     

       65
       65
       +
       ```

     

       66
       66
       +
       

     

       67
       67
       +
       ### Element Matrix Services (EMS) {#module-services-mjolnir-setup-ems}

     

       68
       68
       +
       

     

       69
       69
       +
       If you are using a managed ["Element Matrix Services (EMS)"](https://ems.element.io/)

     

       70
       70
       +
       server, you will need to consent to the terms and conditions. Upon startup, an error

     

       71
       71
       +
       log entry with a URL to the consent page will be generated.

     

       72
       72
       +
       

     

       73
       73
       +
       ## Synapse Antispam Module {#module-services-mjolnir-matrix-synapse-antispam}

     

       74
       74
       +
       

     

       75
       75
       +
       A Synapse module is also available to apply the same rulesets the bot

     

       76
       76
       +
       uses across an entire homeserver.

     

       77
       77
       +
       

     

       78
       78
       +
       To use the Antispam Module, add `matrix-synapse-plugins.matrix-synapse-mjolnir-antispam`

     

       79
       79
       +
       to the Synapse plugin list and enable the `mjolnir.Module` module.

     

       80
       80
       +
       

     

       81
       81
       +
       ```

     

       82
       82
       +
       {

     

       83
       83
       +
         services.matrix-synapse = {

     

       84
       84
       +
           plugins = with pkgs; [

     

       85
       85
       +
             matrix-synapse-plugins.matrix-synapse-mjolnir-antispam

     

       86
       86
       +
           ];

     

       87
       87
       +
           extraConfig = ''

     

       88
       88
       +
             modules:

     

       89
       89
       +
               - module: mjolnir.Module

     

       90
       90
       +
                 config:

     

       91
       91
       +
                   # Prevent servers/users in the ban lists from inviting users on this

     

       92
       92
       +
                   # server to rooms. Default true.

     

       93
       93
       +
                   block_invites: true

     

       94
       94
       +
                   # Flag messages sent by servers/users in the ban lists as spam. Currently

     

       95
       95
       +
                   # this means that spammy messages will appear as empty to users. Default

     

       96
       96
       +
                   # false.

     

       97
       97
       +
                   block_messages: false

     

       98
       98
       +
                   # Remove users from the user directory search by filtering matrix IDs and

     

       99
       99
       +
                   # display names by the entries in the user ban list. Default false.

     

       100
       100
       +
                   block_usernames: false

     

       101
       101
       +
                   # The room IDs of the ban lists to honour. Unlike other parts of Mjolnir,

     

       102
       102
       +
                   # this list cannot be room aliases or permalinks. This server is expected

     

       103
       103
       +
                   # to already be joined to the room - Mjolnir will not automatically join

     

       104
       104
       +
                   # these rooms.

     

       105
       105
       +
                   ban_lists:

     

       106
       106
       +
                     - "!roomid:example.org"

     

       107
       107
       +
           '';

     

       108
       108
       +
         };

     

       109
       109
       +
       }

     

       110
       110
       +
       ```

nixos/modules/services/matrix/mjolnir.nix

···

       236
       236
        
         };

     

       237
       237
        
       

     

       238
       238
        
         meta = {

     

       239
       239
       +
           # Don't edit the docbook xml directly, edit the md and generate it:

     

       240
       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

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="module-services-mjolnir">

     

       6
       6
       -
        <title>Mjolnir (Matrix Moderation Tool)</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         This chapter will show you how to set up your own, self-hosted

     

       9
       9
       -
         <link xlink:href="https://github.com/matrix-org/mjolnir">Mjolnir</link>

     

       10
       10
       -
         instance.

     

       11
       11
       -
        </para>

     

       12
       12
       -
        <para>

     

       13
       13
       -
         As an all-in-one moderation tool, it can protect your server from

     

       14
       14
       -
         malicious invites, spam messages, and whatever else you don't want.

     

       15
       15
       -
         In addition to server-level protection, Mjolnir is great for communities

     

       16
       16
       -
         wanting to protect their rooms without having to use their personal

     

       17
       17
       -
         accounts for moderation.

     

       18
       18
       -
        </para>

     

       19
       19
       -
        <para>

     

       20
       20
       -
         The bot by default includes support for bans, redactions, anti-spam,

     

       21
       21
       -
         server ACLs, room directory changes, room alias transfers, account

     

       22
       22
       -
         deactivation, room shutdown, and more.

     

       23
       23
       -
        </para>

     

       24
       24
       -
        <para>

     

       25
       25
       -
         See the <link xlink:href="https://github.com/matrix-org/mjolnir#readme">README</link>

     

       26
       26
       -
         page and the <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md">Moderator's guide</link>

     

       27
       27
       -
         for additional instructions on how to setup and use Mjolnir.

     

       28
       28
       -
        </para>

     

       29
       29
       -
        <para>

     

       30
       30
       -
         For <link linkend="opt-services.mjolnir.settings">additional settings</link>

     

       31
       31
       -
         see <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml">the default configuration</link>.

     

       32
       32
       -
        </para>

     

       33
       33
       -
        <section xml:id="module-services-mjolnir-setup">

     

       34
       34
       -
         <title>Mjolnir Setup</title>

     

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-mjolnir">

     

       2
       2
       +
         <title>Mjolnir (Matrix Moderation Tool)</title>

     

       35
       3
        
         <para>

     

       36
       36
       -
          First create a new Room which will be used as a management room for Mjolnir. In

     

       37
       37
       -
          this room, Mjolnir will log possible errors and debugging information. You'll

     

       38
       38
       -
          need to set this Room-ID in <link linkend="opt-services.mjolnir.managementRoom">services.mjolnir.managementRoom</link>.

     

       39
       39
       -
         </para>

     

       40
       40
       -
         <para>

     

       41
       41
       -
          Next, create a new user for Mjolnir on your homeserver, if not present already.

     

       42
       42
       -
         </para>

     

       43
       43
       -
         <para>

     

       44
       44
       -
          The Mjolnir Matrix user expects to be free of any rate limiting.

     

       45
       45
       -
          See <link xlink:href="https://github.com/matrix-org/synapse/issues/6286">Synapse #6286</link>

     

       46
       46
       -
          for an example on how to achieve this.

     

       4
       4
       +
           This chapter will show you how to set up your own, self-hosted

     

       5
       5
       +
           <link xlink:href="https://github.com/matrix-org/mjolnir">Mjolnir</link>

     

       6
       6
       +
           instance.

     

       47
       7
        
         </para>

     

       48
       8
        
         <para>

     

       49
       49
       -
          If you want Mjolnir to be able to deactivate users, move room aliases, shutdown rooms, etc.

     

       50
       50
       -
          you'll need to make the Mjolnir user a Matrix server admin.

     

       9
       9
       +
           As an all-in-one moderation tool, it can protect your server from

     

       10
       10
       +
           malicious invites, spam messages, and whatever else you don't want.

     

       11
       11
       +
           In addition to server-level protection, Mjolnir is great for

     

       12
       12
       +
           communities wanting to protect their rooms without having to use

     

       13
       13
       +
           their personal accounts for moderation.

     

       51
       14
        
         </para>

     

       52
       15
        
         <para>

     

       53
       53
       -
          Now invite the Mjolnir user to the management room.

     

       16
       16
       +
           The bot by default includes support for bans, redactions, anti-spam,

     

       17
       17
       +
           server ACLs, room directory changes, room alias transfers, account

     

       18
       18
       +
           deactivation, room shutdown, and more.

     

       54
       19
        
         </para>

     

       55
       20
        
         <para>

     

       56
       56
       -
          It is recommended to use <link xlink:href="https://github.com/matrix-org/pantalaimon">Pantalaimon</link>,

     

       57
       57
       -
          so your management room can be encrypted. This also applies if you are looking to moderate an encrypted room.

     

       21
       21
       +
           See the

     

       22
       22
       +
           <link xlink:href="https://github.com/matrix-org/mjolnir#readme">README</link>

     

       23
       23
       +
           page and the

     

       24
       24
       +
           <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md">Moderator's

     

       25
       25
       +
           guide</link> for additional instructions on how to setup and use

     

       26
       26
       +
           Mjolnir.

     

       58
       27
        
         </para>

     

       59
       28
        
         <para>

     

       60
       60
       -
          To enable the Pantalaimon E2E Proxy for mjolnir, enable

     

       61
       61
       -
          <link linkend="opt-services.mjolnir.pantalaimon.enable">services.mjolnir.pantalaimon</link>. This will

     

       62
       62
       -
          autoconfigure a new Pantalaimon instance, which will connect to the homeserver

     

       63
       63
       -
          set in <link linkend="opt-services.mjolnir.homeserverUrl">services.mjolnir.homeserverUrl</link> and Mjolnir itself

     

       64
       64
       -
          will be configured to connect to the new Pantalaimon instance.

     

       29
       29
       +
           For <link linkend="opt-services.mjolnir.settings">additional

     

       30
       30
       +
           settings</link> see

     

       31
       31
       +
           <link xlink:href="https://github.com/matrix-org/mjolnir/blob/main/config/default.yaml">the

     

       32
       32
       +
           default configuration</link>.

     

       65
       33
        
         </para>

     

       66
       66
       -
       <programlisting>

     

       34
       34
       +
         <section xml:id="module-services-mjolnir-setup">

     

       35
       35
       +
           <title>Mjolnir Setup</title>

     

       36
       36
       +
           <para>

     

       37
       37
       +
             First create a new Room which will be used as a management room

     

       38
       38
       +
             for Mjolnir. In this room, Mjolnir will log possible errors and

     

       39
       39
       +
             debugging information. You'll need to set this Room-ID in

     

       40
       40
       +
             <link linkend="opt-services.mjolnir.managementRoom">services.mjolnir.managementRoom</link>.

     

       41
       41
       +
           </para>

     

       42
       42
       +
           <para>

     

       43
       43
       +
             Next, create a new user for Mjolnir on your homeserver, if not

     

       44
       44
       +
             present already.

     

       45
       45
       +
           </para>

     

       46
       46
       +
           <para>

     

       47
       47
       +
             The Mjolnir Matrix user expects to be free of any rate limiting.

     

       48
       48
       +
             See

     

       49
       49
       +
             <link xlink:href="https://github.com/matrix-org/synapse/issues/6286">Synapse

     

       50
       50
       +
             #6286</link> for an example on how to achieve this.

     

       51
       51
       +
           </para>

     

       52
       52
       +
           <para>

     

       53
       53
       +
             If you want Mjolnir to be able to deactivate users, move room

     

       54
       54
       +
             aliases, shutdown rooms, etc. you'll need to make the Mjolnir user

     

       55
       55
       +
             a Matrix server admin.

     

       56
       56
       +
           </para>

     

       57
       57
       +
           <para>

     

       58
       58
       +
             Now invite the Mjolnir user to the management room.

     

       59
       59
       +
           </para>

     

       60
       60
       +
           <para>

     

       61
       61
       +
             It is recommended to use

     

       62
       62
       +
             <link xlink:href="https://github.com/matrix-org/pantalaimon">Pantalaimon</link>,

     

       63
       63
       +
             so your management room can be encrypted. This also applies if you

     

       64
       64
       +
             are looking to moderate an encrypted room.

     

       65
       65
       +
           </para>

     

       66
       66
       +
           <para>

     

       67
       67
       +
             To enable the Pantalaimon E2E Proxy for mjolnir, enable

     

       68
       68
       +
             <link linkend="opt-services.mjolnir.pantalaimon.enable">services.mjolnir.pantalaimon</link>.

     

       69
       69
       +
             This will autoconfigure a new Pantalaimon instance, which will

     

       70
       70
       +
             connect to the homeserver set in

     

       71
       71
       +
             <link linkend="opt-services.mjolnir.homeserverUrl">services.mjolnir.homeserverUrl</link>

     

       72
       72
       +
             and Mjolnir itself will be configured to connect to the new

     

       73
       73
       +
             Pantalaimon instance.

     

       74
       74
       +
           </para>

     

       75
       75
       +
           <programlisting>

     

       67
       76
        
       {

     

       68
       77
        
         services.mjolnir = {

     

       69
       78
        
           enable = true;

     

       70
       70
       -
           homeserverUrl = "https://matrix.domain.tld";

     

       79
       79
       +
           homeserverUrl = &quot;https://matrix.domain.tld&quot;;

     

       71
       80
        
           pantalaimon = {

     

       72
       81
        
              enable = true;

     

       73
       73
       -
              username = "mjolnir";

     

       74
       74
       -
              passwordFile = "/run/secrets/mjolnir-password";

     

       82
       82
       +
              username = &quot;mjolnir&quot;;

     

       83
       83
       +
              passwordFile = &quot;/run/secrets/mjolnir-password&quot;;

     

       75
       84
        
           };

     

       76
       85
        
           protectedRooms = [

     

       77
       77
       -
             "https://matrix.to/#/!xxx:domain.tld"

     

       86
       86
       +
             &quot;https://matrix.to/#/!xxx:domain.tld&quot;

     

       78
       87
        
           ];

     

       79
       79
       -
           managementRoom = "!yyy:domain.tld";

     

       88
       88
       +
           managementRoom = &quot;!yyy:domain.tld&quot;;

     

       80
       89
        
         };

     

       81
       90
        
       }

     

       82
       91
        
       </programlisting>

     

       83
       83
       -
        <section xml:id="module-services-mjolnir-setup-ems">

     

       84
       84
       -
         <title>Element Matrix Services (EMS)</title>

     

       85
       85
       -
         <para>

     

       86
       86
       -
          If you are using a managed <link xlink:href="https://ems.element.io/">"Element Matrix Services (EMS)"</link>

     

       87
       87
       -
          server, you will need to consent to the terms and conditions. Upon startup, an error

     

       88
       88
       -
          log entry with a URL to the consent page will be generated.

     

       89
       89
       -
         </para>

     

       90
       90
       -
        </section>

     

       91
       91
       -
        </section>

     

       92
       92
       -
       

     

       93
       93
       -
        <section xml:id="module-services-mjolnir-matrix-synapse-antispam">

     

       94
       94
       -
         <title>Synapse Antispam Module</title>

     

       95
       95
       -
         <para>

     

       96
       96
       -
          A Synapse module is also available to apply the same rulesets the bot

     

       97
       97
       -
          uses across an entire homeserver.

     

       98
       98
       -
         </para>

     

       99
       99
       -
         <para>

     

       100
       100
       -
          To use the Antispam Module, add <literal>matrix-synapse-plugins.matrix-synapse-mjolnir-antispam</literal>

     

       101
       101
       -
          to the Synapse plugin list and enable the <literal>mjolnir.Module</literal> module.

     

       102
       102
       -
         </para>

     

       103
       103
       -
       <programlisting>

     

       92
       92
       +
           <section xml:id="module-services-mjolnir-setup-ems">

     

       93
       93
       +
             <title>Element Matrix Services (EMS)</title>

     

       94
       94
       +
             <para>

     

       95
       95
       +
               If you are using a managed

     

       96
       96
       +
               <link xlink:href="https://ems.element.io/">&quot;Element Matrix

     

       97
       97
       +
               Services (EMS)&quot;</link> server, you will need to consent to

     

       98
       98
       +
               the terms and conditions. Upon startup, an error log entry with

     

       99
       99
       +
               a URL to the consent page will be generated.

     

       100
       100
       +
             </para>

     

       101
       101
       +
           </section>

     

       102
       102
       +
         </section>

     

       103
       103
       +
         <section xml:id="module-services-mjolnir-matrix-synapse-antispam">

     

       104
       104
       +
           <title>Synapse Antispam Module</title>

     

       105
       105
       +
           <para>

     

       106
       106
       +
             A Synapse module is also available to apply the same rulesets the

     

       107
       107
       +
             bot uses across an entire homeserver.

     

       108
       108
       +
           </para>

     

       109
       109
       +
           <para>

     

       110
       110
       +
             To use the Antispam Module, add

     

       111
       111
       +
             <literal>matrix-synapse-plugins.matrix-synapse-mjolnir-antispam</literal>

     

       112
       112
       +
             to the Synapse plugin list and enable the

     

       113
       113
       +
             <literal>mjolnir.Module</literal> module.

     

       114
       114
       +
           </para>

     

       115
       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
       128
       -
                     - "!roomid:example.org"

     

       140
       140
       +
                     - &quot;!roomid:example.org&quot;

     

       129
       141
        
           '';

     

       130
       142
        
         };

     

       131
       143
        
       }

     

       132
       144
        
       </programlisting>

     

       133
       133
       -
        </section>

     

       145
       145
       +
         </section>

     

       134
       146
        
       </chapter>