tileradotorg/synapse
1
0
Fork 0
forked from MirrorHub/synapse
Code Pull requests Activity

Merge pull request #4678 from matrix-org/rav/tls_install_instructions

Browse source 
Attempt to clarify installation/config instructions
This commit is contained in:
Richard van der Hoff 2019-02-20 11:10:33 +00:00 committed by GitHub
commit 86920ac266
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
26 changed files with 266 additions and 214 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
INSTALL.md
View file

@ -358,26 +358,25 @@ For information on using a reverse proxy, see
[docs/reverse_proxy.rst](docs/reverse_proxy.rst).
To configure Synapse to expose an HTTPS port, you will need to edit
`homeserver.yaml`.
`homeserver.yaml`, as follows:
First, under the `listeners` section, uncomment the configuration for the
TLS-enabled listener. (Remove the hash sign (`#`) and space at the start of
each line). The relevant lines are like this:
* First, under the `listeners` section, uncomment the configuration for the
TLS-enabled listener. (Remove the hash sign (`#`) at the start of
each line). The relevant lines are like this:
```
```
- port: 8448
type: http
tls: true
resources:
- names: [client, federation]
```
You will also need to uncomment the `tls_certificate_path` and
`tls_private_key_path` lines under the `TLS` section. You can either point
these settings at an existing certificate and key, or you can enable Synapse's
built-in ACME (Let's Encrypt) support. Instructions for having Synapse
automatically provision and renew federation certificates through ACME can be
found at [ACME.md](docs/ACME.md).
```
* You will also need to uncomment the `tls_certificate_path` and
`tls_private_key_path` lines under the `TLS` section. You can either
point these settings at an existing certificate and key, or you can
enable Synapse's built-in ACME (Let's Encrypt) support. Instructions
for having Synapse automatically provision and renew federation
certificates through ACME can be found at [ACME.md](docs/ACME.md).
## Registering a user

1
changelog.d/4681.misc Normal file
View file

@ -0,0 +1 @@
Attempt to clarify installation instructions/config

1
synapse/config/api.py
View file

@ -33,6 +33,7 @@ class ApiConfig(Config):
## API Configuration ##
# A list of event types that will be included in the room_invite_state
#
room_invite_state_types:
- "{JoinRules}"
- "{CanonicalAlias}"

2
synapse/config/appservice.py
View file

@ -38,10 +38,12 @@ class AppServiceConfig(Config):
def default_config(cls, **kwargs):
return """\
# A list of application service config file to use
#
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
"""

3
synapse/config/captcha.py
View file

@ -30,14 +30,17 @@ class CaptchaConfig(Config):
# See docs/CAPTCHA_SETUP for full details of configuring this.
# This Home Server's ReCAPTCHA public key.
#
recaptcha_public_key: "YOUR_PUBLIC_KEY"
# This Home Server's ReCAPTCHA private key.
#
recaptcha_private_key: "YOUR_PRIVATE_KEY"
# Enables ReCaptcha checks when registering, preventing signup
# unless a captcha is answered. Requires a valid ReCaptcha
# public/private key.
#
enable_registration_captcha: False
# A secret key used to bypass the captcha test entirely.

1
synapse/config/cas.py
View file

@ -38,6 +38,7 @@ class CasConfig(Config):
def default_config(self, config_dir_path, server_name, **kwargs):
return """
# Enable CAS for registration and login.
#
#cas_config:
# enabled: true
# server_url: "https://cas-server.com"

2
synapse/config/consent_config.py
View file

@ -54,7 +54,7 @@ DEFAULT_CONFIG = """\
# for an account. Has no effect unless `require_at_registration` is enabled.
# Defaults to "Privacy Policy".
#
# user_consent:
#user_consent:
# template_dir: res/templates/privacy
# version: 1.0
# server_notice_content:

4
synapse/config/groups.py
View file

