From 1a9cc657e1eae5302b130ee3f50f8741e63afb34 Mon Sep 17 00:00:00 2001 From: David Robertson Date: Mon, 24 Oct 2022 14:11:53 +0100 Subject: Move usage docs to usage dir --- docs/SUMMARY.md | 2 +- docs/federate.md | 67 -------------------------------------------- docs/setup/installation.md | 4 +-- docs/usage/federate.md | 67 ++++++++++++++++++++++++++++++++++++++++++++ docs/welcome_and_overview.md | 4 +-- 5 files changed, 72 insertions(+), 72 deletions(-) delete mode 100644 docs/federate.md create mode 100644 docs/usage/federate.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 65ed6e1d48..afbe2ae3ea 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -15,7 +15,7 @@ - [Upgrading between Synapse Versions](upgrade.md) # Usage - - [Federation](federate.md) + - [Federation](usage/federate.md) - [Configuration](usage/configuration/README.md) - [Configuration Manual](usage/configuration/config_documentation.md) - [Homeserver Sample Config File](usage/configuration/homeserver_sample_config.md) diff --git a/docs/federate.md b/docs/federate.md deleted file mode 100644 index 285473362f..0000000000 --- a/docs/federate.md +++ /dev/null @@ -1,67 +0,0 @@ -Setting up federation -===================== - -Federation is the process by which users on different servers can participate -in the same room. For this to work, those other servers must be able to contact -yours to send messages. - -The `server_name` configured in the Synapse configuration file (often -`homeserver.yaml`) defines how resources (users, rooms, etc.) will be -identified (eg: `@user:example.com`, `#room:example.com`). By default, -it is also the domain that other servers will use to try to reach your -server (via port 8448). This is easy to set up and will work provided -you set the `server_name` to match your machine's public DNS hostname. - -For this default configuration to work, you will need to listen for TLS -connections on port 8448. The preferred way to do that is by using a -reverse proxy: see [the reverse proxy documentation](setup/reverse_proxy.md) for instructions -on how to correctly set one up. - -In some cases you might not want to run Synapse on the machine that has -the `server_name` as its public DNS hostname, or you might want federation -traffic to use a different port than 8448. For example, you might want to -have your user names look like `@user:example.com`, but you want to run -Synapse on `synapse.example.com` on port 443. This can be done using -delegation, which allows an admin to control where federation traffic should -be sent. See [the delegation documentation](setup/delegate.md) for instructions on how to set this up. - -Once federation has been configured, you should be able to join a room over -federation. A good place to start is `#synapse:matrix.org` - a room for -Synapse admins. - -## Troubleshooting - -You can use the [federation tester](https://matrix.org/federationtester) -to check if your homeserver is configured correctly. Alternatively try the -[JSON API used by the federation tester](https://matrix.org/federationtester/api/report?server_name=DOMAIN). -Note that you'll have to modify this URL to replace `DOMAIN` with your -`server_name`. Hitting the API directly provides extra detail. - -The typical failure mode for federation is that when the server tries to join -a room, it is rejected with "401: Unauthorized". Generally this means that other -servers in the room could not access yours. (Joining a room over federation is -a complicated dance which requires connections in both directions). - -Another common problem is that people on other servers can't join rooms that -you invite them to. This can be caused by an incorrectly-configured reverse -proxy: see [the reverse proxy documentation](setup/reverse_proxy.md) for instructions on how -to correctly configure a reverse proxy. - -### Known issues - -**HTTP `308 Permanent Redirect` redirects are not followed**: Due to missing features -in the HTTP library used by Synapse, 308 redirects are currently not followed by -federating servers, which can cause `M_UNKNOWN` or `401 Unauthorized` errors. This -may affect users who are redirecting apex-to-www (e.g. `example.com` -> `www.example.com`), -and especially users of the Kubernetes *Nginx Ingress* module, which uses 308 redirect -codes by default. For those Kubernetes users, [this Stackoverflow post](https://stackoverflow.com/a/52617528/5096871) -might be helpful. For other users, switching to a `301 Moved Permanently` code may be -an option. 308 redirect codes will be supported properly in a future -release of Synapse. - -## Running a demo federation of Synapses - -If you want to get up and running quickly with a trio of homeservers in a -private federation, there is a script in the `demo` directory. This is mainly -useful just for development purposes. See -[demo scripts](https://matrix-org.github.io/synapse/develop/development/demo.html). diff --git a/docs/setup/installation.md b/docs/setup/installation.md index 8d4edbf0a0..d1a4970c01 100644 --- a/docs/setup/installation.md +++ b/docs/setup/installation.md @@ -14,7 +14,7 @@ production-ready setup, you will probably want to specify your domain (`example.com`) rather than a matrix-specific hostname here (in the same way that your email address is probably `user@example.com` rather than `user@email.example.com`) - but doing so may require more advanced setup: see -[Setting up Federation](../federate.md). +[Setting up Federation](../usage/federate.md). ## Installing Synapse @@ -436,7 +436,7 @@ listeners: `cert.pem`). For a more detailed guide to configuring your server for federation, see -[Federation](../federate.md). +[Federation](../usage/federate.md). ### Client Well-Known URI diff --git a/docs/usage/federate.md b/docs/usage/federate.md new file mode 100644 index 0000000000..9b8c61f5a0 --- /dev/null +++ b/docs/usage/federate.md @@ -0,0 +1,67 @@ +Setting up federation +===================== + +Federation is the process by which users on different servers can participate +in the same room. For this to work, those other servers must be able to contact +yours to send messages. + +The `server_name` configured in the Synapse configuration file (often +`homeserver.yaml`) defines how resources (users, rooms, etc.) will be +identified (eg: `@user:example.com`, `#room:example.com`). By default, +it is also the domain that other servers will use to try to reach your +server (via port 8448). This is easy to set up and will work provided +you set the `server_name` to match your machine's public DNS hostname. + +For this default configuration to work, you will need to listen for TLS +connections on port 8448. The preferred way to do that is by using a +reverse proxy: see [the reverse proxy documentation](../setup/reverse_proxy.md) for instructions +on how to correctly set one up. + +In some cases you might not want to run Synapse on the machine that has +the `server_name` as its public DNS hostname, or you might want federation +traffic to use a different port than 8448. For example, you might want to +have your user names look like `@user:example.com`, but you want to run +Synapse on `synapse.example.com` on port 443. This can be done using +delegation, which allows an admin to control where federation traffic should +be sent. See [the delegation documentation](../setup/delegate.md) for instructions on how to set this up. + +Once federation has been configured, you should be able to join a room over +federation. A good place to start is `#synapse:matrix.org` - a room for +Synapse admins. + +## Troubleshooting + +You can use the [federation tester](https://matrix.org/federationtester) +to check if your homeserver is configured correctly. Alternatively try the +[JSON API used by the federation tester](https://matrix.org/federationtester/api/report?server_name=DOMAIN). +Note that you'll have to modify this URL to replace `DOMAIN` with your +`server_name`. Hitting the API directly provides extra detail. + +The typical failure mode for federation is that when the server tries to join +a room, it is rejected with "401: Unauthorized". Generally this means that other +servers in the room could not access yours. (Joining a room over federation is +a complicated dance which requires connections in both directions). + +Another common problem is that people on other servers can't join rooms that +you invite them to. This can be caused by an incorrectly-configured reverse +proxy: see [the reverse proxy documentation](../setup/reverse_proxy.md) for instructions on how +to correctly configure a reverse proxy. + +### Known issues + +**HTTP `308 Permanent Redirect` redirects are not followed**: Due to missing features +in the HTTP library used by Synapse, 308 redirects are currently not followed by +federating servers, which can cause `M_UNKNOWN` or `401 Unauthorized` errors. This +may affect users who are redirecting apex-to-www (e.g. `example.com` -> `www.example.com`), +and especially users of the Kubernetes *Nginx Ingress* module, which uses 308 redirect +codes by default. For those Kubernetes users, [this Stackoverflow post](https://stackoverflow.com/a/52617528/5096871) +might be helpful. For other users, switching to a `301 Moved Permanently` code may be +an option. 308 redirect codes will be supported properly in a future +release of Synapse. + +## Running a demo federation of Synapses + +If you want to get up and running quickly with a trio of homeservers in a +private federation, there is a script in the `demo` directory. This is mainly +useful just for development purposes. See +[demo scripts](https://matrix-org.github.io/synapse/develop/development/demo.html). diff --git a/docs/welcome_and_overview.md b/docs/welcome_and_overview.md index 427997bd92..e35234929a 100644 --- a/docs/welcome_and_overview.md +++ b/docs/welcome_and_overview.md @@ -52,8 +52,8 @@ following documentation: * Understand [how Synapse is built](development/internal_documentation/index.html), how to [migrate database schemas](development/database_schema.md), learn about - [federation](federate.md) and how to [set up a local - federation](federate.md#running-a-demo-federation-of-synapses) for development. + [federation](usage/federate.md) and how to [set up a local + federation](usage/federate.md#running-a-demo-federation-of-synapses) for development. * We like to keep our `git` history clean. [Learn](development/git.md) how to do so! -- cgit 1.4.1