diff options
| -rw-r--r-- | nixos/modules/services/matrix/synapse.xml | 235 |
1 files changed, 140 insertions, 95 deletions
diff --git a/nixos/modules/services/matrix/synapse.xml b/nixos/modules/services/matrix/synapse.xml index cf33957d58ec..65bc53d33ac3 100644 --- a/nixos/modules/services/matrix/synapse.xml +++ b/nixos/modules/services/matrix/synapse.xml @@ -33,21 +33,26 @@ <link xlink:href="https://github.com/matrix-org/synapse#synapse-installation"> installation instructions of Synapse </link>. <programlisting> -{ pkgs, lib, ... }: +{ pkgs, lib, config, ... }: let - fqdn = - let - join = hostName: domain: hostName + lib.optionalString (domain != null) ".${domain}"; - in join config.networking.hostName config.networking.domain; -in { - networking = { - <link linkend="opt-networking.hostName">hostName</link> = "myhostname"; - <link linkend="opt-networking.domain">domain</link> = "example.org"; + fqdn = "${config.networking.hostName}.${config.networking.domain}"; + clientConfig = { + "m.homeserver".base_url = "https://${fqdn}"; + "m.identity_server" = {}; }; - <link linkend="opt-networking.firewall.allowedTCPPorts">networking.firewall.allowedTCPPorts</link> = [ 80 443 ]; + 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 { + <xref linkend="opt-networking.hostName" /> = "myhostname"; + <xref linkend="opt-networking.domain" /> = "example.org"; + <xref linkend="opt-networking.firewall.allowedTCPPorts" /> = [ 80 443 ]; - <link linkend="opt-services.postgresql.enable">services.postgresql.enable</link> = true; - <link linkend="opt-services.postgresql.initialScript">services.postgresql.initialScript</link> = pkgs.writeText "synapse-init.sql" '' + <xref linkend="opt-services.postgresql.enable" /> = true; + <xref linkend="opt-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 @@ -57,78 +62,41 @@ in { services.nginx = { <link linkend="opt-services.nginx.enable">enable</link> = true; - # only recommendedProxySettings and recommendedGzipSettings are strictly required, - # but the rest make sense as well <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true; <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true; <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true; <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true; - <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = { - # This host section can be placed on a different host than the rest, - # i.e. to delegate from the host being accessible as ${config.networking.domain} - # to another host actually running the Matrix homeserver. - "${config.networking.domain}" = { + "${config.networking.domain}" = { <co xml:id='ex-matrix-synapse-dns' /> <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true; <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true; - - <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."= /.well-known/matrix/server".extraConfig</link> = - let - # use 443 instead of the default 8448 port to unite - # the client-server and server-server port for simplicity - server = { "m.server" = "${fqdn}:443"; }; - in '' - add_header Content-Type application/json; - return 200 '${builtins.toJSON server}'; - ''; - <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."= /.well-known/matrix/client".extraConfig</link> = - let - client = { - "m.homeserver" = { "base_url" = "https://${fqdn}"; }; - "m.identity_server" = { "base_url" = "https://vector.im"; }; - }; - # ACAO required to allow element-web on any URL to request this json file - in '' - add_header Content-Type application/json; - add_header Access-Control-Allow-Origin *; - return 200 '${builtins.toJSON client}'; - ''; + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."= /.well-known/matrix/server".extraConfig</link> = mkWellKnown serverConfig; <co xml:id='ex-matrix-synapse-well-known-server' /> + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."= /.well-known/matrix/client".extraConfig</link> = mkWellKnown clientConfig; <co xml:id='ex-matrix-synapse-well-known-client' /> }; - - # Reverse proxy for Matrix client-server and server-server communication - ${fqdn} = { + "${fqdn}" = { <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true; <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true; - - # Or do a redirect instead of the 404, or whatever is appropriate for you. - # But do not put a Matrix Web client here! See the Element web section below. - <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."/".extraConfig</link> = '' + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.extraConfig">locations."/".extraConfig</link> = '' <co xml:id='ex-matrix-synapse-rev-default' /> return 404; ''; - - # forward all Matrix API calls to the synapse Matrix homeserver - locations."/_matrix" = { - <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">proxyPass</link> = "http://[::1]:8008"; # without a trailing / - }; + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/_matrix".proxyPass</link> = "http://[::1]:8008"; <co xml:id='ex-matrix-synapse-rev-proxy-pass' /> + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/_synapse/client".proxyPass</link> = "http://[::1]:8008"; <co xml:id='ex-matrix-synapse-rev-client' /> }; }; }; + services.matrix-synapse = { <link linkend="opt-services.matrix-synapse.enable">enable</link> = true; - <link linkend="opt-services.matrix-synapse.settings.server_name">server_name</link> = config.networking.domain; - <link linkend="opt-services.matrix-synapse.settings.listeners">listeners</link> = [ - { - <link linkend="opt-services.matrix-synapse.settings.listeners._.port">port</link> = 8008; + <link linkend="opt-services.matrix-synapse.settings.server_name">settings.server_name</link> = config.networking.domain; + <link linkend="opt-services.matrix-synapse.settings.listeners">settings.listeners</link> = [ + { <link linkend="opt-services.matrix-synapse.settings.listeners._.port">port</link> = 8008; <link linkend="opt-services.matrix-synapse.settings.listeners._.bind_addresses">bind_addresses</link> = [ "::1" ]; <link linkend="opt-services.matrix-synapse.settings.listeners._.type">type</link> = "http"; <link linkend="opt-services.matrix-synapse.settings.listeners._.tls">tls</link> = false; <link linkend="opt-services.matrix-synapse.settings.listeners._.x_forwarded">x_forwarded</link> = true; <link linkend="opt-services.matrix-synapse.settings.listeners._.resources">resources</link> = [ { - <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.names">names</link> = [ "client" ]; + <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.names">names</link> = [ "client" "federation" ]; <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.compress">compress</link> = true; - } { - <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.names">names</link> = [ "federation" ]; - <link linkend="opt-services.matrix-synapse.settings.listeners._.resources._.compress">compress</link> = false; } ]; } ]; @@ -136,20 +104,59 @@ in { } </programlisting> </para> - - <para> - If the <code>A</code> and <code>AAAA</code> DNS records on - <literal>example.org</literal> do not point on the same host as the records - for <code>myhostname.example.org</code>, you can easily move the - <code>/.well-known</code> virtualHost section of the code to the host that - is serving <literal>example.org</literal>, while the rest stays on - <literal>myhostname.example.org</literal> with no other changes required. - This pattern also allows to seamlessly move the homeserver from - <literal>myhostname.example.org</literal> to - <literal>myotherhost.example.org</literal> by only changing the - <code>/.well-known</code> redirection target. - </para> - + <calloutlist> + <callout arearefs='ex-matrix-synapse-dns'> + <para> + If the <code>A</code> and <code>AAAA</code> DNS records on + <literal>example.org</literal> do not point on the same host as the records + for <code>myhostname.example.org</code>, you can easily move the + <code>/.well-known</code> virtualHost section of the code to the host that + is serving <literal>example.org</literal>, while the rest stays on + <literal>myhostname.example.org</literal> with no other changes required. + This pattern also allows to seamlessly move the homeserver from + <literal>myhostname.example.org</literal> to + <literal>myotherhost.example.org</literal> by only changing the + <code>/.well-known</code> redirection target. + </para> + </callout> + <callout arearefs='ex-matrix-synapse-well-known-server'> + <para> + This section is not needed if the <link linkend="opt-services.matrix-synapse.settings.server_name">server_name</link> + of <package>matrix-synapse</package> is equal to the domain (i.e. + <literal>example.org</literal> from <literal>@foo:example.org</literal>) + and the federation port is 8448. + Further reference can be found in the <link xlink:href="https://matrix-org.github.io/synapse/latest/delegate.html">docs + about delegation</link>. + </para> + </callout> + <callout arearefs='ex-matrix-synapse-well-known-client'> + <para> + This is usually needed for homeserver discovery (from e.g. other Matrix clients). + Further reference can be found in the <link xlink:href="https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient">upstream docs</link> + </para> + </callout> + <callout arearefs='ex-matrix-synapse-rev-default'> + <para> + It's also possible to do a redirect here or something else, this vhost is not + needed for Matrix. It's recommended though to <emphasis>not put</emphasis> element + here, see also the <link linkend='ex-matrix-synapse-rev-default'>section about Element</link>. + </para> + </callout> + <callout arearefs='ex-matrix-synapse-rev-proxy-pass'> + <para> + Forward all Matrix API calls to the synapse Matrix homeserver. A trailing slash + <emphasis>must not</emphasis> be used here. + </para> + </callout> + <callout arearefs='ex-matrix-synapse-rev-client'> + <para> + Forward requests for e.g. SSO and password-resets. + </para> + </callout> + </calloutlist> + </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><link linkend="opt-services.matrix-synapse.settings.enable_registration">services.matrix-synapse.settings.enable_registration</link> = @@ -159,7 +166,7 @@ in { To create a new user or admin, run the following after you have set the secret and have rebuilt NixOS: <screen> -<prompt>$ </prompt>nix run nixpkgs.matrix-synapse +<prompt>$ </prompt>nix-shell -p matrix-synapse <prompt>$ </prompt>register_new_matrix_user -k <replaceable>your-registration-shared-secret</replaceable> http://localhost:8008 <prompt>New user localpart: </prompt><replaceable>your-username</replaceable> <prompt>Password:</prompt> @@ -168,12 +175,51 @@ in { Success! </screen> In the example, this would create a user with the Matrix Identifier - <literal>@your-username:example.org</literal>. Note that the registration - secret ends up in the nix store and therefore is world-readable by any user - on your machine, so it makes sense to only temporarily activate the - <link linkend="opt-services.matrix-synapse.settings.registration_shared_secret">registration_shared_secret</link> - option until a better solution for NixOS is in place. + <literal>@your-username:example.org</literal>. + <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: + <itemizedlist> + <listitem> + <para> + Create a file with the following contents: +<programlisting>registration_shared_secret: your-very-secret-secret</programlisting> + </para> + </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 <package>matrix-synapse</package>. + </para> + </listitem> + <listitem> + <para> + Include the file like this in your configuration: +<programlisting> +{ + <xref linkend="opt-services.matrix-synapse.extraConfigFiles" /> = [ + "/run/secrets/matrix-shared-secret" + ]; +} +</programlisting> + </para> + </listitem> + </itemizedlist> + </para> + </warning> </para> + <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> @@ -206,10 +252,7 @@ Success! <link linkend="opt-services.nginx.virtualHosts._name_.root">root</link> = pkgs.element-web.override { conf = { - default_server_config."m.homeserver" = { - "base_url" = "https://${fqdn}"; - "server_name" = "${fqdn}"; - }; + default_server_config = clientConfig; # see `clientConfig` from the snippet above. }; }; }; @@ -217,15 +260,17 @@ Success! </programlisting> </para> - <para> - Note that 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/riot-web#important-security-note">Element - Important Security Notes</link> for more information on this subject. - </para> + <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> |