diff options
Diffstat (limited to 'docs/usage')
4 files changed, 43 insertions, 27 deletions
diff --git a/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md b/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md index 60b758e33b..4c0dbb5acd 100644 --- a/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md +++ b/docs/usage/administration/monitoring/reporting_homeserver_usage_statistics.md @@ -74,3 +74,4 @@ consider using one of the following known implementations: * [Matrix.org's Panopticon](https://github.com/matrix-org/panopticon) * [Famedly's Barad-dûr](https://gitlab.com/famedly/infra/services/barad-dur) +* [Synapse Usage Exporter](https://github.com/loelkes/synapse-usage-exporter) for Prometheus diff --git a/docs/usage/administration/request_log.md b/docs/usage/administration/request_log.md index 292e3449f1..6154108934 100644 --- a/docs/usage/administration/request_log.md +++ b/docs/usage/administration/request_log.md @@ -1,6 +1,6 @@ # Request log format -HTTP request logs are written by synapse (see [`synapse/http/site.py`](https://github.com/matrix-org/synapse/tree/develop/synapse/http/site.py) for details). +HTTP request logs are written by synapse (see [`synapse/http/site.py`](https://github.com/element-hq/synapse/tree/develop/synapse/http/site.py) for details). See the following for how to decode the dense data available from the default logging configuration. @@ -19,7 +19,7 @@ See the following for how to decode the dense data available from the default lo | EEEE | Request Identifier (This identifier is shared by related log lines)| | FFFF | Source IP (Or X-Forwarded-For if enabled) | | GGGG | Server Port | -| HHHH | Federated Server or Local User making request (blank if unauthenticated or not supplied).<br/>If this is of the form `@aaa:example.com|@bbb:example.com`, then that means that `@aaa:example.com` is authenticated but they are controlling `@bbb:example.com`, e.g. if `aaa` is controlling `bbb` [via the admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#login-as-a-user). | +| HHHH | Federated Server or Local User making request (blank if unauthenticated or not supplied).<br/>If this is of the form `@aaa:example.com|@bbb:example.com`, then that means that `@aaa:example.com` is authenticated but they are controlling `@bbb:example.com`, e.g. if `aaa` is controlling `bbb` [via the admin API](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#login-as-a-user). | | IIII | Total Time to process the request | | JJJJ | Time to send response over network once generated (this may be negative if the socket is closed before the response is generated)| | KKKK | Userland CPU time | diff --git a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md b/docs/usage/administration/understanding_synapse_through_grafana_graphs.md index c365cc3923..a2cb9f5386 100644 --- a/docs/usage/administration/understanding_synapse_through_grafana_graphs.md +++ b/docs/usage/administration/understanding_synapse_through_grafana_graphs.md @@ -1,14 +1,14 @@ ## Understanding Synapse through Grafana graphs -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) -and information on setting up Grafana is [here](https://github.com/matrix-org/synapse/tree/master/contrib/grafana). +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) +and information on setting up Grafana is [here](https://github.com/element-hq/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 present this information through a series of pretty graphs. -Once you have grafana set up, and assuming you're using [our grafana dashboard template](https://github.com/matrix-org/synapse/blob/master/contrib/grafana/synapse.json), look for the following graphs when debugging a slow/overloaded Synapse: +Once you have grafana set up, and assuming you're using [our grafana dashboard template](https://github.com/element-hq/synapse/blob/master/contrib/grafana/synapse.json), look for the following graphs when debugging a slow/overloaded Synapse: ## Message Event Send Time @@ -57,7 +57,7 @@ Cross-referencing this with the Eviction Rate graph, which shows that entries ar  -we should probably consider raising the size of that cache by raising its cache factor (a multiplier value for the size of an individual cache). Information on doing so is available [here](https://github.com/matrix-org/synapse/blob/ee421e524478c1ad8d43741c27379499c2f6135c/docs/sample_config.yaml#L608-L642) (note that the configuration of individual cache factors through the configuration file is available in Synapse v1.14.0+, whereas doing so through environment variables has been supported for a very long time). Note that this will increase Synapse's overall memory usage. +we should probably consider raising the size of that cache by raising its cache factor (a multiplier value for the size of an individual cache). Information on doing so is available [here](https://github.com/element-hq/synapse/blob/ee421e524478c1ad8d43741c27379499c2f6135c/docs/sample_config.yaml#L608-L642) (note that the configuration of individual cache factors through the configuration file is available in Synapse v1.14.0+, whereas doing so through environment variables has been supported for a very long time). Note that this will increase Synapse's overall memory usage. ## Forward Extremities @@ -71,14 +71,13 @@ If a room has >10 forward extremities, it's worth checking which room is the cul  -Large spikes in garbage collection times (bigger than shown here, I'm talking in the -multiple seconds range), can cause lots of problems in Synapse performance. It's more an +Large spikes in garbage collection times (bigger than shown here, I'm talking in the +multiple seconds range), can cause lots of problems in Synapse performance. It's more an indicator of problems, and a symptom of other problems though, so check other graphs for what might be causing it. ## Final Thoughts -If you're still having performance problems with your Synapse instance and you've +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](../../workers.md) to make use of multiple CPU cores / multiple machines for your homeserver. - diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index 425ec75542..8723b9a3fe 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -495,10 +495,10 @@ Unix socket support (_Added in Synapse 1.89.0_): * **Note**: The use of both `path` and `port` options for the same `listener` is not compatible. * The `x_forwarded` option defaults to true when using Unix sockets and can be omitted. - * Other options that would not make sense to use with a UNIX socket, such as + * Other options that would not make sense to use with a UNIX socket, such as `bind_addresses` and `tls` will be ignored and can be removed. * `mode`: The file permissions to set on the UNIX socket. Defaults to `666` -* **Note:** Must be set as `type: http` (does not support `metrics` and `manhole`). +* **Note:** Must be set as `type: http` (does not support `metrics` and `manhole`). Also make sure that `metrics` is not included in `resources` -> `names` @@ -549,7 +549,7 @@ listeners: # that unwraps TLS. # # If you plan to use a reverse proxy, please see - # https://matrix-org.github.io/synapse/latest/reverse_proxy.html. + # https://element-hq.github.io/synapse/latest/reverse_proxy.html. # - port: 8008 tls: false @@ -581,7 +581,7 @@ listeners: # conflicts, and providing enhanced security through system file permissions. # # Note that x_forwarded will default to true, when using a UNIX socket. Please see - # https://matrix-org.github.io/synapse/latest/reverse_proxy.html. + # https://element-hq.github.io/synapse/latest/reverse_proxy.html. # - path: /run/synapse/main_public.sock type: http @@ -680,6 +680,11 @@ This setting has the following sub-options: has missed. Disabled by default. * `notif_for_new_users`: Set to false to disable automatic subscription to email notifications for new users. Enabled by default. +* `notif_delay_before_mail`: The time to wait before emailing about a notification. + This gives the user a chance to view the message via push or an open client. + Defaults to 10 minutes. + + _New in Synapse 1.99.0._ * `client_base_url`: Custom URL for client links within the email notifications. By default links will be based on "https://matrix.to". (This setting used to be called `riot_base_url`; the old name is still supported for backwards-compatibility but is now deprecated.) @@ -1411,7 +1416,7 @@ kill -HUP [PID_OF_SYNAPSE_PROCESS] If you are running multiple workers, you must individually update the worker config file and send this signal to each worker process. -If you're using the [example systemd service](https://github.com/matrix-org/synapse/blob/develop/contrib/systemd/matrix-synapse.service) +If you're using the [example systemd service](https://github.com/element-hq/synapse/blob/develop/contrib/systemd/matrix-synapse.service) file in Synapse's `contrib` directory, you can send a `SIGHUP` signal by using `systemctl reload matrix-synapse`. @@ -2675,7 +2680,7 @@ Example configuration: refreshable_access_token_lifetime: 10m ``` --- -### `refresh_token_lifetime: 24h` +### `refresh_token_lifetime` Time that a refresh token remains valid for (provided that it is not exchanged for another one first). @@ -2774,6 +2779,10 @@ enable_metrics: true Use this option to enable sentry integration. Provide the DSN assigned to you by sentry with the `dsn` setting. + An optional `environment` field can be used to specify an environment. This allows + for log maintenance based on different environments, ensuring better organization + and analysis.. + NOTE: While attempts are made to ensure that the logs don't contain any sensitive information, this cannot be guaranteed. By enabling this option the sentry server may therefore receive sensitive @@ -2783,6 +2792,7 @@ through insecure notification channels if so configured. Example configuration: ```yaml sentry: + environment: "production" dsn: "..." ``` --- @@ -2932,7 +2942,7 @@ access tokens via a query parameter. Example configuration: ```yaml -use_appservice_legacy_authorization: true +use_appservice_legacy_authorization: true ``` --- @@ -3613,7 +3623,7 @@ This setting has the following sub-options: * `enabled`: Defaults to true. Set to false to disable password authentication. Set to `only_for_reauth` to allow users with existing passwords to use them - to log in and reauthenticate, whilst preventing new users from setting passwords. + to reauthenticate (not log in), whilst preventing new users from setting passwords. * `localdb_enabled`: Set to false to disable authentication against the local password database. This is ignored if `enabled` is false, and is only useful if you have other `password_providers`. Defaults to true. @@ -3832,16 +3842,22 @@ Sub-options for this setting include: * `system_mxid_display_name`: set the display name of the "notices" user * `system_mxid_avatar_url`: set the avatar for the "notices" user * `room_name`: set the room name of the server notices room +* `room_avatar_url`: optional string. The room avatar to use for server notice rooms. If set to the empty string `""`, notice rooms will not be given an avatar. Defaults to the empty string. _Added in Synapse 1.99.0._ +* `room_topic`: optional string. The topic to use for server notice rooms. If set to the empty string `""`, notice rooms will not be given a topic. Defaults to the empty string. _Added in Synapse 1.99.0._ * `auto_join`: boolean. If true, the user will be automatically joined to the room instead of being invited. Defaults to false. _Added in Synapse 1.98.0._ +Note that the name, topic and avatar of existing server notice rooms will only be updated when a new notice event is sent. + Example configuration: ```yaml server_notices: system_mxid_localpart: notices system_mxid_display_name: "Server Notices" - system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ" + system_mxid_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ" room_name: "Server Notices" + room_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ" + room_topic: "Room used by your server admin to notice you of important information" auto_join: true ``` --- @@ -3865,7 +3881,7 @@ This setting is an optional list of 0 or more rules. By default, no list is provided, meaning that all alias creations are permitted. Otherwise, requests to create aliases are matched against each rule in order. -The first rule that matches decides if the request is allowed or denied. If no +The first rule that matches decides if the request is allowed or denied. If no rule matches, the request is denied. In particular, this means that configuring an empty list of rules will deny every alias creation request. @@ -3877,7 +3893,7 @@ Each rule is a YAML object containing four fields, each of which is an optional * `action`: either `allow` or `deny`. What to do with the request if the rule matches. Defaults to `allow`. Each of the glob patterns is optional, defaulting to `*` ("match anything"). -Note that the patterns match against fully qualified IDs, e.g. against +Note that the patterns match against fully qualified IDs, e.g. against `@alice:example.com`, `#room:example.com` and `!abcdefghijk:example.com` instead of `alice`, `room` and `abcedgghijk`. @@ -3914,7 +3930,7 @@ alias_creation_rules: alias_creation_rules: - user_id: "@bad_user:example.com" action: deny - + - action: allow ``` @@ -3992,7 +4008,7 @@ room_list_publication_rules: room_list_publication_rules: - user_id: "@bad_user:example.com" action: deny - + - action: allow ``` @@ -4408,7 +4424,7 @@ must be declared, in the same way as the [`listeners` option](#listeners) in the shared config. Workers declared in [`stream_writers`](#stream_writers) and [`instance_map`](#instance_map) - will need to include a `replication` listener here, in order to accept internal HTTP + will need to include a `replication` listener here, in order to accept internal HTTP requests from other workers. Example configuration: |