diff --git a/changelog.d/14282.doc b/changelog.d/14282.doc new file mode 100644 index 000000000000..477ff4f45099 --- /dev/null +++ b/changelog.d/14282.doc @@ -0,0 +1 @@ +Reorganise documentation source files and fix dead links. diff --git a/docker/README-testing.md b/docker/README-testing.md index 21b99963d8b7..8e218ca83224 100644 --- a/docker/README-testing.md +++ b/docker/README-testing.md @@ -98,7 +98,7 @@ Dockerfile makes use of to generate appropriate worker, nginx and supervisord co files. Sharding is supported for a subset of workers, in line with the -[worker documentation](../docs/workers.md). To run multiple instances of a given worker +[worker documentation](../docs/usage/configuration/workers.md). To run multiple instances of a given worker type, simply specify the type multiple times in `SYNAPSE_WORKER_TYPES` (e.g `SYNAPSE_WORKER_TYPES=event_creator,event_creator...`). diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 16720bceb521..afbe2ae3ea6c 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -5,38 +5,38 @@ # Setup - [Installation](setup/installation.md) - - [Using Postgres](postgres.md) - - [Configuring a Reverse Proxy](reverse_proxy.md) + - [Using Postgres](setup/postgres.md) + - [Configuring a Reverse Proxy](setup/reverse_proxy.md) - [Configuring a Forward/Outbound Proxy](setup/forward_proxy.md) - - [Configuring a Turn Server](turn-howto.md) - - [Delegation](delegate.md) + - [Configuring a Turn Server](setup/turn-howto.md) + - [Delegation](setup/delegate.md) # Upgrading - [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) - [Logging Sample Config File](usage/configuration/logging_sample_config.md) - - [Structured Logging](structured_logging.md) - - [Templates](templates.md) + - [Structured Logging](usage/configuration/structured_logging.md) + - [Templates](usage/configuration/templates.md) - [User Authentication](usage/configuration/user_authentication/README.md) - [Single-Sign On](usage/configuration/user_authentication/single_sign_on/README.md) - - [OpenID Connect](openid.md) + - [OpenID Connect](usage/configuration/user_authentication/single_sign_on/openid.md) - [SAML](usage/configuration/user_authentication/single_sign_on/saml.md) - [CAS](usage/configuration/user_authentication/single_sign_on/cas.md) - - [SSO Mapping Providers](sso_mapping_providers.md) - - [Password Auth Providers](password_auth_providers.md) - - [JSON Web Tokens](jwt.md) + - [SSO Mapping Providers](usage/configuration/user_authentication/single_sign_on/sso_mapping_providers.md) + - [Password Auth Providers](usage/configuration/user_authentication/password_auth_providers.md) + - [JSON Web Tokens](usage/configuration/user_authentication/jwt.md) - [Refresh Tokens](usage/configuration/user_authentication/refresh_tokens.md) - - [Registration Captcha](CAPTCHA_SETUP.md) - - [Application Services](application_services.md) - - [Server Notices](server_notices.md) - - [Consent Tracking](consent_tracking.md) - - [User Directory](user_directory.md) - - [Message Retention Policies](message_retention_policies.md) + - [Registration Captcha](usage/configuration/CAPTCHA_SETUP.md) + - [Application Services](usage/configuration/application_services.md) + - [Server Notices](usage/configuration/server_notices.md) + - [Consent Tracking](usage/configuration/consent_tracking.md) + - [User Directory](usage/configuration/user_directory.md) + - [Message Retention Policies](usage/configuration/message_retention_policies.md) - [Pluggable Modules](modules/index.md) - [Writing a module](modules/writing_a_module.md) - [Spam checker callbacks](modules/spam_checker_callbacks.md) @@ -47,65 +47,65 @@ - [Background update controller callbacks](modules/background_update_controller_callbacks.md) - [Account data callbacks](modules/account_data_callbacks.md) - [Porting a legacy module to the new interface](modules/porting_legacy_module.md) - - [Workers](workers.md) - - [Using `synctl` with Workers](synctl_workers.md) - - [Systemd](systemd-with-workers/README.md) - - [Administration](usage/administration/README.md) - - [Admin API](usage/administration/admin_api/README.md) - - [Account Validity](admin_api/account_validity.md) - - [Background Updates](usage/administration/admin_api/background_updates.md) - - [Event Reports](admin_api/event_reports.md) - - [Media](admin_api/media_admin_api.md) - - [Purge History](admin_api/purge_history_api.md) - - [Register Users](admin_api/register_api.md) - - [Registration Tokens](usage/administration/admin_api/registration_tokens.md) - - [Manipulate Room Membership](admin_api/room_membership.md) - - [Rooms](admin_api/rooms.md) - - [Server Notices](admin_api/server_notices.md) - - [Statistics](admin_api/statistics.md) - - [Users](admin_api/user_admin_api.md) - - [Server Version](admin_api/version_api.md) - - [Federation](usage/administration/admin_api/federation.md) - - [Manhole](manhole.md) - - [Monitoring](metrics-howto.md) - - [Reporting Homeserver Usage Statistics](usage/administration/monitoring/reporting_homeserver_usage_statistics.md) - - [Monthly Active Users](usage/administration/monthly_active_users.md) - - [Understanding Synapse Through Grafana Graphs](usage/administration/understanding_synapse_through_grafana_graphs.md) - - [Useful SQL for Admins](usage/administration/useful_sql_for_admins.md) - - [Database Maintenance Tools](usage/administration/database_maintenance_tools.md) - - [State Groups](usage/administration/state_groups.md) - - [Request log format](usage/administration/request_log.md) - - [Admin FAQ](usage/administration/admin_faq.md) + - [Workers](usage/configuration/workers.md) + - [Using `synctl` with Workers](usage/configuration/synctl_workers.md) + - [Systemd](usage/configuration/systemd-with-workers/README.md) + - [Administration](administration/README.md) + - [Admin API](administration/admin_api/README.md) + - [Account Validity](administration/admin_api/account_validity.md) + - [Background Updates](administration/admin_api/background_updates.md) + - [Event Reports](administration/admin_api/event_reports.md) + - [Media](administration/admin_api/media_admin_api.md) + - [Purge History](administration/admin_api/purge_history_api.md) + - [Register Users](administration/admin_api/register_api.md) + - [Registration Tokens](administration/admin_api/registration_tokens.md) + - [Manipulate Room Membership](administration/admin_api/room_membership.md) + - [Rooms](administration/admin_api/rooms.md) + - [Server Notices](administration/admin_api/server_notices.md) + - [Statistics](administration/admin_api/statistics.md) + - [Users](administration/admin_api/user_admin_api.md) + - [Server Version](administration/admin_api/version_api.md) + - [Federation](administration/admin_api/federation.md) + - [Manhole](administration/manhole.md) + - [Monitoring](administration/metrics-howto.md) + - [Reporting Homeserver Usage Statistics](administration/reporting_homeserver_usage_statistics.md) + - [Monthly Active Users](administration/monthly_active_users.md) + - [Understanding Synapse Through Grafana Graphs](administration/understanding_synapse_through_grafana_graphs.md) + - [Useful SQL for Admins](administration/useful_sql_for_admins.md) + - [Database Maintenance Tools](administration/database_maintenance_tools.md) + - [State Groups](administration/state_groups.md) + - [Request log format](administration/request_log.md) + - [Admin FAQ](administration/admin_faq.md) - [Scripts]() # Development - [Contributing Guide](development/contributing_guide.md) - - [Code Style](code_style.md) + - [Code Style](development/code_style.md) - [Reviewing Code](development/reviews.md) - [Release Cycle](development/releases.md) - [Git Usage](development/git.md) - [Testing]() - [Demo scripts](development/demo.md) - - [OpenTracing](opentracing.md) + - [OpenTracing](development/opentracing.md) - [Database Schemas](development/database_schema.md) - [Experimental features](development/experimental_features.md) - [Dependency management](development/dependencies.md) - [Synapse Architecture]() - [Cancellation](development/synapse_architecture/cancellation.md) - - [Log Contexts](log_contexts.md) - - [Replication](replication.md) - - [TCP Replication](tcp_replication.md) + - [Log Contexts](development/synapse_architecture/log_contexts.md) + - [Replication](development/synapse_architecture/replication.md) + - [TCP Replication](development/synapse_architecture/tcp_replication.md) - [Internal Documentation](development/internal_documentation/README.md) - [Single Sign-On]() - - [SAML](development/saml.md) - - [CAS](development/cas.md) - - [Room DAG concepts](development/room-dag-concepts.md) + - [SAML](development/internal_documentation/saml.md) + - [CAS](development/internal_documentation/cas.md) + - [Room DAG concepts](development/internal_documentation/room-dag-concepts.md) - [State Resolution]() - - [The Auth Chain Difference Algorithm](auth_chain_difference_algorithm.md) - - [Media Repository](media_repository.md) - - [Room and User Statistics](room_and_user_statistics.md) + - [The Auth Chain Difference Algorithm](development/internal_documentation/auth_chain_difference_algorithm.md) + - [Media Repository](development/internal_documentation/media_repository.md) + - [Room and User Statistics](development/internal_documentation/room_and_user_statistics.md) - [Scripts]() # Other - - [Dependency Deprecation Policy](deprecation_policy.md) + - [Dependency Deprecation Policy](other/deprecation_policy.md) - [Running Synapse on a Single-Board Computer](other/running_synapse_on_single_board_computers.md) diff --git a/docs/usage/administration/README.md b/docs/administration/README.md similarity index 100% rename from docs/usage/administration/README.md rename to docs/administration/README.md diff --git a/docs/usage/administration/admin_api/README.md b/docs/administration/admin_api/README.md similarity index 78% rename from docs/usage/administration/admin_api/README.md rename to docs/administration/admin_api/README.md index f11e0b19a63a..d42b2159df56 100644 --- a/docs/usage/administration/admin_api/README.md +++ b/docs/administration/admin_api/README.md @@ -7,7 +7,11 @@ server admin. (Note that a server admin is distinct from a room admin.) An existing user can be marked as a server admin by updating the database directly. -Check your [database settings](config_documentation.md#database) in the configuration file, connect to the correct database using either `psql [database name]` (if using PostgreSQL) or `sqlite3 path/to/your/database.db` (if using SQLite) and elevate the user `@foo:bar.com` to administrator. +Check your [database settings](../../usage/configuration/config_documentation.md#database) +in the configuration file, connect to the correct database using either +`psql [database name]` (if using PostgreSQL) or +`sqlite3 path/to/your/database.db` (if using SQLite) and elevate the user +`@foo:bar.com` to administrator. ```sql UPDATE users SET admin = 1 WHERE name = '@foo:bar.com'; ``` @@ -19,7 +23,7 @@ already on your `$PATH` depending on how Synapse was installed. Finding your user's `access_token` is client-dependent, but will usually be shown in the client's settings. ## Making an Admin API request -For security reasons, we [recommend](reverse_proxy.md#synapse-administration-endpoints) +For security reasons, we [recommend](../../setup/reverse_proxy.md#synapse-administration-endpoints) that the Admin API (`/_synapse/admin/...`) should be hidden from public view using a reverse proxy. This means you should typically query the Admin API from a terminal on the machine which runs Synapse. @@ -35,7 +39,7 @@ For example, suppose we want to [query the account](user_admin_api.md#query-user-account) of the user `@foo:bar.com`. We need an admin access token (e.g. `syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk`), and we need to know which port -Synapse's [`client` listener](config_documentation.md#listeners) is listening +Synapse's [`client` listener](../../usage/configuration/config_documentation.md#listeners) is listening on (e.g. `8008`). Then we can use the following command to request the account information from the Admin API. diff --git a/docs/admin_api/account_validity.md b/docs/administration/admin_api/account_validity.md similarity index 93% rename from docs/admin_api/account_validity.md rename to docs/administration/admin_api/account_validity.md index d878bf7451e3..c7a9a9b208d3 100644 --- a/docs/admin_api/account_validity.md +++ b/docs/administration/admin_api/account_validity.md @@ -5,7 +5,7 @@ use it, you must enable the account validity feature (under `account_validity`) in Synapse's configuration. To use it, you will need to authenticate by providing an `access_token` -for a server admin: see [Admin API](../usage/administration/admin_api). +for a server admin: see [Admin API](index.html). ## Renew account diff --git a/docs/usage/administration/admin_api/background_updates.md b/docs/administration/admin_api/background_updates.md similarity index 97% rename from docs/usage/administration/admin_api/background_updates.md rename to docs/administration/admin_api/background_updates.md index 9f6ac7d56784..3bfd254ffc60 100644 --- a/docs/usage/administration/admin_api/background_updates.md +++ b/docs/administration/admin_api/background_updates.md @@ -106,4 +106,4 @@ The following JSON body parameters are available: - `job_name` - A string which job to run. Valid values are: - `populate_stats_process_rooms` - Recalculate the stats for all rooms. - - `regenerate_directory` - Recalculate the [user directory](../../../user_directory.md) if it is stale or out of sync. + - `regenerate_directory` - Recalculate the [user directory](../../usage/configuration/user_directory.md) if it is stale or out of sync. diff --git a/docs/admin_api/event_reports.md b/docs/administration/admin_api/event_reports.md similarity index 98% rename from docs/admin_api/event_reports.md rename to docs/administration/admin_api/event_reports.md index be6f0961bfcb..b767b49efb7a 100644 --- a/docs/admin_api/event_reports.md +++ b/docs/administration/admin_api/event_reports.md @@ -3,7 +3,7 @@ This API returns information about reported events. To use it, you will need to authenticate by providing an `access_token` -for a server admin: see [Admin API](../usage/administration/admin_api). +for a server admin: see [Admin API](index.html). The api is: ``` diff --git a/docs/usage/administration/admin_api/federation.md b/docs/administration/admin_api/federation.md similarity index 97% rename from docs/usage/administration/admin_api/federation.md rename to docs/administration/admin_api/federation.md index 60cbc5265ef3..51f3b52da824 100644 --- a/docs/usage/administration/admin_api/federation.md +++ b/docs/administration/admin_api/federation.md @@ -81,7 +81,7 @@ The following fields are returned in the JSON response body: - `failure_ts` - nullable integer - The first time Synapse tried and failed to reach the remote server, in ms. This is `null` if communication with the remote server has never failed. - `last_successful_stream_ordering` - nullable integer - The stream ordering of the most - recent successfully-sent [PDU](understanding_synapse_through_grafana_graphs.md#federation) + recent successfully-sent [PDU](../understanding_synapse_through_grafana_graphs.md#federation) to this destination, or `null` if this information has not been tracked yet. - `next_token`: string representing a positive integer - Indication for pagination. See above. - `total` - integer - Total number of destinations. @@ -174,7 +174,7 @@ The following fields are returned in the JSON response body: Room objects contain the following fields: - `room_id` - string - The ID of the room. - `stream_ordering` - integer - The stream ordering of the most recent - successfully-sent [PDU](understanding_synapse_through_grafana_graphs.md#federation) + successfully-sent [PDU](../understanding_synapse_through_grafana_graphs.md#federation) to this destination in this room. - `next_token`: string representing a positive integer - Indication for pagination. See above. - `total` - integer - Total number of destinations. diff --git a/docs/admin_api/media_admin_api.md b/docs/administration/admin_api/media_admin_api.md similarity index 97% rename from docs/admin_api/media_admin_api.md rename to docs/administration/admin_api/media_admin_api.md index d57c5aedae4c..0dd57f76f50c 100644 --- a/docs/admin_api/media_admin_api.md +++ b/docs/administration/admin_api/media_admin_api.md @@ -3,10 +3,10 @@ These APIs allow extracting media information from the homeserver. Details about the format of the `media_id` and storage of the media in the file system -are documented under [media repository](../media_repository.md). +are documented under [media repository](../../development/internal_documentation/media_repository.md). To use it, you will need to authenticate by providing an `access_token` -for a server admin: see [Admin API](../usage/administration/admin_api). +for a server admin: see [Admin API](index.html). ## List all media in a room diff --git a/docs/admin_api/purge_history_api.md b/docs/administration/admin_api/purge_history_api.md similarity index 96% rename from docs/admin_api/purge_history_api.md rename to docs/administration/admin_api/purge_history_api.md index 2527e2758ba3..32e61fef8b74 100644 --- a/docs/admin_api/purge_history_api.md +++ b/docs/administration/admin_api/purge_history_api.md @@ -11,7 +11,7 @@ Note that Synapse requires at least one message in each room, so it will never delete the last message in a room. To use it, you will need to authenticate by providing an `access_token` -for a server admin: see [Admin API](../usage/administration/admin_api). +for a server admin: see [Admin API](index.html). The API is: diff --git a/docs/admin_api/register_api.md b/docs/administration/admin_api/register_api.md similarity index 95% rename from docs/admin_api/register_api.md rename to docs/administration/admin_api/register_api.md index dd2830f3a18a..99b79e284aae 100644 --- a/docs/admin_api/register_api.md +++ b/docs/administration/admin_api/register_api.md @@ -5,7 +5,7 @@ non-interactive way. This is generally used for bootstrapping a Synapse instance with administrator accounts. To authenticate yourself to the server, you will need both the shared secret -([`registration_shared_secret`](../usage/configuration/config_documentation.md#registration_shared_secret) +([`registration_shared_secret`](../../usage/configuration/config_documentation.md#registration_shared_secret) in the homeserver configuration), and a one-time nonce. If the registration shared secret is not configured, this API is not enabled. diff --git a/docs/usage/administration/admin_api/registration_tokens.md b/docs/administration/admin_api/registration_tokens.md similarity index 99% rename from docs/usage/administration/admin_api/registration_tokens.md rename to docs/administration/admin_api/registration_tokens.md index 90cbc21125bf..d2fa63c25436 100644 --- a/docs/usage/administration/admin_api/registration_tokens.md +++ b/docs/administration/admin_api/registration_tokens.md @@ -6,7 +6,7 @@ registration requests, as proposed in and stabilised in version 1.2 of the Matrix specification. To use it, you will need to enable the `registration_requires_token` config option, and authenticate by providing an `access_token` for a server admin: -see [Admin API](../admin_api). +see [Admin API](index.html). ## Registration token objects diff --git a/docs/admin_api/room_membership.md b/docs/administration/admin_api/room_membership.md similarity index 91% rename from docs/admin_api/room_membership.md rename to docs/administration/admin_api/room_membership.md index 310d6ae628fa..bc170e31b1c5 100644 --- a/docs/admin_api/room_membership.md +++ b/docs/administration/admin_api/room_membership.md @@ -6,7 +6,7 @@ local users. The server administrator must be in the room and have permission to invite users. To use it, you will need to authenticate by providing an `access_token` -for a server admin: see [Admin API](../usage/administration/admin_api). +for a server admin: see [Admin API](index.html). ## Parameters diff --git a/docs/admin_api/rooms.md b/docs/administration/admin_api/rooms.md similarity index 99% rename from docs/admin_api/rooms.md rename to docs/administration/admin_api/rooms.md index 8f727b363eb8..58412e1c9593 100644 --- a/docs/admin_api/rooms.md +++ b/docs/administration/admin_api/rooms.md @@ -5,7 +5,7 @@ server. There are various parameters available that allow for filtering and sorting the returned list. This API supports pagination. To use it, you will need to authenticate by providing an `access_token` -for a server admin: see [Admin API](../usage/administration/admin_api). +for a server admin: see [Admin API](index.html). **Parameters** @@ -400,7 +400,7 @@ sent to a room in a given timeframe. There are various parameters available that allow for filtering and ordering the returned list. This API supports pagination. To use it, you will need to authenticate by providing an `access_token` -for a server admin: see [Admin API](../usage/administration/admin_api). +for a server admin: see [Admin API](index.html). This endpoint mirrors the [Matrix Spec defined Messages API](https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidmessages). diff --git a/docs/admin_api/server_notices.md b/docs/administration/admin_api/server_notices.md similarity index 89% rename from docs/admin_api/server_notices.md rename to docs/administration/admin_api/server_notices.md index 323138491a9c..5e2527a38bc5 100644 --- a/docs/admin_api/server_notices.md +++ b/docs/administration/admin_api/server_notices.md @@ -45,4 +45,4 @@ Once the notice has been sent, the API will return the following response: ``` Note that server notices must be enabled in `homeserver.yaml` before this API -can be used. See [the server notices documentation](../server_notices.md) for more information. +can be used. See [the server notices documentation](../../usage/configuration/server_notices.md) for more information. diff --git a/docs/admin_api/statistics.md b/docs/administration/admin_api/statistics.md similarity index 97% rename from docs/admin_api/statistics.md rename to docs/administration/admin_api/statistics.md index a26c76f9f317..c745d6e1e59c 100644 --- a/docs/admin_api/statistics.md +++ b/docs/administration/admin_api/statistics.md @@ -4,7 +4,7 @@ Returns information about all local media usage of users. Gives the possibility to filter them by time and user. To use it, you will need to authenticate by providing an `access_token` -for a server admin: see [Admin API](../usage/administration/admin_api). +for a server admin: see [Admin API](index.html). The API is: diff --git a/docs/admin_api/user_admin_api.md b/docs/administration/admin_api/user_admin_api.md similarity index 98% rename from docs/admin_api/user_admin_api.md rename to docs/administration/admin_api/user_admin_api.md index c95d6c9b0536..2b390c1d7da7 100644 --- a/docs/admin_api/user_admin_api.md +++ b/docs/administration/admin_api/user_admin_api.md @@ -1,7 +1,7 @@ # User Admin API To use it, you will need to authenticate by providing an `access_token` -for a server admin: see [Admin API](../usage/administration/admin_api). +for a server admin: see [Admin API](index.html). ## Query User Account @@ -127,7 +127,7 @@ Body parameters: belonging to a user. - `external_ids` - array, optional. Allow setting the identifier of the external identity provider for SSO (Single sign-on). Details in the configuration manual under the - sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers). + sections [sso](../../usage/configuration/config_documentation.md#sso) and [oidc_providers](../../usage/configuration/config_documentation.md#oidc_providers). - `auth_provider` - string. ID of the external identity provider. Value of `idp_id` in the homeserver configuration. Note that no error is raised if the provided value is not in the homeserver configuration. @@ -548,9 +548,9 @@ The following fields are returned in the JSON response body: ### List media uploaded by a user Gets a list of all local media that a specific `user_id` has created. These are media that the user has uploaded themselves -([local media](../media_repository.md#local-media)), as well as -[URL preview images](../media_repository.md#url-previews) requested by the user if the -[feature is enabled](../usage/configuration/config_documentation.md#url_preview_enabled). +([local media](../../development/internal_documentation/media_repository.md#local-media)), as well as +[URL preview images](../../development/internal_documentation/media_repository.md#url-previews) requested by the user if the +[feature is enabled](../../usage/configuration/config_documentation.md#url_preview_enabled). By default, the response is ordered by descending creation date and ascending media ID. The newest media is on top. You can change the order with parameters @@ -650,7 +650,7 @@ The following fields are returned in the JSON response body: - `last_access_ts` - integer - Timestamp when the content was last accessed in ms. - `media_id` - string - The id used to refer to the media. Details about the format are documented under - [media repository](../media_repository.md). + [media repository](../../development/internal_documentation/media_repository.md). - `media_length` - integer - Length of the media in bytes. - `media_type` - string - The MIME-type of the media. - `quarantined_by` - string - The user ID that initiated the quarantine request diff --git a/docs/admin_api/version_api.md b/docs/administration/admin_api/version_api.md similarity index 100% rename from docs/admin_api/version_api.md rename to docs/administration/admin_api/version_api.md diff --git a/docs/usage/administration/admin_faq.md b/docs/administration/admin_faq.md similarity index 93% rename from docs/usage/administration/admin_faq.md rename to docs/administration/admin_faq.md index 7ba5a83f0446..262bd65fe840 100644 --- a/docs/usage/administration/admin_faq.md +++ b/docs/administration/admin_faq.md @@ -2,7 +2,7 @@ How do I become a server admin? --- -If your server already has an admin account you should use the [User Admin API](../../admin_api/user_admin_api.md#Change-whether-a-user-is-a-server-administrator-or-not) to promote other accounts to become admins. +If your server already has an admin account you should use the [User Admin API](../../administration/admin_api/user_admin_api.md#Change-whether-a-user-is-a-server-administrator-or-not) to promote other accounts to become admins. If you don't have any admin accounts yet you won't be able to use the admin API, so you'll have to edit the database manually. Manually editing the database is generally not recommended so once you have an admin account: use the admin APIs to make further changes. @@ -35,7 +35,7 @@ SELECT NAME from users; Manually resetting passwords --- Users can reset their password through their client. Alternatively, a server admin -can reset a user's password using the [admin API](../../admin_api/user_admin_api.md#reset-password). +can reset a user's password using the [admin API](../../administration/admin_api/user_admin_api.md#reset-password). I have a problem with my server. Can I just delete my database and start again? @@ -101,7 +101,7 @@ ORDER BY num_rows desc LIMIT 10; ``` -You can also use the [List Room API](../../admin_api/rooms.md#list-room-api) +You can also use the [List Room API](../../administration/admin_api/rooms.md#list-room-api) and `order_by` `state_events`. @@ -115,14 +115,14 @@ something like the following in their logs: 2019-09-11 19:32:04,271 - synapse.federation.transport.server - 288 - WARNING - GET-11752 - authenticate_request failed: 401: Invalid signature for server with key ed25519:a_EqML: Unable to verify signature for -This is normally caused by a misconfiguration in your reverse-proxy. See [the reverse proxy docs](docs/reverse_proxy.md) and double-check that your settings are correct. +This is normally caused by a misconfiguration in your reverse-proxy. See [the reverse proxy docs](../setup/reverse_proxy.md) and double-check that your settings are correct. Help!! Synapse is slow and eats all my RAM/CPU! ----------------------------------------------- First, ensure you are running the latest version of Synapse, using Python 3 -with a [PostgreSQL database](../../postgres.md). +with a [PostgreSQL database](../setup/postgres.md). Synapse's architecture is quite RAM hungry currently - we deliberately cache a lot of recent room data and metadata in RAM in order to speed up @@ -157,7 +157,7 @@ massive excess of outgoing federation requests (see [discussion](https://github. indicate that your server is also issuing far more outgoing federation requests than can be accounted for by your users' activity, this is a likely cause. The misbehavior can be worked around by disabling presence -in the Synapse config file: [see here](../configuration/config_documentation.md#presence). +in the Synapse config file: [see here](../usage/configuration/config_documentation.md#presence). Running out of File Handles diff --git a/docs/usage/administration/database_maintenance_tools.md b/docs/administration/database_maintenance_tools.md similarity index 73% rename from docs/usage/administration/database_maintenance_tools.md rename to docs/administration/database_maintenance_tools.md index 92b805d413cb..c6cf0c990e5f 100644 --- a/docs/usage/administration/database_maintenance_tools.md +++ b/docs/administration/database_maintenance_tools.md @@ -2,13 +2,13 @@ This blog post by Victor Berger explains how to use many of the tools listed on # List of useful tools and scripts for maintenance Synapse database: -## [Purge Remote Media API](../../admin_api/media_admin_api.md#purge-remote-media-api) +## [Purge Remote Media API](../../administration/admin_api/media_admin_api.md#purge-remote-media-api) The purge remote media API allows server admins to purge old cached remote media. -## [Purge Local Media API](../../admin_api/media_admin_api.md#delete-local-media) +## [Purge Local Media API](../../administration/admin_api/media_admin_api.md#delete-local-media) This API deletes the *local* media from the disk of your own server. -## [Purge History API](../../admin_api/purge_history_api.md) +## [Purge History API](../../administration/admin_api/purge_history_api.md) The purge history API allows server admins to purge historic events from their database, reclaiming disk space. ## [synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state) diff --git a/docs/manhole.md b/docs/administration/manhole.md similarity index 97% rename from docs/manhole.md rename to docs/administration/manhole.md index 4e5bf833ce55..1d04fc244cfb 100644 --- a/docs/manhole.md +++ b/docs/administration/manhole.md @@ -15,7 +15,7 @@ environments where untrusted users have shell access. To enable it, first add the `manhole` listener configuration in your `homeserver.yaml`. You can find information on how to do that -in the [configuration manual](usage/configuration/config_documentation.md#manhole_settings). +in the [configuration manual](../usage/configuration/config_documentation.md#manhole_settings). The configuration is slightly different if you're using docker. #### Docker config diff --git a/docs/metrics-howto.md b/docs/administration/metrics-howto.md similarity index 99% rename from docs/metrics-howto.md rename to docs/administration/metrics-howto.md index 8f1f11f2b2e5..c9156f2783aa 100644 --- a/docs/metrics-howto.md +++ b/docs/administration/metrics-howto.md @@ -92,7 +92,7 @@ ## Monitoring workers -To monitor a Synapse installation using [workers](workers.md), +To monitor a Synapse installation using [workers](../usage/configuration/workers.md), every worker needs to be monitored independently, in addition to the main homeserver process. This is because workers don't send their metrics to the main homeserver process, but expose them diff --git a/docs/usage/administration/monthly_active_users.md b/docs/administration/monthly_active_users.md similarity index 95% rename from docs/usage/administration/monthly_active_users.md rename to docs/administration/monthly_active_users.md index d4e90372846a..c0e233d23413 100644 --- a/docs/usage/administration/monthly_active_users.md +++ b/docs/administration/monthly_active_users.md @@ -3,11 +3,11 @@ Synapse can be configured to record the number of monthly active users (also referred to as MAU) on a given homeserver. For clarity's sake, MAU only tracks local users. -Please note that the metrics recorded by the [Homeserver Usage Stats](../../usage/administration/monitoring/reporting_homeserver_usage_statistics.md) +Please note that the metrics recorded by the [Homeserver Usage Stats](reporting_homeserver_usage_statistics.md) are calculated differently. The `monthly_active_users` from the usage stats does not take into account any of the rules below, and counts any users who have made a request to the homeserver in the last 30 days. -See the [configuration manual](../../usage/configuration/config_documentation.md#limit_usage_by_mau) for details on how to configure MAU. +See the [configuration manual](../usage/configuration/config_documentation.md#limit_usage_by_mau) for details on how to configure MAU. ## Calculating active users diff --git a/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md b/docs/administration/reporting_homeserver_usage_statistics.md similarity index 96% rename from docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md rename to docs/administration/reporting_homeserver_usage_statistics.md index 4e53f9883a5d..7f3b1245290a 100644 --- a/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md +++ b/docs/administration/reporting_homeserver_usage_statistics.md @@ -6,9 +6,9 @@ provide the foundation a glimpse into the number of Synapse homeservers participating in the network, as well as statistics such as the number of rooms being created and messages being sent. This feature is sometimes affectionately called "phone home" stats. Reporting -[is optional](../../configuration/config_documentation.md#report_stats) +[is optional](../usage/configuration/config_documentation.md#report_stats) and the reporting endpoint -[can be configured](../../configuration/config_documentation.md#report_stats_endpoint), +[can be configured](../usage/configuration/config_documentation.md#report_stats_endpoint), in case you would like to instead report statistics from a set of homeservers to your own infrastructure. @@ -52,15 +52,15 @@ The following statistics are sent to the configured reporting endpoint: | `r30v2_users_ios` | int | The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "ios" (case-insensitive) in the user agent string. | | `r30v2_users_electron` | int | The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "electron" (case-insensitive) in the user agent string. | | `r30v2_users_web` | int | The number of 30 day retained users, as defined above. Filtered only to clients with "mozilla" or "gecko" (case-insensitive) in the user agent string. | -| `cache_factor` | int | The configured [`global factor`](../../configuration/config_documentation.md#caching) value for caching. | -| `event_cache_size` | int | The configured [`event_cache_size`](../../configuration/config_documentation.md#caching) value for caching. | +| `cache_factor` | int | The configured [`global factor`](../usage/configuration/config_documentation.md#caching) value for caching. | +| `event_cache_size` | int | The configured [`event_cache_size`](../usage/configuration/config_documentation.md#caching) value for caching. | | `database_engine` | string | The database engine that is in use. Either "psycopg2" meaning PostgreSQL is in use, or "sqlite3" for SQLite3. | | `database_server_version` | string | The version of the database server. Examples being "10.10" for PostgreSQL server version 10.0, and "3.38.5" for SQLite 3.38.5 installed on the system. | | `log_level` | string | The log level in use. Examples are "INFO", "WARNING", "ERROR", "DEBUG", etc. | [^1]: Native matrix users and guests are always counted. If the -[`track_puppeted_user_ips`](../../configuration/config_documentation.md#track_puppeted_user_ips) +[`track_puppeted_user_ips`](../usage/configuration/config_documentation.md#track_puppeted_user_ips) option is set to `true`, "puppeted" users (users that an Application Service have performed [an action on behalf of](https://spec.matrix.org/v1.3/application-service-api/#identity-assertion)) will also be counted. Note that an Application Service can "puppet" any user in their @@ -71,7 +71,7 @@ will additionally be counted as a user (irrespective of `track_puppeted_user_ips ## Using a Custom Statistics Collection Server If statistics reporting is enabled, the endpoint that Synapse sends metrics to is configured by the -[`report_stats_endpoint`](../../configuration/config_documentation.md#report_stats_endpoint) config +[`report_stats_endpoint`](../usage/configuration/config_documentation.md#report_stats_endpoint) config option. By default, statistics are sent to Matrix.org. If you would like to set up your own statistics collection server and send metrics there, you may diff --git a/docs/usage/administration/request_log.md b/docs/administration/request_log.md similarity index 95% rename from docs/usage/administration/request_log.md rename to docs/administration/request_log.md index 82f5ac7b96a5..4b262878b6c0 100644 --- a/docs/usage/administration/request_log.md +++ b/docs/administration/request_log.md @@ -1,6 +1,6 @@ # Request log format -HTTP request logs are written by synapse (see [`site.py`](../synapse/http/site.py) for details). +HTTP request logs are written by synapse (see [`site.py`](https://github.com/matrix-org/synapse/blob/latest/synapse/http/site.py) for details). See the following for how to decode the dense data available from the default logging configuration. diff --git a/docs/usage/administration/state_groups.md b/docs/administration/state_groups.md similarity index 100% rename from docs/usage/administration/state_groups.md rename to docs/administration/state_groups.md diff --git a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md b/docs/administration/understanding_synapse_through_grafana_graphs.md similarity index 97% rename from docs/usage/administration/understanding_synapse_through_grafana_graphs.md rename to docs/administration/understanding_synapse_through_grafana_graphs.md index c365cc392309..56d47adf6e93 100644 --- a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md +++ b/docs/administration/understanding_synapse_through_grafana_graphs.md @@ -2,7 +2,7 @@ It is possible to monitor much of the internal state of Synapse using [Prometheus](https://prometheus.io) metrics and [Grafana](https://grafana.com/). -A guide for configuring Synapse to provide metrics is available [here](../../metrics-howto.md) +A guide for configuring Synapse to provide metrics is available [here](../../administration/metrics-howto.md) and information on setting up Grafana is [here](https://github.com/matrix-org/synapse/tree/master/contrib/grafana). In this setup, Prometheus will periodically scrape the information Synapse provides and store a record of it over time. Grafana is then used as an interface to query and @@ -79,6 +79,6 @@ indicator of problems, and a symptom of other problems though, so check other gr If you're still having performance problems with your Synapse instance and you've tried everything you can, it may just be a lack of system resources. Consider adding -more CPU and RAM, and make use of [worker mode](../../workers.md) +more CPU and RAM, and make use of [worker mode](../usage/configuration/workers.md) to make use of multiple CPU cores / multiple machines for your homeserver. diff --git a/docs/usage/administration/useful_sql_for_admins.md b/docs/administration/useful_sql_for_admins.md similarity index 100% rename from docs/usage/administration/useful_sql_for_admins.md rename to docs/administration/useful_sql_for_admins.md diff --git a/docs/code_style.md b/docs/development/code_style.md similarity index 98% rename from docs/code_style.md rename to docs/development/code_style.md index d65fda62d140..3fb98d7cb7ce 100644 --- a/docs/code_style.md +++ b/docs/development/code_style.md @@ -75,7 +75,7 @@ on save as they take a while and can be very resource intensive. When adding a configuration option to the code, if several settings are grouped into a single dict, ensure that your code correctly handles the top-level option being set to `None` (as it will be if no sub-options are enabled). -The [configuration manual](usage/configuration/config_documentation.md) acts as a +The [configuration manual](../usage/configuration/config_documentation.md) acts as a reference to Synapse's configuration options for server administrators. Remember that many readers will be unfamiliar with YAML and server administration in general, so it is important that when you add diff --git a/docs/development/contributing_guide.md b/docs/development/contributing_guide.md index 1e52f9808c8d..91488d7f7323 100644 --- a/docs/development/contributing_guide.md +++ b/docs/development/contributing_guide.md @@ -103,9 +103,9 @@ Synapse developers. regarding Synapse's Admin API, which is used mostly by sysadmins and external service developers. -Synapse's code style is documented [here](../code_style.md). Please follow +Synapse's code style is documented [here](code_style.md). Please follow it, including the conventions for the [sample configuration -file](../code_style.md#configuration-file-format). +file](code_style.md#configuration-file-format). We welcome improvements and additions to our documentation itself! When writing new pages, please diff --git a/docs/auth_chain_diff.dot b/docs/development/internal_documentation/auth_chain_diff.dot similarity index 100% rename from docs/auth_chain_diff.dot rename to docs/development/internal_documentation/auth_chain_diff.dot diff --git a/docs/auth_chain_diff.dot.png b/docs/development/internal_documentation/auth_chain_diff.dot.png similarity index 100% rename from docs/auth_chain_diff.dot.png rename to docs/development/internal_documentation/auth_chain_diff.dot.png diff --git a/docs/auth_chain_difference_algorithm.md b/docs/development/internal_documentation/auth_chain_difference_algorithm.md similarity index 100% rename from docs/auth_chain_difference_algorithm.md rename to docs/development/internal_documentation/auth_chain_difference_algorithm.md diff --git a/docs/development/cas.md b/docs/development/internal_documentation/cas.md similarity index 100% rename from docs/development/cas.md rename to docs/development/internal_documentation/cas.md diff --git a/docs/media_repository.md b/docs/development/internal_documentation/media_repository.md similarity index 100% rename from docs/media_repository.md rename to docs/development/internal_documentation/media_repository.md diff --git a/docs/development/room-dag-concepts.md b/docs/development/internal_documentation/room-dag-concepts.md similarity index 100% rename from docs/development/room-dag-concepts.md rename to docs/development/internal_documentation/room-dag-concepts.md diff --git a/docs/room_and_user_statistics.md b/docs/development/internal_documentation/room_and_user_statistics.md similarity index 100% rename from docs/room_and_user_statistics.md rename to docs/development/internal_documentation/room_and_user_statistics.md diff --git a/docs/development/saml.md b/docs/development/internal_documentation/saml.md similarity index 100% rename from docs/development/saml.md rename to docs/development/internal_documentation/saml.md diff --git a/docs/opentracing.md b/docs/development/opentracing.md similarity index 97% rename from docs/opentracing.md rename to docs/development/opentracing.md index abb94b565f21..26e5c8b605c6 100644 --- a/docs/opentracing.md +++ b/docs/development/opentracing.md @@ -58,7 +58,7 @@ https://www.jaegertracing.io/docs/latest/getting-started. OpenTracing is not enabled by default. It must be enabled in the homeserver config by adding the `opentracing` option to your config file. You can find -documentation about how to do this in the [config manual under the header 'Opentracing'](usage/configuration/config_documentation.md#opentracing). +documentation about how to do this in the [config manual under the header 'Opentracing'](../usage/configuration/config_documentation.md#opentracing). See below for an example Opentracing configuration: ```yaml diff --git a/docs/log_contexts.md b/docs/development/synapse_architecture/log_contexts.md similarity index 100% rename from docs/log_contexts.md rename to docs/development/synapse_architecture/log_contexts.md diff --git a/docs/ancient_architecture_notes.md b/docs/development/synapse_architecture/old/ancient_architecture_notes.md similarity index 100% rename from docs/ancient_architecture_notes.md rename to docs/development/synapse_architecture/old/ancient_architecture_notes.md diff --git a/docs/architecture.md b/docs/development/synapse_architecture/old/architecture.md similarity index 100% rename from docs/architecture.md rename to docs/development/synapse_architecture/old/architecture.md diff --git a/docs/replication.md b/docs/development/synapse_architecture/replication.md similarity index 100% rename from docs/replication.md rename to docs/development/synapse_architecture/replication.md diff --git a/docs/tcp_replication.md b/docs/development/synapse_architecture/tcp_replication.md similarity index 100% rename from docs/tcp_replication.md rename to docs/development/synapse_architecture/tcp_replication.md diff --git a/docs/deprecation_policy.md b/docs/other/deprecation_policy.md similarity index 100% rename from docs/deprecation_policy.md rename to docs/other/deprecation_policy.md diff --git a/docs/other/running_synapse_on_single_board_computers.md b/docs/other/running_synapse_on_single_board_computers.md index dcf96f0056ba..b137537bf62f 100644 --- a/docs/other/running_synapse_on_single_board_computers.md +++ b/docs/other/running_synapse_on_single_board_computers.md @@ -20,7 +20,7 @@ Joining a "large", federated room will initially fail with the below message in ![Screenshot_2020-10-02_17-15-06](https://user-images.githubusercontent.com/71895/94945781-18771500-04d3-11eb-8419-83c2da73a341.png) -This is [#1211](https://github.com/matrix-org/synapse/issues/1211) and will also hopefully be mitigated by peeking [matrix-org/matrix-doc#2753](https://github.com/matrix-org/matrix-doc/pull/2753) so at least you don't need to wait for a join to complete before finding out if it's the kind of room you want. Note that you should first disable presence, otherwise it'll just make the situation worse [#3120](https://github.com/matrix-org/synapse/issues/3120). There is a lot of database interaction too, so make sure you've [migrated your data](../postgres.md) from the default sqlite to postgresql. Personally, I recommend patience - once the initial join is complete there's rarely any issues with actually interacting with the room, but if you like you can just block "large" rooms entirely. +This is [#1211](https://github.com/matrix-org/synapse/issues/1211) and will also hopefully be mitigated by peeking [matrix-org/matrix-doc#2753](https://github.com/matrix-org/matrix-doc/pull/2753) so at least you don't need to wait for a join to complete before finding out if it's the kind of room you want. Note that you should first disable presence, otherwise it'll just make the situation worse [#3120](https://github.com/matrix-org/synapse/issues/3120). There is a lot of database interaction too, so make sure you've [migrated your data](../setup/postgres.md) from the default sqlite to postgresql. Personally, I recommend patience - once the initial join is complete there's rarely any issues with actually interacting with the room, but if you like you can just block "large" rooms entirely. ### Sessions diff --git a/docs/presence_router_module.md b/docs/presence_router_module.md index face54fe2bb3..4cff8236ae0b 100644 --- a/docs/presence_router_module.md +++ b/docs/presence_router_module.md @@ -36,7 +36,7 @@ presence to (for those users that the receiving user is considered interested in It does not include state for users who are currently offline, and it can only be called on workers that support sending federation. Additionally, this method must only be called from the process that has been configured to write to the -the [presence stream](workers.md#stream-writers). +the [presence stream](usage/configuration/workers.md#stream-writers). By default, this is the main process, but another worker can be configured to do so. diff --git a/docs/delegate.md b/docs/setup/delegate.md similarity index 100% rename from docs/delegate.md rename to docs/setup/delegate.md diff --git a/docs/setup/installation.md b/docs/setup/installation.md index dcd8f17c5e98..d1a4970c0198 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 @@ -392,7 +392,7 @@ instead. Advantages include: - allowing the DB to be run on separate hardware For information on how to install and use PostgreSQL in Synapse, please see -[Using Postgres](../postgres.md) +[Using Postgres](postgres.md) SQLite is only acceptable for testing purposes. SQLite should not be used in a production server. Synapse will perform poorly when using @@ -407,7 +407,7 @@ over HTTPS. The recommended way to do so is to set up a reverse proxy on port `8448`. You can find documentation on doing so in -[the reverse proxy documentation](../reverse_proxy.md). +[the reverse proxy documentation](reverse_proxy.md). Alternatively, you can configure Synapse to expose an HTTPS port. To do so, you will need to edit `homeserver.yaml`, as follows: @@ -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 @@ -553,7 +553,7 @@ it can register users, including admin accounts, on your server even if ### Setting up a TURN server For reliable VoIP calls to be routed via this homeserver, you MUST configure -a TURN server. See [TURN setup](../turn-howto.md) for details. +a TURN server. See [TURN setup](turn-howto.md) for details. ### URL previews diff --git a/docs/postgres.md b/docs/setup/postgres.md similarity index 98% rename from docs/postgres.md rename to docs/setup/postgres.md index f2519f6b0a63..534f6f58fbf8 100644 --- a/docs/postgres.md +++ b/docs/setup/postgres.md @@ -8,14 +8,14 @@ Synapse will require the python postgres client library in order to connect to a postgres database. - If you are using the [matrix.org debian/ubuntu - packages](setup/installation.md#matrixorg-packages), the necessary python + packages](installation.md#matrixorg-packages), the necessary python library will already be installed, but you will need to ensure the low-level postgres library is installed, which you can do with `apt install libpq5`. - For other pre-built packages, please consult the documentation from the relevant package. - If you installed synapse [in a - virtualenv](setup/installation.md#installing-from-source), you can install + virtualenv](installation.md#installing-from-source), you can install the library with: ~/synapse/env/bin/pip install "matrix-synapse[postgres]" diff --git a/docs/reverse_proxy.md b/docs/setup/reverse_proxy.md similarity index 100% rename from docs/reverse_proxy.md rename to docs/setup/reverse_proxy.md diff --git a/docs/turn-howto.md b/docs/setup/turn-howto.md similarity index 100% rename from docs/turn-howto.md rename to docs/setup/turn-howto.md diff --git a/docs/upgrade.md b/docs/upgrade.md index b81385b19183..ed7c1595846a 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -204,7 +204,7 @@ which relays replication commands between processes. This can give a significant CPU saving on the main process and is a prerequisite for upcoming performance improvements. -To migrate to Redis add the [`redis` config](./workers.md#shared-configuration), +To migrate to Redis add the [`redis` config](usage/configuration/workers.md#shared-configuration), and remove the TCP `replication` listener from config of the master and `worker_replication_port` from worker config. Note that a HTTP listener with a `replication` resource is still required. @@ -507,8 +507,8 @@ Please see the [*Notifying Application Services*][v1_59_notify_ases_from] and [*Updating the User Directory*][v1_59_update_user_dir] sections of the worker documentation for more information. -[v1_59_notify_ases_from]: workers.md#notifying-application-services -[v1_59_update_user_dir]: workers.md#updating-the-user-directory +[v1_59_notify_ases_from]: usage/configuration/workers.md#notifying-application-services +[v1_59_update_user_dir]: usage/configuration/workers.md#updating-the-user-directory # Upgrading to v1.58.0 @@ -726,7 +726,7 @@ will become a configuration error in Synapse v1.53.0. ## Dropping support for old Python and Postgres versions -In line with our [deprecation policy](deprecation_policy.md), +In line with our [deprecation policy](other/deprecation_policy.md), we've dropped support for Python 3.6 and PostgreSQL 9.6, as they are no longer supported upstream. @@ -797,8 +797,8 @@ Any scripts still using the above APIs should be converted to use the ## User-interactive authentication fallback templates can now display errors This may affect you if you make use of custom HTML templates for the -[reCAPTCHA](../synapse/res/templates/recaptcha.html) or -[terms](../synapse/res/templates/terms.html) fallback pages. +[reCAPTCHA](https://github.com/matrix-org/synapse/blob/v1.42.0/synapse/res/templates/recaptcha.html) or +[terms](https://github.com/matrix-org/synapse/blob/v1.42.0/synapse/res/templates/terms.html) fallback pages. The template is now provided an `error` variable if the authentication process failed. See the default templates linked above for an example. @@ -983,7 +983,7 @@ Instructions for doing so are provided ## Dropping support for old Python, Postgres and SQLite versions -In line with our [deprecation policy](deprecation_policy.md), +In line with our [deprecation policy](other/deprecation_policy.md), we've dropped support for Python 3.5 and PostgreSQL 9.5, as they are no longer supported upstream. @@ -996,7 +996,7 @@ The deprecated v1 "list accounts" admin API (`GET /_synapse/admin/v1/users/`) has been removed in this version. -The [v2 list accounts API](admin_api/user_admin_api.md#list-accounts) +The [v2 list accounts API](administration/admin_api/user_admin_api.md#list-accounts) has been available since Synapse 1.7.0 (2019-12-13), and is accessible under `GET /_synapse/admin/v2/users`. @@ -1031,7 +1031,7 @@ by the client. Synapse also requires the `Host` header to be preserved. -See the [reverse proxy documentation](reverse_proxy.md), where the +See the [reverse proxy documentation](setup/reverse_proxy.md), where the example configurations have been updated to show how to set these headers. @@ -1050,7 +1050,7 @@ identity providers: `[synapse public baseurl]/_synapse/client/oidc/callback` to the list of permitted "redirect URIs" at the identity provider. - See the [OpenID docs](openid.md) for more information on setting + See the [OpenID docs](usage/configuration/user_authentication/single_sign_on/openid.md) for more information on setting up OpenID Connect. - If your server is configured for single sign-on via a SAML2 identity @@ -1280,13 +1280,13 @@ acts the same as the `http_client` argument previously passed to ## Forwarding `/_synapse/client` through your reverse proxy -The [reverse proxy documentation](reverse_proxy.md) +The [reverse proxy documentation](setup/reverse_proxy.md) has been updated to include reverse proxy directives for `/_synapse/client/*` endpoints. As the user password reset flow now uses endpoints under this prefix, **you must update your reverse proxy configurations for user password reset to work**. -Additionally, note that the [Synapse worker documentation](workers.md) has been updated to +Additionally, note that the [Synapse worker documentation](usage/configuration/workers.md) has been updated to : state that the `/_synapse/client/password_reset/email/submit_token` endpoint can be handled @@ -1396,7 +1396,7 @@ New templates (`sso_auth_confirm.html`, `sso_auth_success.html`, and is configured to use SSO and a custom `sso_redirect_confirm_template_dir` configuration then these templates will need to be copied from -[synapse/res/templates](synapse/res/templates) into that directory. +[synapse/res/templates](https://github.com/matrix-org/synapse/tree/v1.13/synapse/res/templates) into that directory. ## Synapse SSO Plugins Method Deprecation @@ -1482,7 +1482,7 @@ participating in many rooms. omitting the `CONCURRENTLY` keyword. Note however that this operation may in itself cause Synapse to stop running for some time. Synapse admins are reminded that [SQLite is not recommended for use - outside a test environment](postgres.md). + outside a test environment](setup/postgres.md). 3. Once the index has been created, the `SELECT` query in step 1 above should complete quickly. It is therefore safe to upgrade to Synapse @@ -1500,7 +1500,7 @@ participating in many rooms. Synapse will now log a warning on start up if used with a PostgreSQL database that has a non-recommended locale set. -See [Postgres](postgres.md) for details. +See [Postgres](setup/postgres.md) for details. # Upgrading to v1.8.0 @@ -1720,7 +1720,7 @@ back to v1.3.1, subject to the following: Some counter metrics have been renamed, with the old names deprecated. See [the metrics -documentation](metrics-howto.md#renaming-of-metrics--deprecation-of-old-names-in-12) +documentation](administration/metrics-howto.md#renaming-of-metrics--deprecation-of-old-names-in-12) for details. # Upgrading to v1.1.0 diff --git a/docs/CAPTCHA_SETUP.md b/docs/usage/configuration/CAPTCHA_SETUP.md similarity index 100% rename from docs/CAPTCHA_SETUP.md rename to docs/usage/configuration/CAPTCHA_SETUP.md diff --git a/docs/application_services.md b/docs/usage/configuration/application_services.md similarity index 100% rename from docs/application_services.md rename to docs/usage/configuration/application_services.md diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index d81eda52c156..2490e10f5ef9 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -115,7 +115,7 @@ usernames on your server would be in the format `@user:example.com` In most cases you should avoid using a matrix specific subdomain such as matrix.example.com or synapse.example.com as the `server_name` for the same reasons you wouldn't use user@email.example.com as your email address. -See [here](../../delegate.md) +See [here](../../setup/delegate.md) for information on how to host Synapse on a subdomain while preserving a clean `server_name`. @@ -179,7 +179,7 @@ This will tell other servers to send traffic to port 443 instead. This option currently defaults to false. -See [Delegation of incoming federation traffic](../../delegate.md) for more +See [Delegation of incoming federation traffic](../../setup/delegate.md) for more information. Example configuration: @@ -427,21 +427,21 @@ Sub-options for each listener include: * `type`: the type of listener. Normally `http`, but other valid options are: - * `manhole`: (see the docs [here](../../manhole.md)), + * `manhole`: (see the docs [here](../../administration/manhole.md)), - * `metrics`: (see the docs [here](../../metrics-howto.md)), + * `metrics`: (see the docs [here](../../administration/metrics-howto.md)), * `tls`: set to true to enable TLS for this listener. Will use the TLS key/cert specified in tls_private_key_path / tls_certificate_path. * `x_forwarded`: Only valid for an 'http' listener. Set to true to use the X-Forwarded-For header as the client IP. Useful when Synapse is - behind a [reverse-proxy](../../reverse_proxy.md). + behind a [reverse-proxy](../../setup/reverse_proxy.md). * `request_id_header`: The header extracted from each incoming request that is used as the basis for the request ID. The request ID is used in - [logs](../administration/request_log.md#request-log-format) and tracing to + [logs](../../administration/request_log.md#request-log-format) and tracing to correlate and match up requests. When unset, Synapse will automatically generate sequential request IDs. This option is useful when Synapse is behind - a [reverse-proxy](../../reverse_proxy.md). + a [reverse-proxy](../../setup/reverse_proxy.md). _Added in Synapse 1.68.0._ @@ -460,7 +460,7 @@ Valid resource names are: * `client`: the client-server API (/_matrix/client), and the synapse admin API (/_synapse/admin). Also implies `media` and `static`. -* `consent`: user consent forms (/_matrix/consent). See [here](../../consent_tracking.md) for more. +* `consent`: user consent forms (/_matrix/consent). See [here](consent_tracking.md) for more. * `federation`: the server-server API (/_matrix/federation). Also implies `media`, `keys`, `openid` @@ -468,11 +468,11 @@ Valid resource names are: * `media`: the media API (/_matrix/media). -* `metrics`: the metrics interface. See [here](../../metrics-howto.md). +* `metrics`: the metrics interface. See [here](../../administration/metrics-howto.md). -* `openid`: OpenID authentication. See [here](../../openid.md). +* `openid`: OpenID authentication. See [here](user_authentication/single_sign_on/openid.md). -* `replication`: the HTTP replication API (/_synapse/replication). See [here](../../workers.md). +* `replication`: the HTTP replication API (/_synapse/replication). See [here](workers.md). * `static`: static resources under synapse/static (/_matrix/static). (Mostly useful for 'fallback authentication'.) @@ -525,7 +525,7 @@ listeners: ### `manhole_settings` Connection settings for the manhole. You can find more information -on the manhole [here](../../manhole.md). Manhole sub-options include: +on the manhole [here](../../administration/manhole.md). Manhole sub-options include: * `username` : the username for the manhole. This defaults to 'matrix'. * `password`: The password for the manhole. This defaults to 'rabbithole'. * `ssh_priv_key_path` and `ssh_pub_key_path`: The private and public SSH key pair used to encrypt the manhole traffic. @@ -602,7 +602,7 @@ server owner wants to limit to the number of monthly active users. When enabled reached the server returns a `ResourceLimitError` with error type `Codes.RESOURCE_LIMIT_EXCEEDED`. Defaults to false. If this is enabled, a value for `max_mau_value` must also be set. -See [Monthly Active Users](../administration/monthly_active_users.md) for details on how to configure MAU. +See [Monthly Active Users](../../administration/monthly_active_users.md) for details on how to configure MAU. Example configuration: ```yaml @@ -835,7 +835,7 @@ find template files in to use to generate email or HTML page contents. If not set, or a file is not found within the template directory, a default template from within the Synapse package will be used. -See [here](../../templates.md) for more +See [here](templates.md) for more information about using custom templates. Example configuration: @@ -862,7 +862,7 @@ The message retention policies feature is disabled by default. Please be advised that enabling this feature carries some risk. There are known bugs with the implementation which can cause database corruption. Setting retention to delete older history is less risky than deleting newer history but in general caution is advised when enabling this -experimental feature. You can read more about this feature [here](../../message_retention_policies.md). +experimental feature. You can read more about this feature [here](message_retention_policies.md). This setting has the following sub-options: * `default_policy`: Default retention policy. If set, Synapse will apply it to rooms that lack the @@ -1139,7 +1139,7 @@ number of entries that can be stored. * `cache_autotuning` and its sub-options `max_cache_memory_usage`, `target_cache_memory_usage`, and `min_cache_ttl` work in conjunction with each other to maintain a balance between cache memory - usage and cache entry availability. You must be using [jemalloc](../administration/admin_faq.md#help-synapse-is-slow-and-eats-all-my-ramcpu) + usage and cache entry availability. You must be using [jemalloc](../../administration/admin_faq.md#help-synapse-is-slow-and-eats-all-my-ramcpu) to utilize this option, and all three of the options must be specified for this feature to work. This option defaults to off, enable it by providing values for the sub-options listed below. Please note that the feature will not work and may cause unstable behavior (such as excessive emptying of caches or exceptions) if all of the values are not provided. @@ -1205,7 +1205,7 @@ Associated sub-options: * `allow_unsafe_locale` is an option specific to Postgres. Under the default behavior, Synapse will refuse to start if the postgres db is set to a non-C locale. You can override this behavior (which is *not* recommended) by setting `allow_unsafe_locale` to true. Note that doing so may corrupt your database. You can find more information - [here](../../postgres.md#fixing-incorrect-collate-or-ctype) and [here](https://wiki.postgresql.org/wiki/Locale_data_changes). + [here](../../setup/postgres.md#fixing-incorrect-collate-or-ctype) and [here](https://wiki.postgresql.org/wiki/Locale_data_changes). * `args` gives options which are passed through to the database engine, except for options starting with `cp_`, which are used to configure the Twisted @@ -1215,7 +1215,7 @@ Associated sub-options: * for [the connection pool](https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__) For more information on using Synapse with Postgres, -see [here](../../postgres.md). +see [here](../../setup/postgres.md). Example SQLite configuration: ```yaml @@ -1626,7 +1626,7 @@ The largest allowed upload size in bytes. If you are using a reverse proxy you may also need to set this value in your reverse proxy's config. Defaults to 50M. Notably Nginx has a small max body size by default. -See [here](../../reverse_proxy.md) for more on using a reverse proxy with Synapse. +See [here](../../setup/reverse_proxy.md) for more on using a reverse proxy with Synapse. Example configuration: ```yaml @@ -1702,9 +1702,9 @@ and the original media will be removed. If either of these options are unset, then media of that type will not be purged. Local or cached remote media that has been -[quarantined](../../admin_api/media_admin_api.md#quarantining-media-in-a-room) +[quarantined](../../administration/admin_api/media_admin_api.md#quarantining-media-in-a-room) will not be deleted. Similarly, local media that has been marked as -[protected from quarantine](../../admin_api/media_admin_api.md#protecting-media-from-being-quarantined) +[protected from quarantine](../../administration/admin_api/media_admin_api.md#protecting-media-from-being-quarantined) will not be deleted. Example configuration: @@ -1879,7 +1879,7 @@ oembed: --- ## Captcha ## -See [here](../../CAPTCHA_SETUP.md) for full details on setting up captcha. +See [here](CAPTCHA_SETUP.md) for full details on setting up captcha. --- ### `recaptcha_public_key` @@ -2068,7 +2068,7 @@ enable_3pid_lookup: false ### `registration_requires_token` Require users to submit a token during registration. -Tokens can be managed using the admin [API](../administration/admin_api/registration_tokens.md). +Tokens can be managed using the admin [API](../../administration/admin_api/registration_tokens.md). Disabling this option will not delete any tokens previously generated. Defaults to `false`. Set to `true` to enable. @@ -2088,7 +2088,7 @@ set. This is primarily intended for use with the `register_new_matrix_user` script (see [Registering a user](../../setup/installation.md#registering-a-user)); -however, the interface is [documented](../../admin_api/register_api.html). +however, the interface is [documented](../../administration/admin_api/register_api.md). See also [`registration_shared_secret_path`](#registration_shared_secret_path). @@ -2498,7 +2498,7 @@ metrics_flags: Whether or not to report homeserver usage statistics. This is originally set when generating the config. Set this option to true or false to change the current behavior. See -[Reporting Homeserver Usage Statistics](../administration/monitoring/reporting_homeserver_usage_statistics.md) +[Reporting Homeserver Usage Statistics](../../administration/reporting_homeserver_usage_statistics.md) for information on what data is reported. Statistics will be reported 5 minutes after Synapse starts, and then every 3 hours @@ -2879,7 +2879,7 @@ saml2_config: ### `oidc_providers` List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration -and login. See [here](../../openid.md) +and login. See [here](user_authentication/single_sign_on/openid.md) for information on how to configure these options. For backwards compatibility, it is also possible to configure a single OIDC @@ -2977,7 +2977,7 @@ Options for each entry include: * `module`: The class name of a custom mapping module. Default is `synapse.handlers.oidc.JinjaOidcMappingProvider`. - See [OpenID Mapping Providers](../../sso_mapping_providers.md#openid-mapping-providers) + See [OpenID Mapping Providers](user_authentication/single_sign_on/sso_mapping_providers.md#openid-mapping-providers) for information on implementing a custom mapping provider. * `config`: Configuration for the mapping provider module. This section will @@ -3096,7 +3096,7 @@ Additional settings to use with single-sign on systems such as OpenID Connect, SAML2 and CAS. Server admins can configure custom templates for pages related to SSO. See -[here](../../templates.md) for more information. +[here](templates.md) for more information. Options include: * `client_whitelist`: A list of client URLs which are whitelisted so that the user does not @@ -3142,7 +3142,7 @@ and issued at ("iat") claims are validated if present. Note that this is a non-standard login type and client support is expected to be non-existent. -See [here](../../jwt.md) for more. +See [here](user_authentication/jwt.md) for more. Additional sub-options for this setting include: * `enabled`: Set to true to enable authorization using JSON web @@ -3245,7 +3245,7 @@ ui_auth: Configuration for sending emails from Synapse. Server admins can configure custom templates for email content. See -[here](../../templates.md) for more information. +[here](templates.md) for more information. This setting has the following sub-options: * `smtp_host`: The hostname of the outgoing SMTP server to use. Defaults to 'localhost'. @@ -3425,7 +3425,7 @@ This option has the following sub-options: These indexes are built the first time Synapse starts; admins can manually trigger a rebuild via the API following the instructions - [for running background updates](../administration/admin_api/background_updates.md#run), + [for running background updates](../../administration/admin_api/background_updates.md#run), set to true to return search results containing all known users, even if that user does not share a room with the requester. * `prefer_local_users`: Defines whether to prefer local users in search query results. @@ -3442,7 +3442,7 @@ user_directory: --- ### `user_consent` -For detailed instructions on user consent configuration, see [here](../../consent_tracking.md). +For detailed instructions on user consent configuration, see [here](consent_tracking.md). Parts of this section are required if enabling the `consent` resource under [`listeners`](#listeners), in particular `template_dir` and `version`. @@ -3493,7 +3493,7 @@ user_consent: --- ### `stats` -Settings for local room and user statistics collection. See [here](../../room_and_user_statistics.md) +Settings for local room and user statistics collection. See [here](../../development/internal_documentation/room_and_user_statistics.md) for more. * `enabled`: Set to false to disable room and user statistics. Note that doing @@ -3642,7 +3642,7 @@ synapse or any other services which support opentracing Sub-options include: * `enabled`: whether tracing is enabled. Set to true to enable. Disabled by default. * `homeserver_whitelist`: The list of homeservers we wish to send and receive span contexts and span baggage. - See [here](../../opentracing.md) for more. + See [here](../../development/opentracing.md) for more. This is a list of regexes which are matched against the `server_name` of the homeserver. By default, it is empty, so no servers are matched. * `force_tracing_for_users`: # A list of the matrix IDs of users whose requests will always be traced, diff --git a/docs/consent_tracking.md b/docs/usage/configuration/consent_tracking.md similarity index 100% rename from docs/consent_tracking.md rename to docs/usage/configuration/consent_tracking.md diff --git a/docs/message_retention_policies.md b/docs/usage/configuration/message_retention_policies.md similarity index 98% rename from docs/message_retention_policies.md rename to docs/usage/configuration/message_retention_policies.md index 7f3e5359f155..70d5a61a58d4 100644 --- a/docs/message_retention_policies.md +++ b/docs/usage/configuration/message_retention_policies.md @@ -52,7 +52,7 @@ clients. Support for this feature can be enabled and configured by adding a the `retention` in the Synapse configuration file (see -[configuration manual](usage/configuration/config_documentation.md#retention)). +[configuration manual](config_documentation.md#retention)). To enable support for message retention policies, set the setting `enabled` in this section to `true`. @@ -88,7 +88,7 @@ expired events from the database. They are only run if support for message retention policies is enabled in the server's configuration. If no configuration for purge jobs is configured by the server admin, Synapse will use a default configuration, which is described here in the -[configuration manual](usage/configuration/config_documentation.md#retention). +[configuration manual](config_documentation.md#retention). Some server admins might want a finer control on when events are removed depending on an event's room's policy. This can be done by setting the diff --git a/docs/server_notices.md b/docs/usage/configuration/server_notices.md similarity index 97% rename from docs/server_notices.md rename to docs/usage/configuration/server_notices.md index 339d10a0ab3f..a96f312864fe 100644 --- a/docs/server_notices.md +++ b/docs/usage/configuration/server_notices.md @@ -58,4 +58,4 @@ displayname and avatar of the Server Notices user. ## Sending notices To send server notices to users you can use the -[admin_api](admin_api/server_notices.md). +[admin_api](../../administration/admin_api/server_notices.md). diff --git a/docs/structured_logging.md b/docs/usage/configuration/structured_logging.md similarity index 100% rename from docs/structured_logging.md rename to docs/usage/configuration/structured_logging.md diff --git a/docs/synctl_workers.md b/docs/usage/configuration/synctl_workers.md similarity index 100% rename from docs/synctl_workers.md rename to docs/usage/configuration/synctl_workers.md diff --git a/docs/systemd-with-workers/README.md b/docs/usage/configuration/systemd-with-workers/README.md similarity index 100% rename from docs/systemd-with-workers/README.md rename to docs/usage/configuration/systemd-with-workers/README.md diff --git a/docs/systemd-with-workers/system/matrix-synapse-worker@.service b/docs/usage/configuration/systemd-with-workers/system/matrix-synapse-worker@.service similarity index 100% rename from docs/systemd-with-workers/system/matrix-synapse-worker@.service rename to docs/usage/configuration/systemd-with-workers/system/matrix-synapse-worker@.service diff --git a/docs/systemd-with-workers/system/matrix-synapse.service b/docs/usage/configuration/systemd-with-workers/system/matrix-synapse.service similarity index 100% rename from docs/systemd-with-workers/system/matrix-synapse.service rename to docs/usage/configuration/systemd-with-workers/system/matrix-synapse.service diff --git a/docs/systemd-with-workers/system/matrix-synapse.target b/docs/usage/configuration/systemd-with-workers/system/matrix-synapse.target similarity index 100% rename from docs/systemd-with-workers/system/matrix-synapse.target rename to docs/usage/configuration/systemd-with-workers/system/matrix-synapse.target diff --git a/docs/systemd-with-workers/workers/background_worker.yaml b/docs/usage/configuration/systemd-with-workers/workers/background_worker.yaml similarity index 100% rename from docs/systemd-with-workers/workers/background_worker.yaml rename to docs/usage/configuration/systemd-with-workers/workers/background_worker.yaml diff --git a/docs/systemd-with-workers/workers/event_persister.yaml b/docs/usage/configuration/systemd-with-workers/workers/event_persister.yaml similarity index 100% rename from docs/systemd-with-workers/workers/event_persister.yaml rename to docs/usage/configuration/systemd-with-workers/workers/event_persister.yaml diff --git a/docs/systemd-with-workers/workers/federation_sender.yaml b/docs/usage/configuration/systemd-with-workers/workers/federation_sender.yaml similarity index 100% rename from docs/systemd-with-workers/workers/federation_sender.yaml rename to docs/usage/configuration/systemd-with-workers/workers/federation_sender.yaml diff --git a/docs/systemd-with-workers/workers/generic_worker.yaml b/docs/usage/configuration/systemd-with-workers/workers/generic_worker.yaml similarity index 100% rename from docs/systemd-with-workers/workers/generic_worker.yaml rename to docs/usage/configuration/systemd-with-workers/workers/generic_worker.yaml diff --git a/docs/systemd-with-workers/workers/media_worker.yaml b/docs/usage/configuration/systemd-with-workers/workers/media_worker.yaml similarity index 100% rename from docs/systemd-with-workers/workers/media_worker.yaml rename to docs/usage/configuration/systemd-with-workers/workers/media_worker.yaml diff --git a/docs/systemd-with-workers/workers/pusher_worker.yaml b/docs/usage/configuration/systemd-with-workers/workers/pusher_worker.yaml similarity index 100% rename from docs/systemd-with-workers/workers/pusher_worker.yaml rename to docs/usage/configuration/systemd-with-workers/workers/pusher_worker.yaml diff --git a/docs/templates.md b/docs/usage/configuration/templates.md similarity index 100% rename from docs/templates.md rename to docs/usage/configuration/templates.md diff --git a/docs/jwt.md b/docs/usage/configuration/user_authentication/jwt.md similarity index 96% rename from docs/jwt.md rename to docs/usage/configuration/user_authentication/jwt.md index 2e262583a7ce..6f4cc444bc83 100644 --- a/docs/jwt.md +++ b/docs/usage/configuration/user_authentication/jwt.md @@ -50,7 +50,7 @@ as follows: maintainer. To enable the JSON web token integration, you should then add a `jwt_config` option -to your configuration file. See the [configuration manual](usage/configuration/config_documentation.md#jwt_config) for some +to your configuration file. See the [configuration manual](../config_documentation.md#jwt_config) for some sample settings. ## How to test JWT as a developer diff --git a/docs/password_auth_providers.md b/docs/usage/configuration/user_authentication/password_auth_providers.md similarity index 99% rename from docs/password_auth_providers.md rename to docs/usage/configuration/user_authentication/password_auth_providers.md index dc0dfffa21ab..c85a809a82b6 100644 --- a/docs/password_auth_providers.md +++ b/docs/usage/configuration/user_authentication/password_auth_providers.md @@ -1,7 +1,7 @@

