Clean up default listener configuration (#4586)

Rearrange the comments to try to clarify them, and expand on what some of it
means.

Use a sensible default 'bind_addresses' setting.

For the insecure port, only bind to localhost, and enable x_forwarded, since
apparently it's for use behind a load-balancer.
This commit is contained in:
Richard van der Hoff 2019-02-11 12:50:30 +00:00 committed by GitHub
parent c475275926
commit 24b7f3916d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 82 additions and 48 deletions

1
changelog.d/4586.misc Normal file
View File

@ -0,0 +1 @@
Clean up default listener configuration

View File

@ -24,6 +24,14 @@ from ._base import Config, ConfigError
logger = logging.Logger(__name__) logger = logging.Logger(__name__)
# by default, we attempt to listen on both '::' *and* '0.0.0.0' because some OSes
# (Windows, macOS, other BSD/Linux where net.ipv6.bindv6only is set) will only listen
# on IPv6 when '::' is set.
#
# We later check for errors when binding to 0.0.0.0 and ignore them if :: is also in
# in the list.
DEFAULT_BIND_ADDRESSES = ['::', '0.0.0.0']
class ServerConfig(Config): class ServerConfig(Config):
@ -124,10 +132,13 @@ class ServerConfig(Config):
bind_address = listener.pop("bind_address", None) bind_address = listener.pop("bind_address", None)
bind_addresses = listener.setdefault("bind_addresses", []) bind_addresses = listener.setdefault("bind_addresses", [])
# if bind_address was specified, add it to the list of addresses
if bind_address: if bind_address:
bind_addresses.append(bind_address) bind_addresses.append(bind_address)
elif not bind_addresses:
bind_addresses.append('') # if we still have an empty list of addresses, use the default list
if not bind_addresses:
bind_addresses.extend(DEFAULT_BIND_ADDRESSES)
if not self.web_client_location: if not self.web_client_location:
_warn_if_webclient_configured(self.listeners) _warn_if_webclient_configured(self.listeners)
@ -295,76 +306,98 @@ class ServerConfig(Config):
# List of ports that Synapse should listen on, their purpose and their # List of ports that Synapse should listen on, their purpose and their
# configuration. # 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: listeners:
# Main HTTPS listener # Main HTTPS listener.
# For when matrix traffic is sent directly to synapse. # For when matrix traffic is sent directly to synapse.
- - port: %(bind_port)s
# The port to listen for HTTPS requests on.
port: %(bind_port)s
# 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:
- '::'
- '0.0.0.0'
# This is a 'http' listener, allows us to specify 'resources'.
type: http type: http
tls: true tls: true
# Use the X-Forwarded-For (XFF) header as the client IP and not the
# actual client IP.
x_forwarded: false
# List of HTTP resources to serve on this listener. # List of HTTP resources to serve on this listener.
resources: resources:
- - names: [client]
# List of resources to host on this listener.
names:
- client # The client-server APIs, both v1 and v2
# - webclient # A web client. Requires web_client_location to be set.
# Should synapse compress HTTP responses to clients that support it?
# This should be disabled if running synapse behind a load balancer
# that can do automatic compression.
compress: true compress: true
- names: [federation]
- names: [federation] # Federation APIs
compress: false compress: false
# # If federation is disabled synapse can still expose the open ID endpoint # example addional_resources:
# # to allow integrations to authenticate users #
# - names: [openid]
# compress: false
# optional list of additional endpoints which can be loaded via
# dynamic modules
# additional_resources: # additional_resources:
# "/_matrix/my/custom/endpoint": # "/_matrix/my/custom/endpoint":
# module: my_module.CustomRequestHandler # module: my_module.CustomRequestHandler
# config: {} # config: {}
# Unsecure HTTP listener, # Unsecure HTTP listener
# For when matrix traffic passes through loadbalancer that unwraps TLS. # For when matrix traffic passes through a reverse-proxy that unwraps TLS.
- port: %(unsecure_port)s - port: %(unsecure_port)s
tls: false tls: false
bind_addresses: ['::', '0.0.0.0'] bind_addresses: ['::1', '127.0.0.1']
type: http type: http
x_forwarded: true
x_forwarded: false
resources: resources:
- names: [client] - names: [client]
compress: true compress: true
- names: [federation] - names: [federation]
compress: false compress: false
# # If federation is disabled synapse can still expose the open ID endpoint
# # to allow integrations to authenticate users
# - names: [openid]
# compress: false
# Turn on the twisted ssh manhole service on localhost on the given # Turn on the twisted ssh manhole service on localhost on the given
# port. # port.