@ -24,9 +24,11 @@ class GroupsConfig(Config):
def default_config(self, **kwargs):
return """\
# Whether to allow non server admins to create groups on this server
#
enable_group_creation: false
# If enabled, non server admins can only create groups with local parts
# starting with this prefix
# group_creation_prefix: "unofficial/"
#
#group_creation_prefix: "unofficial/"
"""

2
synapse/config/jwt_config.py
View file

@ -46,7 +46,7 @@ class JWTConfig(Config):
return """\
# The JWT needs to contain a globally unique "sub" (subject) claim.
#
# jwt_config:
#jwt_config:
# enabled: true
# secret: "a secret"
# algorithm: "HS256"

11
synapse/config/key.py
View file

@ -40,7 +40,7 @@ class KeyConfig(Config):
def read_config(self, config):
self.signing_key = self.read_signing_key(config["signing_key_path"])
self.old_signing_keys = self.read_old_signing_keys(
config["old_signing_keys"]
config.get("old_signing_keys", {})
)
self.key_refresh_interval = self.parse_duration(
config["key_refresh_interval"]
@ -83,24 +83,29 @@ class KeyConfig(Config):
# 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)s
# 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. Must be specified for the User Consent
# forms to work.
#
%(form_secret)s
## Signing Keys ##
# Path to the signing key to sign messages with
#
signing_key_path: "%(base_key_name)s.signing.key"
# The keys that the server used to sign messages with but won't use
# to sign new messages. E.g. it has lost its private key
old_signing_keys: {}
#
#old_signing_keys:
# "ed25519:auto":
# # Base64 encoded public key
# key: "The public part of your old signing key."
@ -111,9 +116,11 @@ class KeyConfig(Config):
# Used to set the valid_until_ts in /key/v2 APIs.
# Determines how quickly servers will query to check which keys
# are still valid.
#
key_refresh_interval: "1d" # 1 Day.
# The trusted servers to download signing keys from.
#
perspectives:
servers:
"matrix.org":

1
synapse/config/logger.py
View file

@ -83,6 +83,7 @@ class LoggingConfig(Config):
log_config = os.path.join(config_dir_path, server_name + ".log.config")
return """
# A yaml python logging config file
#
log_config: "%(log_config)s"
""" % locals()

2
synapse/config/metrics.py
View file

@ -47,6 +47,7 @@ class MetricsConfig(Config):
## Metrics ###
# Enable collection and rendering of performance metrics
#
enable_metrics: False
# Enable sentry integration
@ -55,6 +56,7 @@ class MetricsConfig(Config):
# this option the sentry server may therefore receive sensitive
# information, and it in turn may then diseminate sensitive information
# through insecure notification channels if so configured.
#
#sentry:
# dsn: "..."
"""

1
synapse/config/password.py
View file

@ -28,6 +28,7 @@ class PasswordConfig(Config):
def default_config(self, config_dir_path, server_name, **kwargs):
return """
# Enable password for login.
#
password_config:
enabled: true
# Uncomment and change to a secret random string for extra security.

2
synapse/config/password_auth_providers.py
View file

@ -52,7 +52,7 @@ class PasswordAuthProviderConfig(Config):
def default_config(self, **kwargs):
return """\
# password_providers:
#password_providers:
# - module: "ldap_auth_provider.LdapAuthProvider"
# config:
# enabled: true

2
synapse/config/push.py
View file

@ -51,7 +51,7 @@ class PushConfig(Config):
# notification request includes the content of the event (other details
# like the sender are still included). For `event_id_only` push, it
# has no effect.
#
# For modern android devices the notification content will still appear
# because it is loaded by the app. iPhone, however will send a
# notification saying only that a message arrived and who it came from.

7
synapse/config/ratelimiting.py
View file

