diff --git a/docs/howto-server-delegation.md b/docs/howto-server-delegation.md index ef0c0faac..512e1196a 100644 --- a/docs/howto-server-delegation.md +++ b/docs/howto-server-delegation.md @@ -127,7 +127,6 @@ matrix_synapse_container_additional_volumes: You can then tell Synapse to serve Federation traffic over TLS on `tcp/8448`: ```yaml -matrix_synapse_no_tls: false matrix_synapse_tls_federation_listener_enabled: true matrix_synapse_tls_certificate_path: /some/path/inside/the/container/certificate.crt matrix_synapse_tls_private_key_path: /some/path/inside/the/container/private.key diff --git a/group_vars/matrix-servers b/group_vars/matrix-servers index 597a6a89c..f46b5c6fc 100644 --- a/group_vars/matrix-servers +++ b/group_vars/matrix-servers @@ -294,12 +294,9 @@ matrix_synapse_database_database: "{{ matrix_postgres_db_name }}" # We do not enable TLS in Synapse by default. # TLS is handled by the matrix-nginx-proxy, which proxies the requests to Synapse. -matrix_synapse_no_tls: true -# Even though we don't do TLS at the Synapse side, Synapse v0.99 would still like to read -# some certificate file. The container contains a dummy certificate that could be used -# to prevent certificate file reading errors. It won't actually be used for anything else. -# See https://github.com/matrix-org/synapse/issues/4554 -matrix_synapse_tls_certificate_path: /conf/dummy.tls.crt +matrix_synapse_tls_federation_listener_enabled: false +matrix_synapse_tls_certificate_path: ~ +matrix_synapse_tls_private_key_path: ~ matrix_synapse_email_enabled: "{{ matrix_mailer_enabled }}" matrix_synapse_email_smtp_host: "matrix-mailer" diff --git a/roles/matrix-base/defaults/main.yml b/roles/matrix-base/defaults/main.yml index f86cf2f1f..033bda7ec 100644 --- a/roles/matrix-base/defaults/main.yml +++ b/roles/matrix-base/defaults/main.yml @@ -31,7 +31,7 @@ matrix_docker_network: "matrix" # Controls whether a `/.well-known/matrix/server` file is generated and used at all. # # If you wish to rely on DNS SRV records only, you can disable this. -# That implies that you'll be handling Matrix Federation API traffic (tcp/8448) +# Using DNS SRV records implies that you'll be handling Matrix Federation API traffic (tcp/8448) # using certificates for the base domain (`hostname_identity`) and not for the # matrix domain (`hostname_matrix`). matrix_well_known_matrix_server_enabled: true diff --git a/roles/matrix-synapse/defaults/main.yml b/roles/matrix-synapse/defaults/main.yml index 95ebc7a37..8ecc7339c 100644 --- a/roles/matrix-synapse/defaults/main.yml +++ b/roles/matrix-synapse/defaults/main.yml @@ -1,4 +1,4 @@ -matrix_synapse_docker_image: "matrixdotorg/synapse:v0.99.0-py3" +matrix_synapse_docker_image: "matrixdotorg/synapse:v0.99.1-py3" matrix_synapse_base_path: "{{ matrix_base_data_path }}/synapse" matrix_synapse_config_dir_path: "{{ matrix_synapse_base_path }}/config" @@ -65,14 +65,12 @@ matrix_synapse_root_log_level: "INFO" matrix_synapse_rc_messages_per_second: 0.2 matrix_synapse_rc_message_burst_count: 10.0 -# If you're serving Synapse behind an HTTPS-capable reverse-proxy, -# you can disable TLS completely (`matrix_synapse_no_tls: true`). -# Otherwise, you would need to provide certificate files to it. -matrix_synapse_no_tls: false # Controls whether the TLS federation listener is enabled (tcp/8448). -# Only makes sense if federation is not disabled (`matrix_synapse_federation_enabled`). +# Only makes sense if federation is enabled (`matrix_synapse_federation_enabled`). # Note that federation may potentially be enabled as non-TLS on tcp/8048 as well. -matrix_synapse_tls_federation_listener_enabled: "{{ not matrix_synapse_no_tls }}" +# If you're serving Synapse behind an HTTPS-capable reverse-proxy, +# you can disable the TLS listener (`matrix_synapse_tls_federation_listener_enabled: false`). +matrix_synapse_tls_federation_listener_enabled: true matrix_synapse_tls_certificate_path: "/data/{{ hostname_matrix }}.tls.crt" matrix_synapse_tls_private_key_path: "/data/{{ hostname_matrix }}.tls.key" diff --git a/roles/matrix-synapse/tasks/validate_config.yml b/roles/matrix-synapse/tasks/validate_config.yml index 2f86e6767..3cf1d1c4b 100644 --- a/roles/matrix-synapse/tasks/validate_config.yml +++ b/roles/matrix-synapse/tasks/validate_config.yml @@ -16,4 +16,5 @@ when: "item.old in vars" with_items: - {'old': 'matrix_synapse_container_expose_api_port', 'new': 'matrix_synapse_container_expose_client_api_port'} + - {'old': 'matrix_synapse_no_tls', 'new': ''} diff --git a/roles/matrix-synapse/templates/synapse/homeserver.yaml.j2 b/roles/matrix-synapse/templates/synapse/homeserver.yaml.j2 index d52ba1abb..73c0003a7 100644 --- a/roles/matrix-synapse/templates/synapse/homeserver.yaml.j2 +++ b/roles/matrix-synapse/templates/synapse/homeserver.yaml.j2 @@ -1,71 +1,4 @@ # vim:ft=yaml -# PEM-encoded X509 certificate for TLS. -# This certificate, as of Synapse 1.0, will need to be a valid and verifiable -# certificate, signed by a recognised Certificate Authority. -# -# See 'ACME support' below to enable auto-provisioning this certificate via -# Let's Encrypt. -# -tls_certificate_path: "{{ matrix_synapse_tls_certificate_path }}" - -# PEM-encoded private key for TLS -tls_private_key_path: "{{ matrix_synapse_tls_private_key_path }}" - -# ACME support: This will configure Synapse to request a valid TLS certificate -# for your configured `server_name` via Let's Encrypt. -# -# Note that provisioning a certificate in this way requires port 80 to be -# routed to Synapse so that it can complete the http-01 ACME challenge. -# By default, if you enable ACME support, Synapse will attempt to listen on -# port 80 for incoming http-01 challenges - however, this will likely fail -# with 'Permission denied' or a similar error. -# -# There are a couple of potential solutions to this: -# -# * If you already have an Apache, Nginx, or similar listening on port 80, -# you can configure Synapse to use an alternate port, and have your web -# server forward the requests. For example, assuming you set 'port: 8009' -# below, on Apache, you would write: -# -# ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge -# -# * Alternatively, you can use something like `authbind` to give Synapse -# permission to listen on port 80. -# -acme: - # ACME support is disabled by default. Uncomment the following line - # to enable it. - # - # enabled: true - - # Endpoint to use to request certificates. If you only want to test, - # use Let's Encrypt's staging url: - # https://acme-staging.api.letsencrypt.org/directory - # - # url: https://acme-v01.api.letsencrypt.org/directory - - # Port number to listen on for the HTTP-01 challenge. Change this if - # you are forwarding connections through Apache/Nginx/etc. - # - # port: 80 - - # Local addresses to listen on for incoming connections. - # Again, you may want to change this if you are forwarding connections - # through Apache/Nginx/etc. - # - # bind_addresses: ['::', '0.0.0.0'] - - # How many days remaining on a certificate before it is renewed. - # - # reprovision_threshold: 30 - -# If your server runs behind a reverse-proxy which terminates TLS connections -# (for both client and federation connections), it may be useful to disable -# All TLS support for incoming connections. Setting no_tls to True will -# do so (and avoid the need to give synapse a TLS private key). -# -no_tls: {{ matrix_synapse_no_tls|to_json }} - ## Server ## # The domain name of the server, with optional explicit port. @@ -100,16 +33,16 @@ pid_file: /homeserver.pid # # cpu_affinity: 0xFFFFFFFF -# Whether to serve a web client from the HTTP/HTTPS root resource. -web_client: False - -# The root directory to server for the above web client. -# If left undefined, synapse will serve the matrix-angular-sdk web client. -# Make sure matrix-angular-sdk is installed with pip if web_client is True -# and web_client_location is undefined +# The path to the web client which will be served at /_matrix/client/ +# if 'webclient' is configured under the 'listeners' configuration. +# # web_client_location: "/path/to/web/root" -# The public-facing base URL for the client API (not including _matrix/...) +# The public-facing base URL that clients use to access this HS +# (not including _matrix/...). This is the same URL a user would +# enter into the 'custom HS URL' field on their client. If you +# use synapse with a reverse proxy, this should be the URL to reach +# synapse via the proxy. public_baseurl: https://{{ hostname_matrix }}/ # Set the soft limit on the number of file descriptors synapse can use @@ -148,6 +81,64 @@ federation_domain_whitelist: {{ matrix_synapse_federation_domain_whitelist|to_js # List of ports that Synapse should listen on, their purpose and their # configuration. +# +# Options for each listener include: +# +# port: the TCP port to bind to +# +# bind_addresses: a list of local addresses to listen on. The default is +# 'all local interfaces'. +# +# type: the type of listener. Normally 'http', but other valid options are: +# 'manhole' (see docs/manhole.md), +# 'metrics' (see docs/metrics-howto.rst), +# 'replication' (see docs/workers.rst). +# +# 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. +# +# resources: Only valid for an 'http' listener. A list of resources to host +# on this port. Options for each resource are: +# +# names: a list of names of HTTP resources. See below for a list of +# valid resource names. +# +# compress: set to true to enable HTTP comression for this resource. +# +# additional_resources: Only valid for an 'http' listener. A map of +# additional endpoints which should be loaded via dynamic modules. +# +# Valid resource names are: +# +# client: the client-server API (/_matrix/client). Also implies 'media' and +# 'static'. +# +# consent: user consent forms (/_matrix/consent). See +# docs/consent_tracking.md. +# +# federation: the server-server API (/_matrix/federation). Also implies +# 'media', 'keys', 'openid' +# +# keys: the key discovery API (/_matrix/keys). +# +# media: the media API (/_matrix/media). +# +# metrics: the metrics interface. See docs/metrics-howto.rst. +# +# openid: OpenID authentication. +# +# replication: the HTTP replication API (/_synapse/replication). See +# docs/workers.rst. +# +# static: static resources under synapse/static (/_matrix/static). (Mostly +# useful for 'fallback authentication'.) +# +# webclient: A web client. Requires web_client_location to be set. +# listeners: {% if matrix_synapse_metrics_enabled %} - type: metrics @@ -157,47 +148,24 @@ listeners: {% endif %} {% if matrix_synapse_federation_enabled and matrix_synapse_tls_federation_listener_enabled %} - # Main HTTPS listener - # For when matrix traffic is sent directly to synapse. - - - # The port to listen for HTTPS requests on. - port: 8448 - - # Local addresses to listen on. - # On Linux and Mac OS, `::` will listen on all IPv4 and IPv6 - # addresses by default. For most other OSes, this will only listen - # on IPv6. - bind_addresses: ['::'] - - # This is a 'http' listener, allows us to specify 'resources'. - type: http - + # TLS-enabled listener: for when matrix traffic is sent directly to synapse. + - port: 8448 tls: true - - # Use the X-Forwarded-For (XFF) header as the client IP and not the - # actual client IP. + bind_addresses: ['::'] + type: http x_forwarded: false - # List of HTTP resources to serve on this listener. resources: - - names: [federation] # Federation APIs + - names: [federation] compress: false - - # optional list of additional endpoints which can be loaded via - # dynamic modules - # additional_resources: - # "/_matrix/my/custom/endpoint": - # module: my_module.CustomRequestHandler - # config: {} {% endif %} - # Unsecure HTTP listener for the Client API, - # For when matrix traffic passes through loadbalancer that unwraps TLS. + # Unsecure HTTP listener (Client API): for when matrix traffic passes through a reverse proxy + # that unwraps TLS. - port: 8008 tls: false bind_addresses: ['::'] type: http - x_forwarded: true resources: @@ -205,13 +173,12 @@ listeners: compress: false {% if matrix_synapse_federation_enabled %} - # Unsecure HTTP listener for the Federation API, - # For when matrix traffic passes through loadbalancer that unwraps TLS. + # Unsecure HTTP listener (Federation API): for when matrix traffic passes through a reverse proxy + # that unwraps TLS. - port: 8048 tls: false bind_addresses: ['::'] type: http - x_forwarded: true resources: @@ -225,31 +192,132 @@ listeners: # bind_addresses: ['::1', '127.0.0.1'] # type: manhole +# Homeserver blocking +# +# How to reach the server admin, used in ResourceLimitError +# admin_contact: 'mailto:admin@server.com' +# +# Global block config +# +# hs_disabled: False +# hs_disabled_message: 'Human readable reason for why the HS is blocked' +# hs_disabled_limit_type: 'error code(str), to help clients decode reason' +# +# Monthly Active User Blocking +# +# Enables monthly active user checking +# limit_usage_by_mau: False +# max_mau_value: 50 +# mau_trial_days: 2 +# +# If enabled, the metrics for the number of monthly active users will +# be populated, however no one will be limited. If limit_usage_by_mau +# is true, this is implied to be true. +# mau_stats_only: False +# +# Sometimes the server admin will want to ensure certain accounts are +# never blocked by mau checking. These accounts are specified here. +# +# mau_limit_reserved_threepids: +# - medium: 'email' +# address: 'reserved_user@example.com' +# +# Room searching +# +# If disabled, new messages will not be indexed for searching and users +# will receive errors when searching for messages. Defaults to enabled. +# enable_search: true - # Homeserver blocking - # - # How to reach the server admin, used in ResourceLimitError - # admin_contact: 'mailto:admin@server.com' - # - # Global block config - # - # hs_disabled: False - # hs_disabled_message: 'Human readable reason for why the HS is blocked' - # hs_disabled_limit_type: 'error code(str), to help clients decode reason' - # - # Monthly Active User Blocking - # - # Enables monthly active user checking - # limit_usage_by_mau: False - # max_mau_value: 50 - # mau_trial_days: 2 - # - # Sometimes the server admin will want to ensure certain accounts are - # never blocked by mau checking. These accounts are specified here. - # - # mau_limit_reserved_threepids: - # - medium: 'email' - # address: 'reserved_user@example.com' + +## TLS ## + +# PEM-encoded X509 certificate for TLS. +# This certificate, as of Synapse 1.0, will need to be a valid and verifiable +# certificate, signed by a recognised Certificate Authority. +# +# See 'ACME support' below to enable auto-provisioning this certificate via +# Let's Encrypt. +# +tls_certificate_path: {{ matrix_synapse_tls_certificate_path|to_json }} + +# PEM-encoded private key for TLS +tls_private_key_path: {{ matrix_synapse_tls_private_key_path|to_json }} + +# ACME support: This will configure Synapse to request a valid TLS certificate +# for your configured `server_name` via Let's Encrypt. +# +# Note that provisioning a certificate in this way requires port 80 to be +# routed to Synapse so that it can complete the http-01 ACME challenge. +# By default, if you enable ACME support, Synapse will attempt to listen on +# port 80 for incoming http-01 challenges - however, this will likely fail +# with 'Permission denied' or a similar error. +# +# There are a couple of potential solutions to this: +# +# * If you already have an Apache, Nginx, or similar listening on port 80, +# you can configure Synapse to use an alternate port, and have your web +# server forward the requests. For example, assuming you set 'port: 8009' +# below, on Apache, you would write: +# +# ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge +# +# * Alternatively, you can use something like `authbind` to give Synapse +# permission to listen on port 80. +# +acme: + # ACME support is disabled by default. Uncomment the following line + # (and tls_certificate_path and tls_private_key_path above) to enable it. + # + # enabled: true + + # Endpoint to use to request certificates. If you only want to test, + # use Let's Encrypt's staging url: + # https://acme-staging.api.letsencrypt.org/directory + # + # url: https://acme-v01.api.letsencrypt.org/directory + + # Port number to listen on for the HTTP-01 challenge. Change this if + # you are forwarding connections through Apache/Nginx/etc. + # + # port: 80 + + # Local addresses to listen on for incoming connections. + # Again, you may want to change this if you are forwarding connections + # through Apache/Nginx/etc. + # + # bind_addresses: ['::', '0.0.0.0'] + + # How many days remaining on a certificate before it is renewed. + # + # reprovision_threshold: 30 + +# List of allowed TLS fingerprints for this server to publish along +# with the signing keys for this server. Other matrix servers that +# make HTTPS requests to this server will check that the TLS +# certificates returned by this server match one of the fingerprints. +# +# Synapse automatically adds the fingerprint of its own certificate +# to the list. So if federation traffic is handled directly by synapse +# then no modification to the list is required. +# +# If synapse is run behind a load balancer that handles the TLS then it +# will be necessary to add the fingerprints of the certificates used by +# the loadbalancers to this list if they are different to the one +# synapse is using. +# +# Homeservers are permitted to cache the list of TLS fingerprints +# returned in the key responses up to the "valid_until_ts" returned in +# key. It may be necessary to publish the fingerprints of a new +# certificate and wait until the "valid_until_ts" of the previous key +# responses have passed before deploying it. +# +# You can calculate a fingerprint from a given TLS listener via: +# openssl s_client -connect $host:$port < /dev/null 2> /dev/null | +# openssl x509 -outform DER | openssl sha256 -binary | base64 | tr -d '=' +# or by checking matrix.org/federationtester/api/report?server_name=$host +# +tls_fingerprints: [] +# tls_fingerprints: [{"sha256": ""}] @@ -483,16 +551,21 @@ enable_registration: {{ matrix_synapse_enable_registration|to_json }} # - email # - msisdn +# Explicitly disable asking for MSISDNs from the registration +# flow (overrides registrations_require_3pid if MSISDNs are set as required) +# +# disable_msisdn_registration = True + # Mandate that users are only allowed to associate certain formats of # 3PIDs with accounts on this server. # # allowed_local_3pids: # - medium: email -# pattern: ".*@matrix\.org" +# pattern: '.*@matrix\.org' # - medium: email -# pattern: ".*@vector\.im" +# pattern: '.*@vector\.im' # - medium: msisdn -# pattern: "\+44" +# pattern: '\+44' # If set, allows registration by anyone who also has the shared # secret, even if registration is otherwise disabled. @@ -510,8 +583,19 @@ bcrypt_rounds: 12 # accessible to anonymous users. allow_guest_access: False +# The identity server which we suggest that clients should use when users log +# in on this server. +# +# (By default, no suggestion is made, so it is left up to the client. +# This setting is ignored unless public_baseurl is also set.) +# +# default_identity_server: https://matrix.org + # The list of identity servers trusted to verify third party # identifiers by this server. +# +# Also defines the ID server which will be called when an account is +# deactivated (one will be picked arbitrarily). {% if matrix_synapse_trusted_third_party_id_servers|length > 0 %} trusted_third_party_id_servers: {{ matrix_synapse_trusted_third_party_id_servers|to_nice_yaml }} @@ -534,7 +618,6 @@ auto_join_rooms: autocreate_auto_join_rooms: {{ matrix_synapse_autocreate_auto_join_rooms }} - ## Metrics ### # Enable collection and rendering of performance metrics @@ -549,20 +632,29 @@ room_invite_state_types: - "m.room.join_rules" - "m.room.canonical_alias" - "m.room.avatar" + - "m.room.encryption" - "m.room.name" # A list of application service config file to use app_service_config_files: {{ matrix_synapse_app_service_config_files }} +# Whether or not to track application service IP addresses. Implicitly +# enables MAU tracking for application service users. +track_appservice_user_ips: False + +# a secret which is used to sign access tokens. If none is specified, +# the registration_shared_secret is used, if one is given; otherwise, +# a secret key is derived from the signing key. macaroon_secret_key: {{ matrix_synapse_macaroon_secret_key|to_json }} # Used to enable access token expiration. expire_access_token: False # a secret which is used to calculate HMACs for form values, to stop -# falsification of values +# falsification of values. Must be specified for the User Consent +# forms to work. form_secret: {{ matrix_synapse_form_secret|to_json }} ## Signing Keys ## @@ -595,15 +687,48 @@ perspectives: -# Enable SAML2 for registration and login. Uses pysaml2 -# config_path: Path to the sp_conf.py configuration file -# idp_redirect_url: Identity provider URL which will redirect -# the user back to /login/saml2 with proper info. -# See pysaml2 docs for format of config. -#saml2_config: -# enabled: true -# config_path: "/data/sp_conf.py" -# idp_redirect_url: "http://{{ hostname_matrix }}/idp" +# Enable SAML2 for registration and login. Uses pysaml2. +# +# saml2_config: +# +# # The following is the configuration for the pysaml2 Service Provider. +# # See pysaml2 docs for format of config. +# # +# # Default values will be used for the 'entityid' and 'service' settings, +# # so it is not normally necessary to specify them unless you need to +# # override them. +# +# sp_config: +# # point this to the IdP's metadata. You can use either a local file or +# # (preferably) a URL. +# metadata: +# # local: ["saml2/idp.xml"] +# remote: +# - url: https://our_idp/metadata.xml +# +# # The following is just used to generate our metadata xml, and you +# # may well not need it, depending on your setup. Alternatively you +# # may need a whole lot more detail - see the pysaml2 docs! +# +# description: ["My awesome SP", "en"] +# name: ["Test SP", "en"] +# +# organization: +# name: Example com +# display_name: +# - ["Example co", "en"] +# url: "http://example.com" +# +# contact_person: +# - given_name: Bob +# sur_name: "the Sysadmin" +# email_address": ["admin@example.com"] +# contact_type": technical +# +# # Instead of putting the config inline as above, you can specify a +# # separate pysaml2 configuration file: +# # +# # config_path: "/data/sp_conf.py" @@ -710,6 +835,7 @@ password_providers: {% endif %} + # Clients requesting push notifications can either have the body of # the message sent in the notification poke along with other details # like the sender, or just the event ID and room ID (`event_id_only`).