This page of the Synapse documentation is now deprecated. For up to date documentation on setting up or writing a password auth provider module, please see -this page. +this page.

# Password auth provider modules diff --git a/docs/openid.md b/docs/usage/configuration/user_authentication/single_sign_on/openid.md similarity index 99% rename from docs/openid.md rename to docs/usage/configuration/user_authentication/single_sign_on/openid.md index 87ebea4c296f..d2726c2caa85 100644 --- a/docs/openid.md +++ b/docs/usage/configuration/user_authentication/single_sign_on/openid.md @@ -46,7 +46,7 @@ as follows: To enable the OpenID integration, you should then add a section to the `oidc_providers` setting in your configuration file. -See the [configuration manual](usage/configuration/config_documentation.md#oidc_providers) for some sample settings, as well as +See the [configuration manual](../../config_documentation.md#oidc_providers) for some sample settings, as well as the text below for example configurations for specific providers. ## Sample configs diff --git a/docs/sso_mapping_providers.md b/docs/usage/configuration/user_authentication/single_sign_on/sso_mapping_providers.md similarity index 98% rename from docs/sso_mapping_providers.md rename to docs/usage/configuration/user_authentication/single_sign_on/sso_mapping_providers.md index 9f5e5fbbe152..bfb567227eaf 100644 --- a/docs/sso_mapping_providers.md +++ b/docs/usage/configuration/user_authentication/single_sign_on/sso_mapping_providers.md @@ -37,7 +37,7 @@ as Synapse). The Synapse config is then modified to point to the mapping provide ## OpenID Mapping Providers The OpenID mapping provider can be customized by editing the -[`oidc_providers.user_mapping_provider.module`](usage/configuration/config_documentation.md#oidc_providers) +[`oidc_providers.user_mapping_provider.module`](../../config_documentation.md#oidc_providers) config option. `oidc_providers.user_mapping_provider.config` allows you to provide custom @@ -120,7 +120,7 @@ specified in the config. It is located at ## SAML Mapping Providers The SAML mapping provider can be customized by editing the -[`saml2_config.user_mapping_provider.module`](docs/usage/configuration/config_documentation.md#saml2_config) +[`saml2_config.user_mapping_provider.module`](../../config_documentation.md#saml2_config) config option. `saml2_config.user_mapping_provider.config` allows you to provide custom diff --git a/docs/user_directory.md b/docs/usage/configuration/user_directory.md similarity index 97% rename from docs/user_directory.md rename to docs/usage/configuration/user_directory.md index c4794b04cf61..5fa6079ba78b 100644 --- a/docs/user_directory.md +++ b/docs/usage/configuration/user_directory.md @@ -7,7 +7,7 @@ who are present in a publicly viewable room present on the server. The directory info is stored in various tables, which can (typically after DB corruption) get stale or out of sync. If this happens, for now the -solution to fix it is to use the [admin API](usage/administration/admin_api/background_updates.md#run) +solution to fix it is to use the [admin API](../../administration/admin_api/background_updates.md#run) and execute the job `regenerate_directory`. This should then start a background task to flush the current tables and regenerate the directory. diff --git a/docs/workers.md b/docs/usage/configuration/workers.md similarity index 97% rename from docs/workers.md rename to docs/usage/configuration/workers.md index c27b3f8bd56c..f63a9e646957 100644 --- a/docs/workers.md +++ b/docs/usage/configuration/workers.md @@ -68,7 +68,7 @@ https://hub.docker.com/r/matrixdotorg/synapse/. To make effective use of the workers, you will need to configure an HTTP reverse-proxy such as nginx or haproxy, which will direct incoming requests to the correct worker, or to the main synapse instance. See -[the reverse proxy documentation](reverse_proxy.md) for information on setting up a reverse +[the reverse proxy documentation](../../setup/reverse_proxy.md) for information on setting up a reverse proxy. When using workers, each worker process has its own configuration file which @@ -111,7 +111,7 @@ redis: enabled: true ``` -See the [configuration manual](usage/configuration/config_documentation.html) for the full documentation of each option. +See the [configuration manual](config_documentation.md) for the full documentation of each option. Under **no circumstances** should the replication listener be exposed to the public internet; replication traffic is: @@ -128,7 +128,7 @@ In the config file for each worker, you must specify: * The HTTP replication endpoint that it should talk to on the main synapse process (`worker_replication_host` and `worker_replication_http_port`) * If handling HTTP requests, a `worker_listeners` option with an `http` - listener, in the same way as the [`listeners`](usage/configuration/config_documentation.md#listeners) + listener, in the same way as the [`listeners`](config_documentation.md#listeners) option in the shared config. * If handling the `^/_matrix/client/v3/keys/upload` endpoint, the HTTP URI for the main process (`worker_main_http_uri`). @@ -153,7 +153,7 @@ Finally, you need to start your worker processes. This can be done with either `synctl` or your distribution's preferred service manager such as `systemd`. We recommend the use of `systemd` where available: for information on setting up `systemd` to start synapse workers, see -[Systemd with Workers](systemd-with-workers). To use `synctl`, see +[Systemd with Workers](systemd-with-workers/index.html). To use `synctl`, see [Using synctl with Workers](synctl_workers.md). @@ -287,7 +287,7 @@ For multiple workers not handling the SSO endpoints properly, see [#7530](https://github.com/matrix-org/synapse/issues/7530) and [#9427](https://github.com/matrix-org/synapse/issues/9427). -Note that a [HTTP listener](usage/configuration/config_documentation.md#listeners) +Note that a [HTTP listener](config_documentation.md#listeners) with `client` and `federation` `resources` must be configured in the `worker_listeners` option in the worker config. @@ -330,7 +330,7 @@ Additionally, the writing of specific streams (such as events) can be moved off of the main process to a particular worker. To enable this, the worker must have a -[HTTP `replication` listener](usage/configuration/config_documentation.md#listeners) configured, +[HTTP `replication` listener](config_documentation.md#listeners) configured, have a `worker_name` and be listed in the `instance_map` config. The same worker can handle multiple streams, but unless otherwise documented, each stream can only have a single writer. @@ -553,7 +553,7 @@ media repository. Note that doing so will prevent the main process from being able to handle the above endpoints. In the `media_repository` worker configuration file, configure the -[HTTP listener](usage/configuration/config_documentation.md#listeners) to +[HTTP listener](config_documentation.md#listeners) to expose the `media` resource. For example: ```yaml diff --git a/docs/federate.md b/docs/usage/federate.md similarity index 91% rename from docs/federate.md rename to docs/usage/federate.md index df4c87da51e2..9b8c61f5a082 100644 --- a/docs/federate.md +++ b/docs/usage/federate.md @@ -14,7 +14,7 @@ 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](reverse_proxy.md) for instructions +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 @@ -23,7 +23,7 @@ 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](delegate.md) for instructions on how to set this up. +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 @@ -44,7 +44,7 @@ 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](reverse_proxy.md) for instructions on how +proxy: see [the reverse proxy documentation](../setup/reverse_proxy.md) for instructions on how to correctly configure a reverse proxy. ### Known issues diff --git a/docs/welcome_and_overview.md b/docs/welcome_and_overview.md index 451759f06ec6..44bf90e37077 100644 --- a/docs/welcome_and_overview.md +++ b/docs/welcome_and_overview.md @@ -16,16 +16,16 @@ This documentation covers topics for **installation**, **configuration** and * See how to [upgrade](upgrade.md) between Synapse versions. * Administer your instance using the [Admin - API](usage/administration/admin_api/index.html), installing [pluggable - modules](modules/index.html), or by accessing the [manhole](manhole.md). + API](administration/admin_api/index.html), installing [pluggable + modules](modules/index.html), or by accessing the [manhole](administration/manhole.md). -* Learn how to [read log lines](usage/administration/request_log.md), configure +* Learn how to [read log lines](administration/request_log.md), configure [logging](usage/configuration/logging_sample_config.md) or set up [structured - logging](structured_logging.md). + logging](usage/configuration/structured_logging.md). -* Scale Synapse through additional [worker processes](workers.md). +* Scale Synapse through additional [worker processes](usage/configuration/workers.md). -* Set up [monitoring and metrics](metrics-howto.md) to keep an eye on your +* Set up [monitoring and metrics](administration/metrics-howto.md) to keep an eye on your Synapse instance's performance. ## Developing on Synapse @@ -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!