From 7b75dabb1090d52ae383093d47feb557edc653c1 Mon Sep 17 00:00:00 2001 From: squahtx Date: Tue, 8 Nov 2022 13:07:53 +0000 Subject: deploy: f0dec49f01a7071296bce74557fbd6996ccf5759 --- .../usage/configuration/config_documentation.html | 199 ++++++++++++++++++--- 1 file changed, 173 insertions(+), 26 deletions(-) (limited to 'latest/usage/configuration/config_documentation.html') diff --git a/latest/usage/configuration/config_documentation.html b/latest/usage/configuration/config_documentation.html index 671492a9b5..828ffdf5e0 100644 --- a/latest/usage/configuration/config_documentation.html +++ b/latest/usage/configuration/config_documentation.html @@ -275,7 +275,7 @@ including _matrix/...). This is the same URL a user might enter into the 'Custom Homeserver URL' field on their client. If you use Synapse with a reverse proxy, this should be the URL to reach Synapse via the proxy. Otherwise, it should be the URL to reach Synapse's client HTTP listener (see -'listeners' below).

+'listeners' below).

Defaults to https://<server_name>/.

Example configuration:

public_baseurl: https://example.com/
@@ -1269,7 +1269,8 @@ when Synapse is started.

 
Config options related to logging.

 

 
log_config

-
This option specifies a yaml python logging config file as described here.

+
This option specifies a yaml python logging config file as described
+here.

 
Example configuration:

 
log_config: "CONFDIR/SERVERNAME.log.config"
 

@@ -2114,8 +2115,8 @@ Defaults to false.

 
enable_legacy_metrics

 
Set to true to publish both legacy and non-legacy Prometheus metric names,
 or to false to only publish non-legacy Prometheus metric names.
-Defaults to true. Has no effect if enable_metrics is false.
-In Synapse v1.71.0, this will default to false before being removed in Synapse v1.73.0.

+Defaults to false. Has no effect if enable_metrics is false.
+In Synapse v1.67.0 up to and including Synapse v1.70.1, this defaulted to true.

 
Legacy metric names include:

 
    
 
  • metrics containing colons in the name, such as synapse_util_caches_response_cache:hits, because colons are supposed to be reserved for user-defined recording rules;
    • 
@@ -2299,6 +2300,11 @@ is still supported for backwards-compatibility, but it is deprecated.
    
 
    trusted_key_servers defaults to matrix.org, but using it will generate a
 warning on start-up. To suppress this warning, set
 suppress_key_server_warning to true.
    
+
    If the use of a trusted key server has to be deactivated, e.g. in a private
+federation or for privacy reasons, this can be realised by setting
+an empty array (trusted_key_servers: []). Then Synapse will request the keys
+directly from the server that owns the keys. If Synapse does not get keys directly
+from the server, the events of this server will be rejected.
    
 
    Options for each entry in the list include:
    
 
      
 
    • server_name: the name of the server. Required.
      • 
@@ -2661,6 +2667,17 @@ without modifications.
      
 which is set to the claims returned by the UserInfo Endpoint and/or
 in the ID Token.
      
 
+
    • 
+
      backchannel_logout_enabled: set to true to process OIDC Back-Channel Logout notifications. 
+Those notifications are expected to be received on /_synapse/client/oidc/backchannel_logout.
+Defaults to false.
      
+
      • 
+
    • 
+
      backchannel_logout_ignore_sub: by default, the OIDC Back-Channel Logout feature checks that the
+sub claim matches the subject claim received during login. This check can be disabled by setting
+this to true. Defaults to false.
      
+
      You might want to disable this if the subject_claim returned by the mapping provider is not sub.
      
+
      • 
 
    
 
    It is possible to configure Synapse to only allow logins if certain attributes
 match particular values in the OIDC userinfo. The requirements can be listed under
@@ -3031,7 +3048,7 @@ of unread messages.
 
    Rooms
    
 
    Config options relating to rooms.
    
 
    
-
    encryption_enabled_by_default
    