@ -32,27 +32,34 @@ class RatelimitConfig(Config):
## Ratelimiting ##
# Number of messages a client can send per second
#
rc_messages_per_second: 0.2
# Number of message a client can send before being throttled
#
rc_message_burst_count: 10.0
# The federation window size in milliseconds
#
federation_rc_window_size: 1000
# The number of federation requests from a single server in a window
# before the server will delay processing the request.
#
federation_rc_sleep_limit: 10
# The duration in milliseconds to delay processing events from
# remote servers by if they go over the sleep limit.
#
federation_rc_sleep_delay: 500
# The maximum number of concurrent federation requests allowed
# from a single server
#
federation_rc_reject_limit: 50
# The number of federation requests to concurrently process from a
# single server
#
federation_rc_concurrent: 3
"""

14
synapse/config/registration.py
View file

@ -70,19 +70,19 @@ class RegistrationConfig(Config):
# The user must provide all of the below types of 3PID when registering.
#
# registrations_require_3pid:
#registrations_require_3pid:
# - 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
#disable_msisdn_registration: True
# Mandate that users are only allowed to associate certain formats of
# 3PIDs with accounts on this server.
#
# allowed_local_3pids:
#allowed_local_3pids:
# - medium: email
# pattern: '.*@matrix\\.org'
# - medium: email
@ -92,6 +92,7 @@ class RegistrationConfig(Config):
# If set, allows registration by anyone who also has the shared
# secret, even if registration is otherwise disabled.
#
%(registration_shared_secret)s
# Set the number of bcrypt rounds used to generate password hash.
@ -99,11 +100,13 @@ class RegistrationConfig(Config):
# The default number is 12 (which equates to 2^12 rounds).
# N.B. that increasing this will exponentially increase the time required
# to register or login - e.g. 24 => 2^24 rounds which will take >20 mins.
#
bcrypt_rounds: 12
# Allows users to register as guests without a password/email/etc, and
# participate in rooms hosted on this server which have been made
# accessible to anonymous users.
#
allow_guest_access: False
# The identity server which we suggest that clients should use when users log
@ -112,19 +115,21 @@ class RegistrationConfig(Config):
# (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
#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).
#
trusted_third_party_id_servers:
- matrix.org
- vector.im
# Users who register on this homeserver will automatically be joined
# to these rooms
#
#auto_join_rooms:
# - "#example:example.com"
@ -133,6 +138,7 @@ class RegistrationConfig(Config):
# homeserver registers.
# Setting to false means that if the rooms are not manually created,
# users cannot be auto-joined since they do not exist.
#
autocreate_auto_join_rooms: true
""" % locals()

19
synapse/config/repository.py
View file

@ -180,11 +180,13 @@ class ContentRepositoryConfig(Config):
uploads_path = os.path.join(data_dir_path, "uploads")
return r"""
# Directory where uploaded images and attachments are stored.
#
media_store_path: "%(media_store)s"
# Media storage providers allow media to be stored in different
# locations.
# media_storage_providers:
#
#media_storage_providers:
# - module: file_system
# # Whether to write new local files.
# store_local: false
@ -197,12 +199,15 @@ class ContentRepositoryConfig(Config):
# directory: /mnt/some/other/directory
# Directory where in-progress uploads are stored.
#
uploads_path: "%(uploads_path)s"
# The largest allowed upload size in bytes
#
max_upload_size: "10M"
# Maximum number of pixels that will be thumbnailed
#
max_image_pixels: "32M"
# Whether to generate new thumbnails on the fly to precisely match
@ -210,9 +215,11 @@ class ContentRepositoryConfig(Config):
# a new resolution is requested by the client the server will
# generate a new thumbnail. If false the server will pick a thumbnail
# from a precalculated list.
#
dynamic_thumbnails: false
# List of thumbnail to precalculate when an image is uploaded.
# List of thumbnails to precalculate when an image is uploaded.
#
thumbnail_sizes:
- width: 32
height: 32
@ -233,6 +240,7 @@ class ContentRepositoryConfig(Config):
# Is the preview URL API enabled? If enabled, you *must* specify
# an explicit url_preview_ip_range_blacklist of IPs that the spider is
# denied from accessing.
#
url_preview_enabled: False
# List of IP address CIDR ranges that the URL preview spider is denied
@ -243,7 +251,7 @@ class ContentRepositoryConfig(Config):
# synapse to issue arbitrary GET requests to your internal services,
# causing serious security issues.
#
# url_preview_ip_range_blacklist:
#url_preview_ip_range_blacklist:
# - '127.0.0.0/8'
# - '10.0.0.0/8'
# - '172.16.0.0/12'
@ -260,7 +268,7 @@ class ContentRepositoryConfig(Config):
# target IP ranges - e.g. for enabling URL previews for a specific private
# website only visible in your network.
#
# url_preview_ip_range_whitelist:
#url_preview_ip_range_whitelist:
# - '192.168.1.1'
# Optional list of URL matches that the URL preview spider is
@ -279,7 +287,7 @@ class ContentRepositoryConfig(Config):
# specified component matches for a given list item succeed, the URL is
# blacklisted.
#
# url_preview_url_blacklist:
#url_preview_url_blacklist:
# # blacklist any URL with a username in its URI
# - username: '*'
#
@ -300,5 +308,4 @@ class ContentRepositoryConfig(Config):
# The largest allowed URL preview spidering size in bytes
max_spider_size: "10M"
""" % locals()

