From 1fec7f5214f0a160600bb51fe9b17a8563a878e6 Mon Sep 17 00:00:00 2001 From: erikjohnston Date: Tue, 31 May 2022 13:28:14 +0000 Subject: deploy: b2b5279a3f1b4012de664b424f9e9db13ce3c774 --- .../usage/configuration/config_documentation.html | 99 +++++++++++++++++++--- .../configuration/homeserver_sample_config.html | 66 ++++++++++++++- latest/usage/configuration/index.html | 2 +- .../usage/configuration/logging_sample_config.html | 2 +- .../configuration/user_authentication/index.html | 2 +- .../user_authentication/refresh_tokens.html | 2 +- .../user_authentication/single_sign_on/cas.html | 2 +- .../user_authentication/single_sign_on/index.html | 2 +- .../user_authentication/single_sign_on/saml.html | 2 +- 9 files changed, 156 insertions(+), 23 deletions(-) (limited to 'latest/usage/configuration') diff --git a/latest/usage/configuration/config_documentation.html b/latest/usage/configuration/config_documentation.html index 0603e07295..57b9ea0529 100644 --- a/latest/usage/configuration/config_documentation.html +++ b/latest/usage/configuration/config_documentation.html @@ -76,7 +76,7 @@ @@ -167,6 +167,13 @@ followed by a letter. Letters have the following meanings:

For example, setting redaction_retention_period: 5m would remove redacted messages from the database after 5 minutes, rather than 5 months.

+

In addition, configuration options referring to size use the following suffixes:

+ +

For example, setting max_avatar_size: 10M means that Synapse will not accept files larger than 10,485,760 bytes +for a user avatar.

YAML

The configuration file is a YAML file, which means that certain syntax rules apply if you want your config file to be read properly. A few helpful things to know:

@@ -515,7 +522,7 @@ additional endpoints which should be loaded via dynamic modules.

Valid resource names are:

Example configuration:

caches:
   global_factor: 1.0
   per_cache_factors:
     get_users_who_share_room_with_user: 2.0
-  expire_caches: false
   sync_response_cache_duration: 2m
-
+ cache_autotuning: + max_cache_memory_usage: 1024M + target_cache_memory_usage: 758M + min_cache_ttl: 5m + +

Reloading cache factors

+

The cache factors (i.e. caches.global_factor and caches.per_cache_factors) may be reloaded at any time by sending a +SIGHUP signal to Synapse using e.g.

+
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 +file in Synapse's contrib directory, you can send a SIGHUP signal by using +systemctl reload matrix-synapse.

Database

Config options related to database settings.

@@ -1095,13 +1135,13 @@ connection pool. For a reference to valid arguments, see:

For more information on using Synapse with Postgres, see here.

Example SQLite configuration:

-
database:
+
database:
   name: sqlite3
   args:
     database: /path/to/homeserver.db
 

 
Example Postgres configuration:

-
database:
+
database:
   name: psycopg2
   txn_limit: 10000
   args:
@@ -1237,6 +1277,17 @@ Defaults to per_second: 0.003, burst_count: 5.

 
This option sets ratelimiting how often invites can be sent in a room or to a 
 specific user. per_room defaults to per_second: 0.3, burst_count: 10 and
 per_user defaults to per_second: 0.003, burst_count: 5. 

+
Client requests that invite user(s) when creating a
+room
+will count against the rc_invites.per_room limit, whereas
+client requests to invite a single user to a
+room
+will count against both the rc_invites.per_user and rc_invites.per_room limits.

+
Federation requests to invite a user will count against the rc_invites.per_user
+limit only, as Synapse presumes ratelimiting by room will be done by the sending server.

+
The rc_invites.per_user limit applies to the receiver of the invite, rather than the
+sender, meaning that a rc_invite.per_user.burst_count of 5 mandates that a single user
+cannot receive more than a burst of 5 invites at a time.

 
Example configuration:

 
rc_invites:
   per_room:
@@ -1491,10 +1542,10 @@ using quality value syntax (;q=). '*' translates to any language.

 
Defaults to "en".

 
Example configuration:

 
 url_preview_accept_language:
-   - en-UK
-   - en-US;q=0.9
-   - fr;q=0.8
-   - *;q=0.7
+   - 'en-UK'
+   - 'en-US;q=0.9'
+   - 'fr;q=0.8'
+   - '*;q=0.7'
 

 

 
Config option: oembed