+
    encryption_enabled_by_default_for_room_type
    
 
    Controls whether locally-created rooms should be end-to-end encrypted by
 default.
    
 
    Possible options are "all", "invite", and "off". They are defined as:
    
@@ -3289,31 +3306,82 @@ mostly related to trace sampling which is documented Workers
-
    Configuration options related to workers.
    
+
    Coordinating workers
    
+
    Configuration options related to workers which belong in the main config file
+(usually called homeserver.yaml).
+A Synapse deployment can scale horizontally by running multiple Synapse processes
+called workers. Incoming requests are distributed between workers to handle higher
+loads. Some workers are privileged and can accept requests from other workers.
    
+
    As a result, the worker configuration is divided into two parts.
    
+
      
+
    1. The first part (in this section of the manual) defines which shardable tasks
+are delegated to privileged workers. This allows unprivileged workers to make
+request a privileged worker to act on their behalf.
      2. 
+
    2. The second part
+controls the behaviour of individual workers in isolation.
      3. 
+
    
+
    For guidance on setting up workers, see the worker documentation.
    
+
    
+
    worker_replication_secret
    
+
    A shared secret used by the replication APIs on the main process to authenticate
+HTTP requests from workers.
    
+
    The default, this value is omitted (equivalently null), which means that 
+traffic between the workers and the main process is not authenticated.
    
+
    Example configuration:
    
+
    worker_replication_secret: "secret_secret"
+
    
+
    
+
    start_pushers
    
+
    Controls sending of push notifications on the main process. Set to false
+if using a pusher worker. Defaults to true.
    
+
    Example configuration:
    
+
    start_pushers: false
+
    
+
    
+
    pusher_instances
    
+
    It is possible to run multiple pusher workers,
+in which case the work is balanced across them. Use this setting to list the pushers by
+worker_name. Ensure the main process and all pusher workers are
+restarted after changing this option.
    
+
    If no or only one pusher worker is configured, this setting is not necessary.
+The main process will send out push notifications by default if you do not disable
+it by setting start_pushers: false.
    
+
    Example configuration:
    
+
    start_pushers: false
+pusher_instances:
+  - pusher_worker1
+  - pusher_worker2
+
    
 
    
 
    send_federation
    
 
    Controls sending of outbound federation transactions on the main process.
-Set to false if using a federation sender worker. Defaults to true.
    
+Set to false if using a federation sender worker.
+Defaults to true.
    
 
    Example configuration:
    
 
    send_federation: false
 
    
 
    
 
    federation_sender_instances
    
-
    It is possible to run multiple federation sender workers, in which case the
-work is balanced across them. Use this setting to list the senders.
    
+
    It is possible to run multiple
+federation sender worker, in which
+case the work is balanced across them. Use this setting to list the senders.
    
 
    This configuration setting must be shared between all federation sender workers, and if
 changed all federation sender workers must be stopped at the same time and then
 started, to ensure that all instances are running with the same config (otherwise
 events may be dropped).
    
 
    Example configuration:
    
-
    federation_sender_instances:
+
    send_federation: false
+federation_sender_instances:
   - federation_sender1
 
    
 
    
 
    instance_map
    
-
    When using workers this should be a map from worker name to the
-HTTP replication listener of the worker, if configured.
    
+
    When using workers this should be a map from worker_name to the
+HTTP replication listener of the worker, if configured.
+Each worker declared under stream_writers needs 
+a HTTP replication listener, and that listener should be included in the instance_map.
+(The main process also needs an HTTP replication listener, but it should not be 
+listed in the instance_map.)
    
 
    Example configuration:
    
 
    instance_map:
   worker1:
@@ -3323,8 +3391,10 @@ HTTP replication listener of the worker, if configured.
    
 
    
 
    stream_writers
    
 
    Experimental: When using workers you can define which workers should
-handle event persistence and typing notifications. Any worker
-specified here must also be in the instance_map.
    
+handle writing to streams such as event persistence and typing notifications.
+Any worker specified here must also be in the instance_map.
    
+
    See the list of available streams in the
+worker documentation.
    
 
    Example configuration:
    
 
    stream_writers:
   events: worker1