4
synapse/config/room_directory.py
View file

@ -76,7 +76,7 @@ class RoomDirectoryConfig(Config):
#
# The default is:
#
# alias_creation_rules:
#alias_creation_rules:
# - user_id: "*"
# alias: "*"
# room_id: "*"
@ -105,7 +105,7 @@ class RoomDirectoryConfig(Config):
#
# The default is:
#
# room_list_publication_rules:
#room_list_publication_rules:
# - user_id: "*"
# alias: "*"
# room_id: "*"

19
synapse/config/saml2_config.py
View file

@ -67,24 +67,23 @@ class SAML2Config(Config):
return """
# Enable SAML2 for registration and login. Uses pysaml2.
#
# saml2_config:
# `sp_config` is the configuration for the pysaml2 Service Provider.
# See pysaml2 docs for format of 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.
# 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.
#
#saml2_config:
# 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"]
# #local: ["saml2/idp.xml"]
# remote:
# - url: https://our_idp/metadata.xml
#
# # The following is just used to generate our metadata xml, and you
# # The rest of sp_config 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!
#
@ -106,5 +105,5 @@ class SAML2Config(Config):
# # Instead of putting the config inline as above, you can specify a
# # separate pysaml2 configuration file:
# #
# # config_path: "%(config_dir_path)s/sp_conf.py"
# config_path: "%(config_dir_path)s/sp_conf.py"
""" % {"config_dir_path": config_dir_path}

70
synapse/config/server.py
View file

@ -286,19 +286,20 @@ class ServerConfig(Config):
#
# This setting requires the affinity package to be installed!
#
# cpu_affinity: 0xFFFFFFFF
#cpu_affinity: 0xFFFFFFFF
# 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"
#web_client_location: "/path/to/web/root"
# 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://example.com/
#
#public_baseurl: https://example.com/
# Set the soft limit on the number of file descriptors synapse can use
# Zero is used to indicate synapse should set the soft limit to the
@ -309,15 +310,25 @@ class ServerConfig(Config):
use_presence: true
# The GC threshold parameters to pass to `gc.set_threshold`, if defined
# gc_thresholds: [700, 10, 10]
#
#gc_thresholds: [700, 10, 10]
# Set the limit on the returned events in the timeline in the get
# and sync operations. The default value is -1, means no upper limit.
# filter_timeline_limit: 5000
#
#filter_timeline_limit: 5000
# Whether room invites to users on this server should be blocked
# (except those sent by local server admins). The default is False.
# block_non_admin_invites: True
#
#block_non_admin_invites: True
# 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: false
# Restrict federation to the following whitelist of domains.
# N.B. we recommend also firewalling your federation listener to limit
@ -325,7 +336,7 @@ class ServerConfig(Config):
# purely on this application-layer restriction. If not specified, the
# default is to whitelist everything.
#
# federation_domain_whitelist:
#federation_domain_whitelist:
# - lon.example.com
# - nyc.example.com
# - syd.example.com
@ -397,7 +408,7 @@ class ServerConfig(Config):
# will also need to give Synapse a TLS key and certificate: see the TLS section
# below.)
#
# - port: %(bind_port)s
#- port: %(bind_port)s
# type: http
# tls: true
# resources:
@ -421,52 +432,49 @@ class ServerConfig(Config):
# example additonal_resources:
#
# additional_resources:
#additional_resources:
# "/_matrix/my/custom/endpoint":
# module: my_module.CustomRequestHandler
# config: {}
# Turn on the twisted ssh manhole service on localhost on the given
# port.
# - port: 9000
#
#- port: 9000
# bind_addresses: ['::1', '127.0.0.1']
# type: manhole
# Homeserver blocking
#
## 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'
#admin_contact: 'mailto:admin@server.com'
# Global blocking
#
#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
#
#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
#
#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:
#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
""" % locals()
def read_arguments(self, args):

2
synapse/config/server_notices_config.py
View file

@ -30,7 +30,7 @@ DEFAULT_CONFIG = """\
# It's also possible to override the room name, the display name of the
# "notices" user, and the avatar for the user.
#
# server_notices:
#server_notices:
# system_mxid_localpart: notices
# system_mxid_display_name: "Server Notices"
# system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ"

