diff options
Diffstat (limited to 'nixos/modules/services/matrix')
| -rw-r--r-- | nixos/modules/services/matrix/mjolnir.nix | 2 | ||||
| -rw-r--r-- | nixos/modules/services/matrix/mjolnir.xml | 148 | ||||
| -rw-r--r-- | nixos/modules/services/matrix/synapse.nix | 2 | ||||
| -rw-r--r-- | nixos/modules/services/matrix/synapse.xml | 263 |
4 files changed, 2 insertions, 413 deletions
diff --git a/nixos/modules/services/matrix/mjolnir.nix b/nixos/modules/services/matrix/mjolnir.nix index cbf7b93329d7a..b6a3e5e8c7308 100644 --- a/nixos/modules/services/matrix/mjolnir.nix +++ b/nixos/modules/services/matrix/mjolnir.nix @@ -236,7 +236,7 @@ in }; meta = { - doc = ./mjolnir.xml; + doc = ./mjolnir.md; maintainers = with maintainers; [ jojosch ]; }; } diff --git a/nixos/modules/services/matrix/mjolnir.xml b/nixos/modules/services/matrix/mjolnir.xml deleted file mode 100644 index 5bd2919e437c6..0000000000000 --- a/nixos/modules/services/matrix/mjolnir.xml +++ /dev/null @@ -1,148 +0,0 @@ -<!-- 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> diff --git a/nixos/modules/services/matrix/synapse.nix b/nixos/modules/services/matrix/synapse.nix index 3087d879b9d2b..aee275dab1ec1 100644 --- a/nixos/modules/services/matrix/synapse.nix +++ b/nixos/modules/services/matrix/synapse.nix @@ -801,7 +801,7 @@ in { meta = { buildDocsInSandbox = false; - doc = ./synapse.xml; + doc = ./synapse.md; maintainers = teams.matrix.members; }; diff --git a/nixos/modules/services/matrix/synapse.xml b/nixos/modules/services/matrix/synapse.xml deleted file mode 100644 index 686aec93ab675..0000000000000 --- a/nixos/modules/services/matrix/synapse.xml +++ /dev/null @@ -1,263 +0,0 @@ -<!-- 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-matrix"> - <title>Matrix</title> - <para> - <link xlink:href="https://matrix.org/">Matrix</link> is an open - standard for interoperable, decentralised, real-time communication - over IP. It can be used to power Instant Messaging, VoIP/WebRTC - signalling, Internet of Things communication - or anywhere you need - a standard HTTP API for publishing and subscribing to data whilst - tracking the conversation history. - </para> - <para> - This chapter will show you how to set up your own, self-hosted - Matrix homeserver using the Synapse reference homeserver, and how to - serve your own copy of the Element web client. See the - <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try - Matrix Now!</link> overview page for links to Element Apps for - Android and iOS, desktop clients, as well as bridges to other - networks and other projects around Matrix. - </para> - <section xml:id="module-services-matrix-synapse"> - <title>Synapse Homeserver</title> - <para> - <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link> - is the reference homeserver implementation of Matrix from the core - development team at matrix.org. The following configuration - example will set up a synapse server for the - <literal>example.org</literal> domain, served from the host - <literal>myhostname.example.org</literal>. For more information, - please refer to the - <link xlink:href="https://matrix-org.github.io/synapse/latest/setup/installation.html">installation - instructions of Synapse</link> . - </para> - <programlisting> -{ pkgs, lib, config, ... }: -let - fqdn = "${config.networking.hostName}.${config.networking.domain}"; - clientConfig = { - "m.homeserver".base_url = "https://${fqdn}"; - "m.identity_server" = {}; - }; - serverConfig."m.server" = "${config.services.matrix-synapse.settings.server_name}:443"; - mkWellKnown = data: '' - add_header Content-Type application/json; - add_header Access-Control-Allow-Origin *; - return 200 '${builtins.toJSON data}'; - ''; -in { - networking.hostName = "myhostname"; - networking.domain = "example.org"; - networking.firewall.allowedTCPPorts = [ 80 443 ]; - - services.postgresql.enable = true; - services.postgresql.initialScript = pkgs.writeText "synapse-init.sql" '' - CREATE ROLE "matrix-synapse" WITH LOGIN PASSWORD 'synapse'; - CREATE DATABASE "matrix-synapse" WITH OWNER "matrix-synapse" - TEMPLATE template0 - LC_COLLATE = "C" - LC_CTYPE = "C"; - ''; - - services.nginx = { - enable = true; - recommendedTlsSettings = true; - recommendedOptimisation = true; - recommendedGzipSettings = true; - recommendedProxySettings = true; - virtualHosts = { - # If the A and AAAA DNS records on example.org do not point on the same host as the - # records for myhostname.example.org, you can easily move the /.well-known - # virtualHost section of the code to the host that is serving example.org, while - # the rest stays on myhostname.example.org with no other changes required. - # This pattern also allows to seamlessly move the homeserver from - # myhostname.example.org to myotherhost.example.org by only changing the - # /.well-known redirection target. - "${config.networking.domain}" = { - enableACME = true; - forceSSL = true; - # This section is not needed if the server_name of matrix-synapse is equal to - # the domain (i.e. example.org from @foo:example.org) and the federation port - # is 8448. - # Further reference can be found in the docs about delegation under - # https://matrix-org.github.io/synapse/latest/delegate.html - locations."= /.well-known/matrix/server".extraConfig = mkWellKnown serverConfig; - # This is usually needed for homeserver discovery (from e.g. other Matrix clients). - # Further reference can be found in the upstream docs at - # https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient - locations."= /.well-known/matrix/client".extraConfig = mkWellKnown clientConfig; - }; - "${fqdn}" = { - enableACME = true; - forceSSL = true; - # It's also possible to do a redirect here or something else, this vhost is not - # needed for Matrix. It's recommended though to *not put* element - # here, see also the section about Element. - locations."/".extraConfig = '' - return 404; - ''; - # Forward all Matrix API calls to the synapse Matrix homeserver. A trailing slash - # *must not* be used here. - locations."/_matrix".proxyPass = "http://[::1]:8008"; - # Forward requests for e.g. SSO and password-resets. - locations."/_synapse/client".proxyPass = "http://[::1]:8008"; - }; - }; - }; - - services.matrix-synapse = { - enable = true; - settings.server_name = config.networking.domain; - settings.listeners = [ - { port = 8008; - bind_addresses = [ "::1" ]; - type = "http"; - tls = false; - x_forwarded = true; - resources = [ { - names = [ "client" "federation" ]; - compress = true; - } ]; - } - ]; - }; -} -</programlisting> - </section> - <section xml:id="module-services-matrix-register-users"> - <title>Registering Matrix users</title> - <para> - If you want to run a server with public registration by anybody, - you can then enable - <literal>services.matrix-synapse.settings.enable_registration = true;</literal>. - Otherwise, or you can generate a registration secret with - <command>pwgen -s 64 1</command> and set it with - <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />. - To create a new user or admin, run the following after you have - set the secret and have rebuilt NixOS: - </para> - <programlisting> -$ nix-shell -p matrix-synapse -$ register_new_matrix_user -k your-registration-shared-secret http://localhost:8008 -New user localpart: your-username -Password: -Confirm password: -Make admin [no]: -Success! -</programlisting> - <para> - In the example, this would create a user with the Matrix - Identifier <literal>@your-username:example.org</literal>. - </para> - <warning> - <para> - When using - <xref linkend="opt-services.matrix-synapse.settings.registration_shared_secret" />, - the secret will end up in the world-readable store. Instead it’s - recommended to deploy the secret in an additional file like - this: - </para> - <itemizedlist> - <listitem> - <para> - Create a file with the following contents: - </para> - <programlisting> -registration_shared_secret: your-very-secret-secret -</programlisting> - </listitem> - <listitem> - <para> - Deploy the file with a secret-manager such as - <link xlink:href="https://nixops.readthedocs.io/en/latest/overview.html#managing-keys"><option>deployment.keys</option></link> - from - <citerefentry><refentrytitle>nixops</refentrytitle><manvolnum>1</manvolnum></citerefentry> - or - <link xlink:href="https://github.com/Mic92/sops-nix/">sops-nix</link> - to e.g. - <filename>/run/secrets/matrix-shared-secret</filename> and - ensure that it’s readable by - <literal>matrix-synapse</literal>. - </para> - </listitem> - <listitem> - <para> - Include the file like this in your configuration: - </para> - <programlisting> -{ - services.matrix-synapse.extraConfigFiles = [ - "/run/secrets/matrix-shared-secret" - ]; -} -</programlisting> - </listitem> - </itemizedlist> - </warning> - <note> - <para> - It’s also possible to user alternative authentication mechanism - such as - <link xlink:href="https://github.com/matrix-org/matrix-synapse-ldap3">LDAP - (via <literal>matrix-synapse-ldap3</literal>)</link> or - <link xlink:href="https://matrix-org.github.io/synapse/latest/openid.html">OpenID</link>. - </para> - </note> - </section> - <section xml:id="module-services-matrix-element-web"> - <title>Element (formerly known as Riot) Web Client</title> - <para> - <link xlink:href="https://github.com/vector-im/riot-web/">Element - Web</link> is the reference web client for Matrix and developed by - the core team at matrix.org. Element was formerly known as - Riot.im, see the - <link xlink:href="https://element.io/blog/welcome-to-element/">Element - introductory blog post</link> for more information. The following - snippet can be optionally added to the code before to complete the - synapse installation with a web client served at - <literal>https://element.myhostname.example.org</literal> and - <literal>https://element.example.org</literal>. Alternatively, you - can use the hosted copy at - <link xlink:href="https://app.element.io/">https://app.element.io/</link>, - or use other web clients or native client applications. Due to the - <literal>/.well-known</literal> urls set up done above, many - clients should fill in the required connection details - automatically when you enter your Matrix Identifier. See - <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try - Matrix Now!</link> for a list of existing clients and their - supported featureset. - </para> - <programlisting> -{ - services.nginx.virtualHosts."element.${fqdn}" = { - enableACME = true; - forceSSL = true; - serverAliases = [ - "element.${config.networking.domain}" - ]; - - root = pkgs.element-web.override { - conf = { - default_server_config = clientConfig; # see `clientConfig` from the snippet above. - }; - }; - }; -} -</programlisting> - <note> - <para> - The Element developers do not recommend running Element and your - Matrix homeserver on the same fully-qualified domain name for - security reasons. In the example, this means that you should not - reuse the <literal>myhostname.example.org</literal> virtualHost - to also serve Element, but instead serve it on a different - subdomain, like <literal>element.example.org</literal> in the - example. See the - <link xlink:href="https://github.com/vector-im/element-web/tree/v1.10.0#important-security-notes">Element - Important Security Notes</link> for more information on this - subject. - </para> - </note> - </section> -</chapter> |