depot/third_party/nixpkgs/nixos/modules/services/matrix/mjolnir.xml

<!-- 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 = &quot;https://matrix.domain.tld&quot;;
    pantalaimon = {
       enable = true;
       username = &quot;mjolnir&quot;;
       passwordFile = &quot;/run/secrets/mjolnir-password&quot;;
    };
    protectedRooms = [
      &quot;https://matrix.to/#/!xxx:domain.tld&quot;
    ];
    managementRoom = &quot;!yyy:domain.tld&quot;;
  };
}
</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:
              - &quot;!roomid:example.org&quot;
    '';
  };
}
</programlisting>
  </section>
</chapter>