@@ -2543,7 +2594,10 @@ validation will fail without configuring audiences.
 
Use this setting to enable password-based logins. 

 
This setting has the following sub-options:

 
    
-
  • enabled: Defaults to true.
    • 
+
  • 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.
    • 
 
  • 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. 
    • 
@@ -2958,6 +3012,25 @@ can publish rooms.
    
     action: allow
 

 

+
Config option: default_power_level_content_override

+
The default_power_level_content_override option controls the default power
+levels for rooms.

+
Useful if you know that your users need special permissions in rooms
+that they create (e.g. to send particular types of state events without
+needing an elevated power level).  This takes the same shape as the
+power_level_content_override parameter in the /createRoom API, but
+is applied before that parameter.

+
Note that each key provided inside a preset (for example events in the example
+below) will overwrite all existing defaults inside that key. So in the example
+below, newly-created private_chat rooms will have no rules for any event types
+except com.example.foo.

+
Example configuration:

+
default_power_level_content_override:
+   private_chat: { "events": { "com.example.foo" : 0 } }
+   trusted_private_chat: null
+   public_chat: null
+

+

 
Opentracing

 
Configuration options related to Opentracing support.

 

@@ -3040,7 +3113,7 @@ specified here must also be in the instance_map.

   typing: worker1
 

 

-
Config option: run_background_task_on

+
Config option: 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.

 
Example configuration:

diff --git a/latest/usage/configuration/homeserver_sample_config.html b/latest/usage/configuration/homeserver_sample_config.html
index ec9c6791ec..7c2b486e00 100644
--- a/latest/usage/configuration/homeserver_sample_config.html
+++ b/latest/usage/configuration/homeserver_sample_config.html
@@ -76,7 +76,7 @@
 
         
@@ -445,7 +445,7 @@ presence:
 #   federation: the server-server API (/_matrix/federation). Also implies
 #       'media', 'keys', 'openid'
 #
-#   keys: the key discovery API (/_matrix/keys).
+#   keys: the key discovery API (/_matrix/key).
 #
 #   media: the media API (/_matrix/media).
 #
@@ -886,6 +886,12 @@ retention:
 # A cache 'factor' is a multiplier that can be applied to each of
 # Synapse's caches in order to increase or decrease the maximum
 # number of entries that can be stored.
+#
+# The configuration for cache factors (caches.global_factor and
+# caches.per_cache_factors) can be reloaded while the application is running,
+# by sending a SIGHUP signal to the Synapse process. Changes to other parts of
+# the caching config will NOT be applied after a SIGHUP is received; a restart
+# is necessary.
 
 # The number of events to cache in memory. Not affected by
 # caches.global_factor.
@@ -934,6 +940,24 @@ caches:
   #
   #cache_entry_ttl: 30m
 
+  # This flag enables cache autotuning, and is further specified by the sub-options `max_cache_memory_usage`,
+  # `target_cache_memory_usage`, `min_cache_ttl`. These flags work in conjunction with each other to maintain
+  # a balance between cache memory usage and cache entry availability. You must be using jemalloc to utilize
+  # this option, and all three of the options must be specified for this feature to work.
+  #cache_autotuning:
+    # This flag sets a ceiling on much memory the cache can use before caches begin to be continuously evicted.
+    # They will continue to be evicted until the memory usage drops below the `target_memory_usage`, set in
+    # the flag below, or until the `min_cache_ttl` is hit.
+    #max_cache_memory_usage: 1024M
+
+    # This flag sets a rough target for the desired memory usage of the caches.
+    #target_cache_memory_usage: 758M
+
+    # 'min_cache_ttl` sets a limit under which newer cache entries are not evicted and is only applied when
+    # caches are actively being evicted/`max_cache_memory_usage` has been exceeded. This is to protect hot caches
+    # from being emptied while Synapse is evicting due to memory.
+    #min_cache_ttl: 5m
+
   # Controls how long the results of a /sync request are cached for after
   # a successful response is returned. A higher duration can help clients with
   # intermittent connections, at the cost of higher memory usage.
@@ -2348,7 +2372,9 @@ sso:
 
 
 password_config:
-   # Uncomment to disable password login
+   # Uncomment to disable password login.
+   # Set to `only_for_reauth` to permit reauthentication for users that
+   # have passwords and are already logged in.
    #
    #enabled: false
 
@@ -2618,6 +2644,40 @@ push:
 #
 #encryption_enabled_by_default_for_room_type: invite
 
+# Override the default power levels for rooms created on this server, per
+# room creation preset.
+#
+# The appropriate dictionary for the room preset will be applied on top
+# of the existing power levels content.
+#
+# Useful if you know that your users need special permissions in rooms
+# that they create (e.g. to send particular types of state events without
+# needing an elevated power level).  This takes the same shape as the
+# `power_level_content_override` parameter in the /createRoom API, but
+# is applied before that parameter.
+#
+# Valid keys are some or all of `private_chat`, `trusted_private_chat`
+# and `public_chat`. Inside each of those should be any of the
+# properties allowed in `power_level_content_override` in the
+# /createRoom API. If any property is missing, its default value will
+# continue to be used. If any property is present, it will overwrite
+# the existing default completely (so if the `events` property exists,
+# the default event power levels will be ignored).
+#
+#default_power_level_content_override:
+#    private_chat:
+#        "events":
+#            "com.example.myeventtype" : 0
+#            "m.room.avatar": 50
+#            "m.room.canonical_alias": 50
+#            "m.room.encryption": 100
+#            "m.room.history_visibility": 100
+#            "m.room.name": 50
+#            "m.room.power_levels": 100
+#            "m.room.server_acl": 100
+#            "m.room.tombstone": 100
+#        "events_default": 1
+
 
 # Uncomment to allow non-server-admin users to create groups on this server
 #
diff --git a/latest/usage/configuration/index.html b/latest/usage/configuration/index.html
index 0445819fb1..47f9e3e4e7 100644
--- a/latest/usage/configuration/index.html
+++ b/latest/usage/configuration/index.html
@@ -76,7 +76,7 @@
 
         
diff --git a/latest/usage/configuration/logging_sample_config.html b/latest/usage/configuration/logging_sample_config.html
index 7f22f2cba4..aee82a4209 100644
--- a/latest/usage/configuration/logging_sample_config.html
+++ b/latest/usage/configuration/logging_sample_config.html
@@ -76,7 +76,7 @@
 
         
diff --git a/latest/usage/configuration/user_authentication/index.html b/latest/usage/configuration/user_authentication/index.html
index 07b57f93b8..bdd249c696 100644
--- a/latest/usage/configuration/user_authentication/index.html
+++ b/latest/usage/configuration/user_authentication/index.html
@@ -76,7 +76,7 @@
 
         
diff --git a/latest/usage/configuration/user_authentication/refresh_tokens.html b/latest/usage/configuration/user_authentication/refresh_tokens.html
index 19ff965d59..e2dca42383 100644
--- a/latest/usage/configuration/user_authentication/refresh_tokens.html
+++ b/latest/usage/configuration/user_authentication/refresh_tokens.html
@@ -76,7 +76,7 @@
 
         
diff --git a/latest/usage/configuration/user_authentication/single_sign_on/cas.html b/latest/usage/configuration/user_authentication/single_sign_on/cas.html
index 35c34cdb92..7a25155b09 100644
--- a/latest/usage/configuration/user_authentication/single_sign_on/cas.html
+++ b/latest/usage/configuration/user_authentication/single_sign_on/cas.html
@@ -76,7 +76,7 @@
 
         
diff --git a/latest/usage/configuration/user_authentication/single_sign_on/index.html b/latest/usage/configuration/user_authentication/single_sign_on/index.html
index 26e8cbec06..92055b2b12 100644
--- a/latest/usage/configuration/user_authentication/single_sign_on/index.html
+++ b/latest/usage/configuration/user_authentication/single_sign_on/index.html
@@ -76,7 +76,7 @@
 
         
diff --git a/latest/usage/configuration/user_authentication/single_sign_on/saml.html b/latest/usage/configuration/user_authentication/single_sign_on/saml.html
index f6c2b50115..0f914ef20c 100644
--- a/latest/usage/configuration/user_authentication/single_sign_on/saml.html
+++ b/latest/usage/configuration/user_authentication/single_sign_on/saml.html
@@ -76,7 +76,7 @@
 
         
-- 
cgit 1.4.1