diff options
Diffstat (limited to 'develop/delegate.html')
| -rw-r--r-- | develop/delegate.html | 68 |
1 files changed, 37 insertions, 31 deletions
diff --git a/develop/delegate.html b/develop/delegate.html index d809078683..859e19ceca 100644 --- a/develop/delegate.html +++ b/develop/delegate.html @@ -182,7 +182,10 @@ <nav class="pagetoc"></nav> </div> - <h1 id="delegation"><a class="header" href="#delegation">Delegation</a></h1> + <h1 id="delegation-of-incoming-federation-traffic"><a class="header" href="#delegation-of-incoming-federation-traffic">Delegation of incoming federation traffic</a></h1> +<p>In the following documentation, we use the term <code>server_name</code> to refer to that setting +in your homeserver configuration file. It appears at the ends of user ids, and tells +other homeservers where they can find your server.</p> <p>By default, other homeservers will expect to be able to reach yours via your <code>server_name</code>, on port 8448. For example, if you set your <code>server_name</code> to <code>example.com</code> (so that your user names look like <code>@user:example.com</code>), @@ -192,31 +195,46 @@ other servers will try to connect to yours at <code>https://example.com:8448/</c to look like <code>*:example.com</code>, whilst having federation traffic routed to a different server and/or port (e.g. <code>synapse.example.com:443</code>).</p> <h2 id="well-known-delegation"><a class="header" href="#well-known-delegation">.well-known delegation</a></h2> -<p>To use this method, you need to be able to alter the -<code>server_name</code> 's https server to serve the <code>/.well-known/matrix/server</code> -URL. Having an active server (with a valid TLS certificate) serving your -<code>server_name</code> domain is out of the scope of this documentation.</p> -<p>The URL <code>https://<server_name>/.well-known/matrix/server</code> should -return a JSON structure containing the key <code>m.server</code> like so:</p> +<p>To use this method, you need to be able to configure the server at +<code>https://<server_name></code> to serve a file at +<code>https://<server_name>/.well-known/matrix/server</code>. There are two ways to do this, shown below.</p> +<p>Note that the <code>.well-known</code> file is hosted on the default port for <code>https</code> (port 443).</p> +<h3 id="external-server"><a class="header" href="#external-server">External server</a></h3> +<p>For maximum flexibility, you need to configure an external server such as nginx, Apache +or HAProxy to serve the <code>https://<server_name>/.well-known/matrix/server</code> file. Setting +up such a server is out of the scope of this documentation, but note that it is often +possible to configure your <a href="reverse_proxy.html">reverse proxy</a> for this.</p> +<p>The URL <code>https://<server_name>/.well-known/matrix/server</code> should be configured +return a JSON structure containing the key <code>m.server</code> like this:</p> <pre><code class="language-json">{ "m.server": "<synapse.server.name>[:<yourport>]" } </code></pre> -<p>In our example, this would mean that URL <code>https://example.com/.well-known/matrix/server</code> -should return:</p> +<p>In our example (where we want federation traffic to be routed to +<code>https://synapse.example.com</code>, on port 443), this would mean that +<code>https://example.com/.well-known/matrix/server</code> should return:</p> <pre><code class="language-json">{ "m.server": "synapse.example.com:443" } </code></pre> <p>Note, specifying a port is optional. If no port is specified, then it defaults to 8448.</p> -<p>With .well-known delegation, federating servers will check for a valid TLS -certificate for the delegated hostname (in our example: <code>synapse.example.com</code>).</p> +<h3 id="serving-a-well-knownmatrixserver-file-with-synapse"><a class="header" href="#serving-a-well-knownmatrixserver-file-with-synapse">Serving a <code>.well-known/matrix/server</code> file with Synapse</a></h3> +<p>If you are able to set up your domain so that <code>https://<server_name></code> is routed to +Synapse (i.e., the only change needed is to direct federation traffic to port 443 +instead of port 8448), then it is possible to configure Synapse to serve a suitable +<code>.well-known/matrix/server</code> file. To do so, add the following to your <code>homeserver.yaml</code> +file:</p> +<pre><code class="language-yaml">serve_server_wellknown: true +</code></pre> +<p><strong>Note</strong>: this <em>only</em> works if <code>https://<server_name></code> is routed to Synapse, so is +generally not suitable if Synapse is hosted at a subdomain such as +<code>https://synapse.example.com</code>.</p> <h2 id="srv-dns-record-delegation"><a class="header" href="#srv-dns-record-delegation">SRV DNS record delegation</a></h2> -<p>It is also possible to do delegation using a SRV DNS record. However, that is -considered an advanced topic since it's a bit complex to set up, and <code>.well-known</code> -delegation is already enough in most cases.</p> -<p>However, if you really need it, you can find some documentation on how such a +<p>It is also possible to do delegation using a SRV DNS record. However, that is generally +not recommended, as it can be difficult to configure the TLS certificates correctly in +this case, and it offers little advantage over <code>.well-known</code> delegation.</p> +<p>However, if you really need it, you can find some documentation on what such a record should look like and how Synapse will use it in <a href="https://matrix.org/docs/spec/server_server/latest#resolving-server-names">the Matrix specification</a>.</p> <h2 id="delegation-faq"><a class="header" href="#delegation-faq">Delegation FAQ</a></h2> @@ -231,23 +249,11 @@ wouldn't need any delegation set up.</p> <p><strong>However</strong>, if your homeserver's APIs aren't accessible on port 8448 and on the domain <code>server_name</code> points to, you will need to let other servers know how to find it using delegation.</p> -<h3 id="do-you-still-recommend-against-using-a-reverse-proxy-on-the-federation-port"><a class="header" href="#do-you-still-recommend-against-using-a-reverse-proxy-on-the-federation-port">Do you still recommend against using a reverse proxy on the federation port?</a></h3> -<p>We no longer actively recommend against using a reverse proxy. Many admins will -find it easier to direct federation traffic to a reverse proxy and manage their -own TLS certificates, and this is a supported configuration.</p> -<p>See <a href="reverse_proxy.html">the reverse proxy documentation</a> for information on setting up a +<h3 id="should-i-use-a-reverse-proxy-for-federation-traffic"><a class="header" href="#should-i-use-a-reverse-proxy-for-federation-traffic">Should I use a reverse proxy for federation traffic?</a></h3> +<p>Generally, using a reverse proxy for both the federation and client traffic is a good +idea, since it saves handling TLS traffic in Synapse. See +<a href="reverse_proxy.html">the reverse proxy documentation</a> for information on setting up a reverse proxy.</p> -<h3 id="do-i-still-need-to-give-my-tls-certificates-to-synapse-if-i-am-using-a-reverse-proxy"><a class="header" href="#do-i-still-need-to-give-my-tls-certificates-to-synapse-if-i-am-using-a-reverse-proxy">Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy?</a></h3> -<p>This is no longer necessary. If you are using a reverse proxy for all of your -TLS traffic, then you can set <code>no_tls: True</code> in the Synapse config.</p> -<p>In that case, the only reason Synapse needs the certificate is to populate a legacy -<code>tls_fingerprints</code> field in the federation API. This is ignored by Synapse 0.99.0 -and later, and the only time pre-0.99 Synapses will check it is when attempting to -fetch the server keys - and generally this is delegated via <code>matrix.org</code>, which -is running a modern version of Synapse.</p> -<h3 id="do-i-need-the-same-certificate-for-the-client-and-federation-port"><a class="header" href="#do-i-need-the-same-certificate-for-the-client-and-federation-port">Do I need the same certificate for the client and federation port?</a></h3> -<p>No. There is nothing stopping you from using different certificates, -particularly if you are using a reverse proxy.</p> </main> |