@@ -3332,22 +3402,15 @@ specified here must also be in the instance_map.
    
 
    
 
    
 
    run_background_tasks_on
    
-
    The worker that is used to run background tasks (e.g. cleaning up expired
-data). If not provided this defaults to the main process.
    
+
    The worker that is used to run
+background tasks (e.g. cleaning up expired data). If not provided this
+defaults to the main process.
    
 
    Example configuration:
    
 
    run_background_tasks_on: worker1
 
    
 
    
-
    worker_replication_secret
    
-
    A shared secret used by the replication APIs to authenticate HTTP requests
-from workers.
    
-
    By default this is unused and traffic is not authenticated.
    
-
    Example configuration:
    
-
    worker_replication_secret: "secret_secret"
-
    
 
    redis
    
-
    Configuration for Redis when using workers. This must be enabled when
-using workers (unless using old style direct TCP configuration).
+
    Configuration for Redis when using workers. This must be enabled when using workers.
 This setting has the following sub-options:
    
 
      
 
    • enabled: whether to use Redis support. Defaults to false.
      • 
@@ -3362,6 +3425,90 @@ localhost and 6379
   port: 6379
   password: <secret_password>
 
    
+
    
+
    Individual worker configuration
    
+
    These options configure an individual worker, in its worker configuration file.
+They should be not be provided when configuring the main process.
    
+
    Note also the configuration above for
+coordinating a cluster of workers.
    
+
    For guidance on setting up workers, see the worker documentation.
    
+
    
+
    worker_app
    
+
    The type of worker. The currently available worker applications are listed
+in worker documentation.
    
+
    The most common worker is the
+synapse.app.generic_worker.
    
+
    Example configuration:
    
+
    worker_app: synapse.app.generic_worker
+
    
+
    
+
    worker_name
    
+
    A unique name for the worker. The worker needs a name to be addressed in
+further parameters and identification in log files. We strongly recommend
+giving each worker a unique worker_name.
    
+
    Example configuration:
    
+
    worker_name: generic_worker1
+
    
+
    
+
    worker_replication_host
    
+
    The HTTP replication endpoint that it should talk to on the main Synapse process.
+The main Synapse process defines this with a replication resource in
+listeners option.
    
+
    Example configuration:
    
+
    worker_replication_host: 127.0.0.1
+
    
+
    
+
    worker_replication_http_port
    
+
    The HTTP replication port that it should talk to on the main Synapse process.
+The main Synapse process defines this with a replication resource in
+listeners option.
    
+
    Example configuration:
    
+
    worker_replication_http_port: 9093
+
    
+
    
+
    worker_listeners
    
+
    A worker can handle HTTP requests. To do so, a worker_listeners option 
+must be declared, in the same way as the listeners option 
+in the shared config.
    
+
    Workers declared in stream_writers will need to include a
+replication listener here, in order to accept internal HTTP requests from
+other workers.
    
+
    Example configuration:
    
+
    worker_listeners:
+  - type: http
+    port: 8083
+    resources:
+      - names: [client, federation]
+
    
+
    
+
    worker_daemonize
    
+
    Specifies whether the worker should be started as a daemon process.
+If Synapse is being managed by systemd, this option 
+must be omitted or set to false.
    
+
    Defaults to false.
    
+
    Example configuration:
    
+
    worker_daemonize: true
+
    
+
    
+
    worker_pid_file
    
+
    When running a worker as a daemon, we need a place to store the 
+PID of the worker.
+This option defines the location of that "pid file".
    
+
    This option is required if worker_daemonize is true and ignored 
+otherwise. It has no default.
    
+
    See also the pid_file option option for the main Synapse process.
    
+
    Example configuration:
    
+
    worker_pid_file: DATADIR/generic_worker1.pid
+
    
+
    
+
    worker_log_config
    
+
    This option specifies a yaml python logging config file as described
+here.
+See also the log_config option option for the main Synapse process.
    
+
    Example configuration:
    
+
    worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
+
    
+
    
 
    Background Updates
    
 
    Configuration settings related to background updates.
    
 
    
-- 
cgit 1.5.1