2
synapse/config/spam_checker.py
View file

@ -28,7 +28,7 @@ class SpamCheckerConfig(Config):
def default_config(self, **kwargs):
return """\
# spam_checker:
#spam_checker:
# module: "my_custom_project.SuperSpamChecker"
# config:
# example_option: 'things'

20
synapse/config/tls.py
View file

@ -177,10 +177,11 @@ class TlsConfig(Config):
# See 'ACME support' below to enable auto-provisioning this certificate via
# Let's Encrypt.
#
# tls_certificate_path: "%(tls_certificate_path)s"
#tls_certificate_path: "%(tls_certificate_path)s"
# PEM-encoded private key for TLS
# tls_private_key_path: "%(tls_private_key_path)s"
#
#tls_private_key_path: "%(tls_private_key_path)s"
# ACME support: This will configure Synapse to request a valid TLS certificate
# for your configured `server_name` via Let's Encrypt.
@ -207,28 +208,28 @@ class TlsConfig(Config):
# 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
#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
#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
#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']
#bind_addresses: ['::', '0.0.0.0']
# How many days remaining on a certificate before it is renewed.
#
# reprovision_threshold: 30
#reprovision_threshold: 30
# The domain that the certificate should be for. Normally this
# should be the same as your Matrix domain (i.e., 'server_name'), but,
@ -242,7 +243,7 @@ class TlsConfig(Config):
#
# If not set, defaults to your 'server_name'.
#
# domain: matrix.example.com
#domain: matrix.example.com
# List of allowed TLS fingerprints for this server to publish along
# with the signing keys for this server. Other matrix servers that
@ -269,8 +270,7 @@ class TlsConfig(Config):
# 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": "<base64_encoded_sha256_fingerprint>"}]
#tls_fingerprints: [{"sha256": "<base64_encoded_sha256_fingerprint>"}]
"""
% locals()

7
synapse/config/voip.py
View file

@ -27,20 +27,24 @@ class VoipConfig(Config):
def default_config(self, **kwargs):
return """\
## Turn ##
## TURN ##
# The public URIs of the TURN server to give to clients
#
#turn_uris: []
# The shared secret used to compute passwords for the TURN server
#
#turn_shared_secret: "YOUR_SHARED_SECRET"
# The Username and password if the TURN server needs them and
# does not use a token
#
#turn_username: "TURNSERVER_USERNAME"
#turn_password: "TURNSERVER_PASSWORD"
# How long generated TURN credentials last
#
turn_user_lifetime: "1h"
# Whether guests should be allowed to use the TURN server.
@ -48,5 +52,6 @@ class VoipConfig(Config):
# However, it does introduce a slight security risk as it allows users to
# connect to arbitrary endpoints without having first signed up for a
# valid account (e.g. by passing a CAPTCHA).
#
turn_allow_guests: True
"""