From 512e94d230756d96ffefd8011ae53d13f3f5514c Mon Sep 17 00:00:00 2001 From: Aaron Raimist Date: Tue, 4 Dec 2018 04:59:09 -0600 Subject: Add note to UPGRADE.rst about removing riot.im from list of trusted identity servers (#4224) * Add note to UPGRADE.rst about removing riot.im from list of trusted identity servers Signed-off-by: Aaron Raimist * Add changelog Signed-off-by: Aaron Raimist --- UPGRADE.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index 55c77eedde..aa5473ec62 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -48,6 +48,15 @@ returned by the Client-Server API: # configured on port 443. curl -kv https:///_matrix/client/versions 2>&1 | grep "Server:" +Upgrading to v0.34.0 +==================== + +This release removes the ``riot.im`` from the default list of trusted identity servers. + +If ``riot.im`` is in your homeserver's list of ``trusted_third_party_id_servers``, +you should remove it. It was added in case a hypothetical future identity server was +put there. If you don't remove it, users may be unable to deactivate their accounts. + Upgrading to v0.33.7 ==================== -- cgit 1.4.1 From 4acd1a35496e0a738a1f1966b1c623ccd0bccfca Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 4 Dec 2018 12:27:10 +0000 Subject: Notes on upgrading to python3, and README updates. --- README.rst | 67 ++++++++++++++------------------------------------- UPGRADE.rst | 67 ++++++++++++++++++++++++++++++++++++++++++++++++--- changelog.d/4260.misc | 1 + 3 files changed, 82 insertions(+), 53 deletions(-) create mode 100644 changelog.d/4260.misc (limited to 'UPGRADE.rst') diff --git a/README.rst b/README.rst index 8c55dd7894..664a0ea03f 100644 --- a/README.rst +++ b/README.rst @@ -86,7 +86,7 @@ Synapse is the reference Python/Twisted Matrix homeserver implementation. System requirements: - POSIX-compliant system (tested on Linux & OS X) -- Python 2.7 +- Python 3.5, 3.6, or 2.7 - At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org Installing from source @@ -101,13 +101,13 @@ header files for Python C extensions. Installing prerequisites on Ubuntu or Debian:: - sudo apt-get install build-essential python2.7-dev libffi-dev \ + sudo apt-get install build-essential python3-dev libffi-dev \ python-pip python-setuptools sqlite3 \ libssl-dev python-virtualenv libjpeg-dev libxslt1-dev Installing prerequisites on ArchLinux:: - sudo pacman -S base-devel python2 python-pip \ + sudo pacman -S base-devel python python-pip \ python-setuptools python-virtualenv sqlite3 Installing prerequisites on CentOS 7 or Fedora 25:: @@ -126,12 +126,9 @@ Installing prerequisites on Mac OS X:: Installing prerequisites on Raspbian:: - sudo apt-get install build-essential python2.7-dev libffi-dev \ + sudo apt-get install build-essential python3-dev libffi-dev \ python-pip python-setuptools sqlite3 \ libssl-dev python-virtualenv libjpeg-dev - sudo pip install --upgrade pip - sudo pip install --upgrade ndg-httpsclient - sudo pip install --upgrade virtualenv Installing prerequisites on openSUSE:: @@ -146,20 +143,21 @@ Installing prerequisites on OpenBSD:: To install the Synapse homeserver run:: - virtualenv -p python2.7 ~/.synapse - source ~/.synapse/bin/activate + mkdir -p ~/synapse + virtualenv -p python3 ~/synapse/env + source ~/synapse/env/bin/activate pip install --upgrade pip pip install --upgrade setuptools pip install matrix-synapse This installs Synapse, along with the libraries it uses, into a virtual -environment under ``~/.synapse``. Feel free to pick a different directory +environment under ``~/synapse/env``. Feel free to pick a different directory if you prefer. This Synapse installation can then be later upgraded by using pip again with the update flag:: - source ~/.synapse/bin/activate + source ~/synapse/env/bin/activate pip install -U matrix-synapse In case of problems, please see the _`Troubleshooting` section below. @@ -240,7 +238,7 @@ commandline script. To get started, it is easiest to use the command line to register new users:: - $ source ~/.synapse/bin/activate + $ source ~/synapse/env/bin/activate $ synctl start # if not already running $ register_new_matrix_user -c homeserver.yaml https://localhost:8448 New user localpart: erikj @@ -266,13 +264,12 @@ Running Synapse =============== To actually run your new homeserver, pick a working directory for Synapse to -run (e.g. ``~/.synapse``), and:: +run (e.g. ``~/synapse``), and:: - cd ~/.synapse - source ./bin/activate + cd ~/synapse + source env/bin/activate synctl start - Connecting to Synapse from a client =================================== @@ -380,35 +377,17 @@ the generated config), https://www.archlinux.org/packages/community/any/python2-matrix-angular-sdk/ will also need to be installed. -Alternatively, to install using pip a few changes may be needed as ArchLinux -defaults to python 3, but synapse currently assumes python 2.7 by default: - pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):: - sudo pip2.7 install --upgrade pip - -You also may need to explicitly specify python 2.7 again during the install -request:: - - pip2.7 install https://github.com/matrix-org/synapse/tarball/master + sudo pip install --upgrade pip If you encounter an error with lib bcrypt causing an Wrong ELF Class: ELFCLASS32 (x64 Systems), you may need to reinstall py-bcrypt to correctly compile it under the right architecture. (This should not be needed if installing under virtualenv):: - sudo pip2.7 uninstall py-bcrypt - sudo pip2.7 install py-bcrypt - -During setup of Synapse you need to call python2.7 directly again:: - - cd ~/.synapse - python2.7 -m synapse.app.homeserver \ - --server-name machine.my.domain.name \ - --config-path homeserver.yaml \ - --generate-config - -...substituting your host and domain name as appropriate. + sudo pip uninstall py-bcrypt + sudo pip install py-bcrypt FreeBSD ------- @@ -475,7 +454,7 @@ You can fix this by manually upgrading pip and virtualenv:: sudo pip install --upgrade virtualenv -You can next rerun ``virtualenv -p python2.7 synapse`` to update the virtual env. +You can next rerun ``virtualenv -p python3 synapse`` to update the virtual env. Installing may fail during installing virtualenv with ``InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning.`` You can fix this by manually installing ndg-httpsclient:: @@ -524,16 +503,6 @@ log lines and looking for any 'Processed request' lines which take more than a few seconds to execute. Please let us know at #matrix-dev:matrix.org if you see this failure mode so we can help debug it, however. -ArchLinux -~~~~~~~~~ - -If running `$ synctl start` fails with 'returned non-zero exit status 1', -you will need to explicitly call Python2.7 - either running as:: - - python2.7 -m synapse.app.homeserver --daemonize -c homeserver.yaml - -...or by editing synctl with the correct python executable. - Upgrading an existing Synapse ============================= @@ -731,7 +700,7 @@ port: * Until v0.33.3, Synapse did not support SNI on the federation port (`bug #1491 `_). This bug - is now fixed, but means that federating with older servers can be unreliable + is now fixed, but means that federating with older servers can be unreliable when using name-based virtual hosting. Furthermore, a number of the normal reasons for using a reverse-proxy do not diff --git a/UPGRADE.rst b/UPGRADE.rst index aa5473ec62..9d68a64058 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -51,11 +51,70 @@ returned by the Client-Server API: Upgrading to v0.34.0 ==================== -This release removes the ``riot.im`` from the default list of trusted identity servers. +1. This release is the first to fully support Python 3. We recommend switching + to Python 3, as it has been shown to give performance improvements. + + For users who have installed Synapse into a virtualenv, we recommend doing + this by creating a new virtualenv. For example:: + + virtualenv -p python3 ~/synapse/env3 + source ~/synapse/env3/bin/activate + pip install matrix-synapse + + You can then start synapse as normal, having activated the new virtualenv:: + + cd ~/synapse + source env3/bin/activate + synctl start + + Users who have installed from distribution packages should see the relevant + package documentation. + + * When upgrading to Python 3, you **must** make sure that your log files are + configured as UTF-8, by adding ``encoding: utf8`` to the + ``RotatingFileHandler`` configuration (if you have one) in your + ``.log.config`` file. For example, if your ``log.config`` file + contains:: + + handlers: + file: + class: logging.handlers.RotatingFileHandler + formatter: precise + filename: homeserver.log + maxBytes: 104857600 + backupCount: 10 + filters: [context] + console: + class: logging.StreamHandler + formatter: precise + filters: [context] + + Then you should update this to be:: + + handlers: + file: + class: logging.handlers.RotatingFileHandler + formatter: precise + filename: homeserver.log + maxBytes: 104857600 + backupCount: 10 + filters: [context] + encoding: utf8 + console: + class: logging.StreamHandler + formatter: precise + filters: [context] + + There is no need to revert this change if downgrading to Python 2. + +2. This release removes the ``riot.im`` from the default list of trusted + identity servers. + + If ``riot.im`` is in your homeserver's list of + ``trusted_third_party_id_servers``, you should remove it. It was added in + case a hypothetical future identity server was put there. If you don't + remove it, users may be unable to deactivate their accounts. -If ``riot.im`` is in your homeserver's list of ``trusted_third_party_id_servers``, -you should remove it. It was added in case a hypothetical future identity server was -put there. If you don't remove it, users may be unable to deactivate their accounts. Upgrading to v0.33.7 ==================== diff --git a/changelog.d/4260.misc b/changelog.d/4260.misc new file mode 100644 index 0000000000..0f7c4faf28 --- /dev/null +++ b/changelog.d/4260.misc @@ -0,0 +1 @@ +Update README.rst and UPGRADE.rst for Python 3. -- cgit 1.4.1 From df96177ca7f6f646baf96e779e0bf0ef38cc5168 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 11 Dec 2018 13:18:48 +0000 Subject: Stop installing Matrix Console by default This is based on the work done by @krombel in #2601. --- README.rst | 9 +-------- UPGRADE.rst | 4 ++++ changelog.d/4290.feature | 1 + synapse/app/homeserver.py | 43 +++++++++++------------------------------- synapse/config/server.py | 42 ++++++++++++++++++++++++++--------------- synapse/python_dependencies.py | 3 --- 6 files changed, 44 insertions(+), 58 deletions(-) create mode 100644 changelog.d/4290.feature (limited to 'UPGRADE.rst') diff --git a/README.rst b/README.rst index 664a0ea03f..02b3db1bc6 100644 --- a/README.rst +++ b/README.rst @@ -289,10 +289,6 @@ go back in your web client and proceed further. If all goes well you should at least be able to log in, create a room, and start sending messages. -(The homeserver runs a web client by default at https://localhost:8448/, though -as of the time of writing it is somewhat outdated and not really recommended - -https://github.com/matrix-org/synapse/issues/1527). - .. _`client-user-reg`: Registering a new user from a client @@ -372,10 +368,7 @@ ArchLinux The quickest way to get up and running with ArchLinux is probably with the community package https://www.archlinux.org/packages/community/any/matrix-synapse/, which should pull in most of -the necessary dependencies. If the default web client is to be served (enabled by default in -the generated config), -https://www.archlinux.org/packages/community/any/python2-matrix-angular-sdk/ will also need to -be installed. +the necessary dependencies. pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):: diff --git a/UPGRADE.rst b/UPGRADE.rst index 9d68a64058..95f4e33300 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -115,6 +115,10 @@ Upgrading to v0.34.0 case a hypothetical future identity server was put there. If you don't remove it, users may be unable to deactivate their accounts. +3. This release no longer installs the (unmaintained) Matrix Console web client + as part of the default installation. It is possible to re-enable it by + installing it separately and setting the ``web_client_location`` config + option, but please consider switching to another client. Upgrading to v0.33.7 ==================== diff --git a/changelog.d/4290.feature b/changelog.d/4290.feature new file mode 100644 index 0000000000..df5114bae9 --- /dev/null +++ b/changelog.d/4290.feature @@ -0,0 +1 @@ +Remove Matrix console from the default distribution diff --git a/synapse/app/homeserver.py b/synapse/app/homeserver.py index 3e4dea2f19..a6af553f79 100755 --- a/synapse/app/homeserver.py +++ b/synapse/app/homeserver.py @@ -54,7 +54,7 @@ from synapse.metrics import RegistryProxy from synapse.metrics.background_process_metrics import run_as_background_process from synapse.metrics.resource import METRICS_PREFIX, MetricsResource from synapse.module_api import ModuleApi -from synapse.python_dependencies import CONDITIONAL_REQUIREMENTS, check_requirements +from synapse.python_dependencies import check_requirements from synapse.replication.http import REPLICATION_PREFIX, ReplicationRestResource from synapse.replication.tcp.resource import ReplicationStreamProtocolFactory from synapse.rest import ClientRestResource @@ -79,36 +79,6 @@ def gz_wrap(r): return EncodingResourceWrapper(r, [GzipEncoderFactory()]) -def build_resource_for_web_client(hs): - webclient_path = hs.get_config().web_client_location - if not webclient_path: - try: - import syweb - except ImportError: - quit_with_error( - "Could not find a webclient.\n\n" - "Please either install the matrix-angular-sdk or configure\n" - "the location of the source to serve via the configuration\n" - "option `web_client_location`\n\n" - "To install the `matrix-angular-sdk` via pip, run:\n\n" - " pip install '%(dep)s'\n" - "\n" - "You can also disable hosting of the webclient via the\n" - "configuration option `web_client`\n" - % {"dep": CONDITIONAL_REQUIREMENTS["web_client"].keys()[0]} - ) - syweb_path = os.path.dirname(syweb.__file__) - webclient_path = os.path.join(syweb_path, "webclient") - # GZip is disabled here due to - # https://twistedmatrix.com/trac/ticket/7678 - # (It can stay enabled for the API resources: they call - # write() with the whole body and then finish() straight - # after and so do not trigger the bug. - # GzipFile was removed in commit 184ba09 - # return GzipFile(webclient_path) # TODO configurable? - return File(webclient_path) # TODO configurable? - - class SynapseHomeServer(HomeServer): DATASTORE_CLASS = DataStore @@ -237,7 +207,16 @@ class SynapseHomeServer(HomeServer): resources[SERVER_KEY_V2_PREFIX] = KeyApiV2Resource(self) if name == "webclient": - resources[WEB_CLIENT_PREFIX] = build_resource_for_web_client(self) + webclient_path = self.get_config().web_client_location + + if webclient_path is None: + logger.warning( + "Not enabling webclient resource, as web_client_location is unset." + ) + else: + # GZip is disabled here due to + # https://twistedmatrix.com/trac/ticket/7678 + resources[WEB_CLIENT_PREFIX] = File(webclient_path) if name == "metrics" and self.get_config().enable_metrics: resources[METRICS_PREFIX] = MetricsResource(RegistryProxy) diff --git a/synapse/config/server.py b/synapse/config/server.py index 4a5b902f8e..a9154ad462 100644 --- a/synapse/config/server.py +++ b/synapse/config/server.py @@ -34,7 +34,6 @@ class ServerConfig(Config): raise ConfigError(str(e)) self.pid_file = self.abspath(config.get("pid_file")) - self.web_client = config["web_client"] self.web_client_location = config.get("web_client_location", None) self.soft_file_limit = config["soft_file_limit"] self.daemonize = config.get("daemonize") @@ -128,6 +127,9 @@ class ServerConfig(Config): elif not bind_addresses: bind_addresses.append('') + if not self.web_client_location: + _warn_if_webclient_configured(self.listeners) + self.gc_thresholds = read_gc_thresholds(config.get("gc_thresholds", None)) bind_port = config.get("bind_port") @@ -136,8 +138,6 @@ class ServerConfig(Config): bind_host = config.get("bind_host", "") gzip_responses = config.get("gzip_responses", True) - names = ["client", "webclient"] if self.web_client else ["client"] - self.listeners.append({ "port": bind_port, "bind_addresses": [bind_host], @@ -145,7 +145,7 @@ class ServerConfig(Config): "type": "http", "resources": [ { - "names": names, + "names": ["client"], "compress": gzip_responses, }, { @@ -164,7 +164,7 @@ class ServerConfig(Config): "type": "http", "resources": [ { - "names": names, + "names": ["client"], "compress": gzip_responses, }, { @@ -247,13 +247,9 @@ class ServerConfig(Config): # # cpu_affinity: 0xFFFFFFFF - # Whether to serve a web client from the HTTP/HTTPS root resource. - web_client: True - - # 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/...) @@ -320,8 +316,8 @@ class ServerConfig(Config): - # List of resources to host on this listener. names: - - client # The client-server APIs, both v1 and v2 - - webclient # The bundled webclient. + - 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 @@ -348,7 +344,7 @@ class ServerConfig(Config): x_forwarded: false resources: - - names: [client, webclient] + - names: [client] compress: true - names: [federation] compress: false @@ -452,3 +448,19 @@ def read_gc_thresholds(thresholds): raise ConfigError( "Value of `gc_threshold` must be a list of three integers if set" ) + + +NO_MORE_WEB_CLIENT_WARNING = """ +Synapse no longer includes a web client. To enable a web client, configure +web_client_location. To remove this warning, remove 'webclient' from the 'listeners' +configuration. +""" + + +def _warn_if_webclient_configured(listeners): + for listener in listeners: + for res in listener.get("resources", []): + for name in res.get("names", []): + if name == 'webclient': + logger.warning(NO_MORE_WEB_CLIENT_WARNING) + return diff --git a/synapse/python_dependencies.py b/synapse/python_dependencies.py index ca62ee7637..92422c6ffc 100644 --- a/synapse/python_dependencies.py +++ b/synapse/python_dependencies.py @@ -69,9 +69,6 @@ REQUIREMENTS = { } CONDITIONAL_REQUIREMENTS = { - "web_client": { - "matrix_angular_sdk>=0.6.8": ["syweb>=0.6.8"], - }, "email.enable_notifs": { "Jinja2>=2.8": ["Jinja2>=2.8"], "bleach>=1.4.2": ["bleach>=1.4.2"], -- cgit 1.4.1 From 6dd72712436c9a0843c4a3ad197adfa4ecb8bffa Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 20 Dec 2018 12:07:15 +0000 Subject: Prepare 0.34 release --- CHANGES.md | 27 +++++++++------------------ UPGRADE.rst | 9 ++++++++- changelog.d/4212.misc | 1 - changelog.d/4284.bugfix | 1 - changelog.d/4294.bugfix | 1 - changelog.d/4295.bugfix | 1 - synapse/__init__.py | 2 +- 7 files changed, 18 insertions(+), 24 deletions(-) delete mode 100644 changelog.d/4212.misc delete mode 100644 changelog.d/4284.bugfix delete mode 100644 changelog.d/4294.bugfix delete mode 100644 changelog.d/4295.bugfix (limited to 'UPGRADE.rst') diff --git a/CHANGES.md b/CHANGES.md index 68210a7d60..a8744fb3d8 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,21 +1,5 @@ -Synapse 0.34.0rc2 (2018-12-11) -============================== - -Features --------- - -- Add a welcome page for the client API port. Credit to @krombel! ([\#4289](https://github.com/matrix-org/synapse/issues/4289)) -- Remove Matrix console from the default distribution ([\#4290](https://github.com/matrix-org/synapse/issues/4290)) - - -Internal Changes ----------------- - -- Disable pager when running git-show in CI ([\#4291](https://github.com/matrix-org/synapse/issues/4291)) - - -Synapse 0.34.0rc1 (2018-12-04) -============================== +Synapse 0.34.0 (2018-12-20) +=========================== Synapse 0.34 is the first release to fully support Python 3. We recommend upgrading to Python 3, but make sure to read the @@ -24,6 +8,11 @@ upgrading to Python 3, but make sure to read the Features -------- +- Add 'sandbox' to CSP for media reprository ([\#4284](https://github.com/matrix-org/synapse/issues/4284)) +- Make the new landing page prettier. ([\#4294](https://github.com/matrix-org/synapse/issues/4294)) +- Fix deleting E2E room keys when using old SQLite versions. ([\#4295](https://github.com/matrix-org/synapse/issues/4295)) +- Add a welcome page for the client API port. Credit to @krombel! ([\#4289](https://github.com/matrix-org/synapse/issues/4289)) +- Remove Matrix console from the default distribution ([\#4290](https://github.com/matrix-org/synapse/issues/4290)) - Add option to track MAU stats (but not limit people) ([\#3830](https://github.com/matrix-org/synapse/issues/3830)) - Add an option to enable recording IPs for appservice users ([\#3831](https://github.com/matrix-org/synapse/issues/3831)) - Rename login type m.login.cas to m.login.sso ([\#4220](https://github.com/matrix-org/synapse/issues/4220)) @@ -49,6 +38,8 @@ Bugfixes Internal Changes ---------------- +- Debian packages utilising a virtualenv with bundled dependencies can now be built. ([\#4212](https://github.com/matrix-org/synapse/issues/4212)) +- Disable pager when running git-show in CI ([\#4291](https://github.com/matrix-org/synapse/issues/4291)) - A coveragerc file, as well as the py36-coverage tox target, have been added. ([\#4180](https://github.com/matrix-org/synapse/issues/4180)) - Add a GitHub pull request template and add multiple issue templates ([\#4182](https://github.com/matrix-org/synapse/issues/4182)) - Update README to reflect the fact that #1491 is fixed ([\#4188](https://github.com/matrix-org/synapse/issues/4188)) diff --git a/UPGRADE.rst b/UPGRADE.rst index 95f4e33300..b431850863 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -68,7 +68,7 @@ Upgrading to v0.34.0 synctl start Users who have installed from distribution packages should see the relevant - package documentation. + package documentation. See below for notes on Debian packages. * When upgrading to Python 3, you **must** make sure that your log files are configured as UTF-8, by adding ``encoding: utf8`` to the @@ -107,6 +107,13 @@ Upgrading to v0.34.0 There is no need to revert this change if downgrading to Python 2. + * We are also making available Debian packages which will run Synapse on + Python 3. You can switch to these packages with ``apt-get install + matrix-synapse-py3``, however, please read + [debian/NEWS](https://github.com/matrix-org/synapse/blob/release-v0.34.0/debian/NEWS) + before doing so. The existing ``matrix-synapse`` packages will continue to + use Python 2 for the time being. + 2. This release removes the ``riot.im`` from the default list of trusted identity servers. diff --git a/changelog.d/4212.misc b/changelog.d/4212.misc deleted file mode 100644 index 42f2546cf9..0000000000 --- a/changelog.d/4212.misc +++ /dev/null @@ -1 +0,0 @@ -Debian packages utilising a virtualenv with bundled dependencies can now be built. diff --git a/changelog.d/4284.bugfix b/changelog.d/4284.bugfix deleted file mode 100644 index 4a9478fa28..0000000000 --- a/changelog.d/4284.bugfix +++ /dev/null @@ -1 +0,0 @@ -Add 'sandbox' to CSP for media reprository diff --git a/changelog.d/4294.bugfix b/changelog.d/4294.bugfix deleted file mode 100644 index 98114869fc..0000000000 --- a/changelog.d/4294.bugfix +++ /dev/null @@ -1 +0,0 @@ -Make the new landing page prettier. diff --git a/changelog.d/4295.bugfix b/changelog.d/4295.bugfix deleted file mode 100644 index e1603cbcda..0000000000 --- a/changelog.d/4295.bugfix +++ /dev/null @@ -1 +0,0 @@ -Fix deleting E2E room keys when using old SQLite versions. diff --git a/synapse/__init__.py b/synapse/__init__.py index d5f6dc2094..27241cb364 100644 --- a/synapse/__init__.py +++ b/synapse/__init__.py @@ -27,4 +27,4 @@ try: except ImportError: pass -__version__ = "0.34.0rc2" +__version__ = "0.34.0" -- cgit 1.4.1 From 8e4d9122b0325a5c5d9df0b40df25e895132e9a2 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 20 Dec 2018 12:09:16 +0000 Subject: fix UPGRADE formatting --- UPGRADE.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index b431850863..b8dead480a 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -107,12 +107,12 @@ Upgrading to v0.34.0 There is no need to revert this change if downgrading to Python 2. - * We are also making available Debian packages which will run Synapse on - Python 3. You can switch to these packages with ``apt-get install - matrix-synapse-py3``, however, please read - [debian/NEWS](https://github.com/matrix-org/synapse/blob/release-v0.34.0/debian/NEWS) - before doing so. The existing ``matrix-synapse`` packages will continue to - use Python 2 for the time being. + We are also making available Debian packages which will run Synapse on + Python 3. You can switch to these packages with ``apt-get install + matrix-synapse-py3``, however, please read `debian/NEWS + `_ + before doing so. The existing ``matrix-synapse`` packages will continue to + use Python 2 for the time being. 2. This release removes the ``riot.im`` from the default list of trusted identity servers. -- cgit 1.4.1 From dfeb274484323403cfac8c9bc7026130a298f30e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 20 Dec 2018 13:57:48 +0000 Subject: document supported python 3 versions --- CHANGES.md | 9 ++++++--- UPGRADE.rst | 5 +++-- 2 files changed, 9 insertions(+), 5 deletions(-) (limited to 'UPGRADE.rst') diff --git a/CHANGES.md b/CHANGES.md index f1332edf94..727275fa33 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,9 +1,12 @@ Synapse 0.34.0 (2018-12-20) =========================== -Synapse 0.34.0 is the first release to fully support Python 3. We recommend -upgrading to Python 3, but make sure to read the -[upgrade notes](UPGRADE.rst#upgrading-to-v0340) when doing so. +Synapse 0.34.0 is the first release to fully support Python 3. Synapse will now +run on Python versions 3.5 or 3.6 (as well as 2.7). Support for Python 3.7 +remains experimental. + +We recommend upgrading to Python 3, but make sure to read the [upgrade +notes](UPGRADE.rst#upgrading-to-v0340) when doing so. Features -------- diff --git a/UPGRADE.rst b/UPGRADE.rst index b8dead480a..b214a15526 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -51,8 +51,9 @@ returned by the Client-Server API: Upgrading to v0.34.0 ==================== -1. This release is the first to fully support Python 3. We recommend switching - to Python 3, as it has been shown to give performance improvements. +1. This release is the first to fully support Python 3. Synapse will now run on + Python versions 3.5, or 3.6 (as well as 2.7). We recommend switching to + Python 3, as it has been shown to give performance improvements. For users who have installed Synapse into a virtualenv, we recommend doing this by creating a new virtualenv. For example:: -- cgit 1.4.1 From 57a3e96e8ebf4a424e973c325e3b4e25cbdc27f1 Mon Sep 17 00:00:00 2001 From: Aaron Raimist Date: Mon, 28 Jan 2019 07:54:25 -0600 Subject: Remove --process-dependency-links from UPGRADE.rst (#4485) * Remove --process-dependency-links from UPGRADE.rst Signed-off-by: Aaron Raimist * Add changelog Signed-off-by: Aaron Raimist --- UPGRADE.rst | 2 +- changelog.d/4485.misc | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelog.d/4485.misc (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index b214a15526..47a8cb9c88 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -18,7 +18,7 @@ instructions that may be required are listed later in this document. .. code:: bash - pip install --upgrade --process-dependency-links matrix-synapse + pip install --upgrade matrix-synapse # restart synapse synctl restart diff --git a/changelog.d/4485.misc b/changelog.d/4485.misc new file mode 100644 index 0000000000..8aa0aeab2a --- /dev/null +++ b/changelog.d/4485.misc @@ -0,0 +1 @@ +Remove deprecated --process-dependency-links option from UPGRADE.rst -- cgit 1.4.1 From fbaee26c68a0db562994c50b4ac869ea8af3320f Mon Sep 17 00:00:00 2001 From: Amber Brown Date: Wed, 30 Jan 2019 16:22:37 +0000 Subject: ACME Upgrade Docs (#4528) --- UPGRADE.rst | 32 ++++++++++++++++++++++++++++++++ changelog.d/4528.doc | 1 + 2 files changed, 33 insertions(+) create mode 100644 changelog.d/4528.doc (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index 47a8cb9c88..c46f70f699 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -48,6 +48,38 @@ returned by the Client-Server API: # configured on port 443. curl -kv https:///_matrix/client/versions 2>&1 | grep "Server:" +Upgrading to v0.99.0 +==================== + +In preparation for Synapse v1.0, you must update your TLS certificates from +self-signed ones to verifiable ones signed by a trusted root CA. + +If you do not already have a certificate for your domain, the easiest way to get +one is with Synapse's new ACME support, which will use the ACME protocol to +provision a certificate automatically. By default, certificates will be obtained +from the publicly trusted CA Let's Encrypt. + +For a sample configuration, please inspect the new ACME section in the example +generated config by running the ``generate-config`` executable. For example:: + + ~/synapse/env3/bin/generate-config + +You will need to provide Let's Encrypt (or other ACME provider) access to your +Synapse ACME challenge responder on port 80, at the domain of your homeserver. +This requires you either change the port of the ACME listener provided by +Synapse to a high port and reverse proxy to it, or use a tool like authbind to +allow Synapse to listen on port 80 without root access. (Do not run Synapse with +root permissions!) + +You will need to back up or delete your self signed TLS certificate +(``example.com.tls.crt`` and ``example.com.tls.key``), Synapse's ACME +implementation will not overwrite them. + +You may wish to use alternate methods such as Certbot to obtain a certificate +from Let's Encrypt, depending on your server configuration. Of course, if you +already have a valid certificate for your homeserver's domain, that can be +placed in Synapse's config directory without the need for ACME. + Upgrading to v0.34.0 ==================== diff --git a/changelog.d/4528.doc b/changelog.d/4528.doc new file mode 100644 index 0000000000..432ef55aa6 --- /dev/null +++ b/changelog.d/4528.doc @@ -0,0 +1 @@ +Add documentation on enabling ACME support when upgrading to v0.99. -- cgit 1.4.1 From cd6fee3169659b13bfdb0f4b4d2a6132fd6b542c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 14:29:09 +0000 Subject: Don't imply self-signed certs are required --- UPGRADE.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index c46f70f699..f6cdec4734 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -51,34 +51,35 @@ returned by the Client-Server API: Upgrading to v0.99.0 ==================== -In preparation for Synapse v1.0, you must update your TLS certificates from -self-signed ones to verifiable ones signed by a trusted root CA. +In preparation for Synapse v1.0, you must ensure your federation TLS +certificates are verifiable by signed by a trusted root CA. -If you do not already have a certificate for your domain, the easiest way to get -one is with Synapse's new ACME support, which will use the ACME protocol to -provision a certificate automatically. By default, certificates will be obtained -from the publicly trusted CA Let's Encrypt. +If you do not already have a valid certificate for your domain, the easiest +way to get one is with Synapse's new ACME support, which will use the ACME +protocol to provision a certificate automatically. By default, certificates +will be obtained from the publicly trusted CA Let's Encrypt. For a sample configuration, please inspect the new ACME section in the example generated config by running the ``generate-config`` executable. For example:: ~/synapse/env3/bin/generate-config -You will need to provide Let's Encrypt (or other ACME provider) access to your -Synapse ACME challenge responder on port 80, at the domain of your homeserver. -This requires you either change the port of the ACME listener provided by -Synapse to a high port and reverse proxy to it, or use a tool like authbind to -allow Synapse to listen on port 80 without root access. (Do not run Synapse with -root permissions!) +You will need to provide Let's Encrypt (or another ACME provider) access to +your Synapse ACME challenge responder on port 80, at the domain of your +homeserver. This requires you to either change the port of the ACME listener +provided by Synapse to a high port and reverse proxy to it, or use a tool +like ``authbind`` to allow Synapse to listen on port 80 without root access. +(Do not run Synapse with root permissions!) -You will need to back up or delete your self signed TLS certificate -(``example.com.tls.crt`` and ``example.com.tls.key``), Synapse's ACME -implementation will not overwrite them. +If you are already using self-signed ceritifcates, you will need to back up +or delete them (files ``example.com.tls.crt`` and ``example.com.tls.key`` in +Synapse's root directory), Synapse's ACME implementation will not overwrite +them. You may wish to use alternate methods such as Certbot to obtain a certificate from Let's Encrypt, depending on your server configuration. Of course, if you already have a valid certificate for your homeserver's domain, that can be -placed in Synapse's config directory without the need for ACME. +placed in Synapse's config directory without the need for any ACME setup. Upgrading to v0.34.0 ==================== -- cgit 1.4.1 From 08b26afeee7b7db8c9d511cb63244927cf48ba9d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:29:42 +0000 Subject: Move ACME docs to docs/ACME.rst and link from UPGRADE. --- README.rst | 69 ----------------------------------------- UPGRADE.rst | 33 +++----------------- docs/ACME.rst | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 102 insertions(+), 98 deletions(-) create mode 100644 docs/ACME.rst (limited to 'UPGRADE.rst') diff --git a/README.rst b/README.rst index 9e3d85de4c..829de0864c 100644 --- a/README.rst +++ b/README.rst @@ -225,75 +225,6 @@ If you would like to use your own certificates, you can do so by changing alternatively, you can use a reverse-proxy. Apart from port 8448 using TLS, both ports are the same in the default configuration. - -ACME setup ----------- - -Synapse v1.0 will require valid TLS certificates for communication between servers -(port ``8448`` by default) in addition to those that are client-facing (port -``443``). In the case that your `server_name` config variable is the same as -the hostname that the client connects to, then the same certificate can be -used between client and federation ports without issue. Synapse v0.99.0+ -**will provision server-to-server certificates automatically for you for -free** through `Let's Encrypt -`_ if you tell it to. - -In order for Synapse to complete the ACME challenge to provision a -certificate, it needs access to port 80. Typically listening on port 80 is -only granted to applications running as root. There are thus two solutions to -this problem. - -**Using a reverse proxy** - -A reverse proxy such as Apache or nginx allows a single process (the web -server) to listen on port 80 and proxy traffic to the appropriate program -running on your server. It is the recommended method for setting up ACME as -it allows you to use your existing webserver while also allowing Synapse to -provision certificates as needed. - -For nginx users, add the following line to your existing ``server`` block:: - - location /.well-known/acme-challenge { - proxy_pass http://localhost:8009/; - } - -For Apache, add the following to your existing webserver config:: - - ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge - -Make sure to restart/reload your webserver after making changes. - - -**Authbind** - -``authbind`` allows a program which does not run as root to bind to -low-numbered ports in a controlled way. The setup is simpler, but requires a -webserver not to already be running on port 80. **This includes every time -Synapse renews a certificate**, which may be cumbersome if you usually run a -web server on port 80. Nevertheless, if you're sure port 80 is not being used -for any other purpose then all that is necessary is the following: - -Install ``authbind``. For example, on Debian/Ubuntu:: - - sudo apt-get install authbind - -Allow ``authbind`` to bind port 80:: - - sudo touch /etc/authbind/byport/80 - sudo chmod 777 /etc/authbind/byport/80 - -When Synapse is started, use the following syntax:: - - authbind --deep - -Finally, once Synapse's is able to listen on port 80 for ACME challenge -requests, it must be told to perform ACME provisioning by setting ``enabled`` -to true under the ``acme`` section in ``homeserver.yaml``:: - - acme: - enabled: true - - Registering a user ------------------ diff --git a/UPGRADE.rst b/UPGRADE.rst index f6cdec4734..74d2452749 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -51,35 +51,10 @@ returned by the Client-Server API: Upgrading to v0.99.0 ==================== -In preparation for Synapse v1.0, you must ensure your federation TLS -certificates are verifiable by signed by a trusted root CA. - -If you do not already have a valid certificate for your domain, the easiest -way to get one is with Synapse's new ACME support, which will use the ACME -protocol to provision a certificate automatically. By default, certificates -will be obtained from the publicly trusted CA Let's Encrypt. - -For a sample configuration, please inspect the new ACME section in the example -generated config by running the ``generate-config`` executable. For example:: - - ~/synapse/env3/bin/generate-config - -You will need to provide Let's Encrypt (or another ACME provider) access to -your Synapse ACME challenge responder on port 80, at the domain of your -homeserver. This requires you to either change the port of the ACME listener -provided by Synapse to a high port and reverse proxy to it, or use a tool -like ``authbind`` to allow Synapse to listen on port 80 without root access. -(Do not run Synapse with root permissions!) - -If you are already using self-signed ceritifcates, you will need to back up -or delete them (files ``example.com.tls.crt`` and ``example.com.tls.key`` in -Synapse's root directory), Synapse's ACME implementation will not overwrite -them. - -You may wish to use alternate methods such as Certbot to obtain a certificate -from Let's Encrypt, depending on your server configuration. Of course, if you -already have a valid certificate for your homeserver's domain, that can be -placed in Synapse's config directory without the need for any ACME setup. +No special steps are required, but please be aware that you will need to +replace any self-signed certificates with those verified by a root CA before +Synapse v1.0 releases in roughly a month's time after v0.99.0. Information on +how to do so can be found at `the ACME docs `_. Upgrading to v0.34.0 ==================== diff --git a/docs/ACME.rst b/docs/ACME.rst new file mode 100644 index 0000000000..2562e85dbc --- /dev/null +++ b/docs/ACME.rst @@ -0,0 +1,98 @@ +ACME +==== + +Synapse v1.0 requires that federation TLS certificates are verifiable by a +trusted root CA. If you do not already have a valid certificate for your domain, the easiest +way to get one is with Synapse's new ACME support, which will use the ACME +protocol to provision a certificate automatically. By default, certificates +will be obtained from the publicly trusted CA Let's Encrypt. + +For a sample configuration, please inspect the new ACME section in the example +generated config by running the ``generate-config`` executable. For example:: + + ~/synapse/env3/bin/generate-config + +You will need to provide Let's Encrypt (or another ACME provider) access to +your Synapse ACME challenge responder on port 80, at the domain of your +homeserver. This requires you to either change the port of the ACME listener +provided by Synapse to a high port and reverse proxy to it, or use a tool +like ``authbind`` to allow Synapse to listen on port 80 without root access. +(Do not run Synapse with root permissions!) Detailed instructions are +available under "ACME setup" below. + +If you are already using self-signed certificates, you will need to back up +or delete them (files ``example.com.tls.crt`` and ``example.com.tls.key`` in +Synapse's root directory), Synapse's ACME implementation will not overwrite +them. + +You may wish to use alternate methods such as Certbot to obtain a certificate +from Let's Encrypt, depending on your server configuration. Of course, if you +already have a valid certificate for your homeserver's domain, that can be +placed in Synapse's config directory without the need for any ACME setup. + +ACME setup +---------- + +Synapse v1.0 will require valid TLS certificates for communication between servers +(port ``8448`` by default) in addition to those that are client-facing (port +``443``). In the case that your `server_name` config variable is the same as +the hostname that the client connects to, then the same certificate can be +used between client and federation ports without issue. Synapse v0.99.0+ +will provision server-to-server certificates automatically for you for +free through `Let's Encrypt +`_ if you tell it to. + +In order for Synapse to complete the ACME challenge to provision a +certificate, it needs access to port 80. Typically listening on port 80 is +only granted to applications running as root. There are thus two solutions to +this problem. + +**Using a reverse proxy** + +A reverse proxy such as Apache or nginx allows a single process (the web +server) to listen on port 80 and proxy traffic to the appropriate program +running on your server. It is the recommended method for setting up ACME as +it allows you to use your existing webserver while also allowing Synapse to +provision certificates as needed. + +For nginx users, add the following line to your existing ``server`` block:: + + location /.well-known/acme-challenge { + proxy_pass http://localhost:8009/; + } + +For Apache, add the following to your existing webserver config:: + + ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge + +Make sure to restart/reload your webserver after making changes. + + +**Authbind** + +``authbind`` allows a program which does not run as root to bind to +low-numbered ports in a controlled way. The setup is simpler, but requires a +webserver not to already be running on port 80. **This includes every time +Synapse renews a certificate**, which may be cumbersome if you usually run a +web server on port 80. Nevertheless, if you're sure port 80 is not being used +for any other purpose then all that is necessary is the following: + +Install ``authbind``. For example, on Debian/Ubuntu:: + + sudo apt-get install authbind + +Allow ``authbind`` to bind port 80:: + + sudo touch /etc/authbind/byport/80 + sudo chmod 777 /etc/authbind/byport/80 + +When Synapse is started, use the following syntax:: + + authbind --deep + +Finally, once Synapse's is able to listen on port 80 for ACME challenge +requests, it must be told to perform ACME provisioning by setting ``enabled`` +to true under the ``acme`` section in ``homeserver.yaml``:: + + acme: + enabled: true -- cgit 1.4.1 From cbdc01cc3b826879b43ad4e8e9c1acacc60cd34b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 15:38:27 +0000 Subject: Convert ACME docs to md --- README.rst | 2 +- UPGRADE.rst | 2 +- docs/ACME.rst | 98 ----------------------------------------------------------- 3 files changed, 2 insertions(+), 100 deletions(-) delete mode 100644 docs/ACME.rst (limited to 'UPGRADE.rst') diff --git a/README.rst b/README.rst index 47f8ef62db..b7b3b20159 100644 --- a/README.rst +++ b/README.rst @@ -229,7 +229,7 @@ ACME setup ---------- For details on having Synapse manage your federation TLS certificates -automatically, please see ``_. +automatically, please see ``_. Registering a user ------------------ diff --git a/UPGRADE.rst b/UPGRADE.rst index 74d2452749..948867f189 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -54,7 +54,7 @@ Upgrading to v0.99.0 No special steps are required, but please be aware that you will need to replace any self-signed certificates with those verified by a root CA before Synapse v1.0 releases in roughly a month's time after v0.99.0. Information on -how to do so can be found at `the ACME docs `_. +how to do so can be found at `the ACME docs `_. Upgrading to v0.34.0 ==================== diff --git a/docs/ACME.rst b/docs/ACME.rst deleted file mode 100644 index 2562e85dbc..0000000000 --- a/docs/ACME.rst +++ /dev/null @@ -1,98 +0,0 @@ -ACME -==== - -Synapse v1.0 requires that federation TLS certificates are verifiable by a -trusted root CA. If you do not already have a valid certificate for your domain, the easiest -way to get one is with Synapse's new ACME support, which will use the ACME -protocol to provision a certificate automatically. By default, certificates -will be obtained from the publicly trusted CA Let's Encrypt. - -For a sample configuration, please inspect the new ACME section in the example -generated config by running the ``generate-config`` executable. For example:: - - ~/synapse/env3/bin/generate-config - -You will need to provide Let's Encrypt (or another ACME provider) access to -your Synapse ACME challenge responder on port 80, at the domain of your -homeserver. This requires you to either change the port of the ACME listener -provided by Synapse to a high port and reverse proxy to it, or use a tool -like ``authbind`` to allow Synapse to listen on port 80 without root access. -(Do not run Synapse with root permissions!) Detailed instructions are -available under "ACME setup" below. - -If you are already using self-signed certificates, you will need to back up -or delete them (files ``example.com.tls.crt`` and ``example.com.tls.key`` in -Synapse's root directory), Synapse's ACME implementation will not overwrite -them. - -You may wish to use alternate methods such as Certbot to obtain a certificate -from Let's Encrypt, depending on your server configuration. Of course, if you -already have a valid certificate for your homeserver's domain, that can be -placed in Synapse's config directory without the need for any ACME setup. - -ACME setup ----------- - -Synapse v1.0 will require valid TLS certificates for communication between servers -(port ``8448`` by default) in addition to those that are client-facing (port -``443``). In the case that your `server_name` config variable is the same as -the hostname that the client connects to, then the same certificate can be -used between client and federation ports without issue. Synapse v0.99.0+ -will provision server-to-server certificates automatically for you for -free through `Let's Encrypt -`_ if you tell it to. - -In order for Synapse to complete the ACME challenge to provision a -certificate, it needs access to port 80. Typically listening on port 80 is -only granted to applications running as root. There are thus two solutions to -this problem. - -**Using a reverse proxy** - -A reverse proxy such as Apache or nginx allows a single process (the web -server) to listen on port 80 and proxy traffic to the appropriate program -running on your server. It is the recommended method for setting up ACME as -it allows you to use your existing webserver while also allowing Synapse to -provision certificates as needed. - -For nginx users, add the following line to your existing ``server`` block:: - - location /.well-known/acme-challenge { - proxy_pass http://localhost:8009/; - } - -For Apache, add the following to your existing webserver config:: - - ProxyPass /.well-known/acme-challenge http://localhost:8009/.well-known/acme-challenge - -Make sure to restart/reload your webserver after making changes. - - -**Authbind** - -``authbind`` allows a program which does not run as root to bind to -low-numbered ports in a controlled way. The setup is simpler, but requires a -webserver not to already be running on port 80. **This includes every time -Synapse renews a certificate**, which may be cumbersome if you usually run a -web server on port 80. Nevertheless, if you're sure port 80 is not being used -for any other purpose then all that is necessary is the following: - -Install ``authbind``. For example, on Debian/Ubuntu:: - - sudo apt-get install authbind - -Allow ``authbind`` to bind port 80:: - - sudo touch /etc/authbind/byport/80 - sudo chmod 777 /etc/authbind/byport/80 - -When Synapse is started, use the following syntax:: - - authbind --deep - -Finally, once Synapse's is able to listen on port 80 for ACME challenge -requests, it must be told to perform ACME provisioning by setting ``enabled`` -to true under the ``acme`` section in ``homeserver.yaml``:: - - acme: - enabled: true -- cgit 1.4.1 From e119cec229202b8c6f0429fa1586c1a28f1925e3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 5 Feb 2019 16:45:41 +0000 Subject: Update INSTALL --- UPGRADE.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index 948867f189..eee38d5228 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -51,10 +51,10 @@ returned by the Client-Server API: Upgrading to v0.99.0 ==================== -No special steps are required, but please be aware that you will need to -replace any self-signed certificates with those verified by a root CA before -Synapse v1.0 releases in roughly a month's time after v0.99.0. Information on -how to do so can be found at `the ACME docs `_. +Please be aware that, before Synapse v1.0 is released around March 2019, you +will need to replace any self-signed certificates with those verified by a +root CA. Information on how to do so can be found at `the ACME docs +`_. Upgrading to v0.34.0 ==================== -- cgit 1.4.1 From 6585ef47991478ed1617f78f992b35b63475a2d7 Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Tue, 5 Feb 2019 17:19:28 +0000 Subject: Neilj/1711faq (#4572) MSC1711 certificates FAQ --- UPGRADE.rst | 2 + changelog.d/4572.misc | 1 + docs/MSC1711_certificates_FAQ.md | 260 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 263 insertions(+) create mode 100644 changelog.d/4572.misc create mode 100644 docs/MSC1711_certificates_FAQ.md (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index c46f70f699..7bd631f14c 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -80,6 +80,8 @@ from Let's Encrypt, depending on your server configuration. Of course, if you already have a valid certificate for your homeserver's domain, that can be placed in Synapse's config directory without the need for ACME. +For more information on configuring TLS certificates see the `FAQ `_ + Upgrading to v0.34.0 ==================== diff --git a/changelog.d/4572.misc b/changelog.d/4572.misc new file mode 100644 index 0000000000..ea5d49b706 --- /dev/null +++ b/changelog.d/4572.misc @@ -0,0 +1 @@ +FAQ to help server admins configure TLS certs in 0.99.0 diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md new file mode 100644 index 0000000000..0dcef57733 --- /dev/null +++ b/docs/MSC1711_certificates_FAQ.md @@ -0,0 +1,260 @@ +# MSC 1711 Certificates FAQ + +The goal of Synapse 0.99.0 is to act as a stepping stone to Synapse 1.0.0. It +supports the r0.1 release of the server to server specification, but is +compatible with both the legacy Matrix federation behaviour (pre-r0.1) as well +as post-r0.1 behaviour, in order to allow for a smooth upgrade across the +federation. + +The most important thing to know is that Synapse 1.0.0 will require a valid TLS +certificate on federation endpoints. Self signed certificates will not be +sufficient. + +Synapse 0.99.0 makes it easy to configure TLS certificates and will +interoperate with both >= 1.0.0 servers as well as existing servers yet to +upgrade. + +**It is critical that all admins upgrade to 0.99.0 and configure a valid TLS +certificate.** Admins will have 1 month to do so, after which 1.0.0 will be +released and those servers without a valid certificate will not longer be able +to federate with >= 1.0.0 servers. + +If you are unable to generate a valid TLS certificate for your server (e.g. +because you run it on behalf of someone who doesn't want to give you a TLS +certificate for their domain, or simply because the matrix domain is hosted on +a different server), then you can now create a /.well-known/matrix/server file +on the matrix domain in order to delegate Matrix hosting to another domain. + Admins who currently use SRV records to delegate a domain **which they do not +control TLS for** will need to switch to using .well-known/matrix/server - though +they should retain their SRV record while the federation upgrades over the +course of the month.  Other SRV records are unaffected. + +Full upgrade notes can be found in +[UPGRADE.rst](https://github.com/matrix-org/synapse/blob/master/UPGRADE.rst). +What follows is a timeline and some frequently asked questions. + +For more details and context on the release of the r0.1 Server/Server API and +imminent Matrix 1.0 release, you can also see our +[main talk from FOSDEM 2019](https://matrix.org/blog/2019/02/04/matrix-at-fosdem-2019/). + +## Contents +* Timeline +* Synapse 0.99.0 has just been released, what do I need to do right now? +* How do I upgrade? +* What will happen if I do not set up a valid federation certificate + immediately? +* What will happen if I do nothing at all? +* When do I need a SRV record or .well-known URI? +* Can I still use an SRV record? +* I have created a .well-known URI. Do I still need an SRV record? +* It used to work just fine, why are you breaking everything? +* Can I manage my own certificates rather than having Synapse renew + certificates itself? +* Do you still recommend against using a reverse-proxy on the federation port? +* Do I still need to give my TLS certificates to Synapse if I am using a + reverse-proxy? +* Do I need the same certificate for the client and federation port? +* How do I tell Synapse to reload my keys/certificates after I replace them? + + +### Timeline + +**5th Feb 2019 - Synapse 0.99.0 is released.** + +All server admins are encouraged to upgrade. + +0.99.0: + +- provides support for ACME to make setting up Let's Encrypt certs easy, as + well as .well-known support. + +- does not enforce that a valid CA cert is present on the federation API, but + rather makes it easy to set one up. + +- provides support for .well-known + +Admins should upgrade and configure a valid CA cert. Homeservers that require a +.well-known entry (see below), should retain their SRV record and use it +alongside their .well-known record. + +**>= 5th March 2019 - Synapse 1.0.0 is released** + +1.0.0 will land no sooner than 1 month after 0.99.0, leaving server admins one +month after 5th February to upgrade to 0.99.0 and deploy their certificates. In +accordance with the the [S2S spec](https://matrix.org/docs/spec/server_server/r0.1.0.html) +1.0.0 will enforce federation checks. This means that any homeserver without a +valid certificate after this point will no longer be able to federate with +1.0.0 servers. + +### Synapse 0.99.0 has just been released, what do I need to do right now? + +Upgrade as soon as you can in preparation for Synapse 1.0.0. + +### How do I upgrade? + +Follow the upgrade notes here [UPGRADE.rst](https://github.com/matrix-org/synapse/blob/master/UPGRADE.rst) + +### What will happen if I do not set up a valid federation certificate immediately? + +Nothing initially, but once 1.0.0 is in the wild it will not be possible to +federate with 1.0.0 servers. + +### What will happen if I do nothing at all? + +If the admin takes no action at all, and remains on a Synapse < 0.99.0 then the +homeserver will be unable to federate with those who have implemented +.well-known. Then, as above, once the month upgrade window has expired the +homeserver will not be able to federate with any Synapse >= 1.0.0 + +### When do I need a SRV record or .well-known URI? + +If your homeserver listens on the default federation port (8448), and your +server_name points to the host that your homeserver runs on, you do not need an +SRV record or .well-known/matrix/server URI.\ +For instance, if you registered example.com and pointed its DNS A record at a +fresh Upcloud VPS or similar, you could install Synapse 0.99 on that host, +giving it a server_name of example.com, and it would automatically generate a +valid TLS certificate for you via Let's Encrypt and no SRV record or +.well-known URI would be needed. + +This is the common case, although you can add an SRV record or +.well-known/matrix/server URI for completeness if you wish. + +**However**, if your server does not listen on port 8448, or if your server_name +does not point to the host that your homeserver runs on, you will need to let +other servers know how to find it. + +The easiest way to do this is with a .well-known/matrix/server URI on the +webroot of the domain to advertise your server. For instance, if you ran +"matrixhosting.com" and you were hosting a Matrix server for example.com, you +would ask example.com to create a file at: + +`https://example.com/.well-known/matrix/server` + +with contents: + +`{"m.server": "example.matrixhosting.com:8448"}` + +...which would tell servers trying to connect to example.com to instead connect +to example.matrixhosting.com on port 8448. You would then configure Synapse +with a server_name of "example.com", but generate a TLS certificate for +example.matrixhosting.com. + +As an alternative, you can still use an SRV DNS record for the delegation, but +this will require you to have a certificate for the matrix domain (example.com +in this example). See "Can I still use an SRV record?". + +### Can I still use an SRV record? + +Firstly, if you didn't need an SRV record before (because your server is +listening on port 8448 of your server_name), you certainly don't need one now: +the defaults are still the same. + +If you previously had an SRV record, you can keep using it provided you are +able to give Synapse a TLS certificate corresponding to your server name. For +example, suppose you had the following SRV record, which directs matrix traffic +for example.com to matrix.example.com:443: + +``` +_matrix._tcp.example.com. IN SRV 10 5 443 matrix.example.com +``` + +In this case, Synapse must be given a certificate for example.com - or be +configured to acquire one from Let's Encrypt. + +If you are unable to give Synapse a certificate for your server_name, you will +also need to use a .well-known URI instead. However, see also "I have created a +.well-known URI. Do I still need an SRV record?". + +### I have created a .well-known URI. Do I still need an SRV record? + +As of Synapse 0.99, Synapse will first check for the existence of a .well-known +URL and follow any delegation it suggests. It will only then check for the +existence of an SRV record. + +That means that the SRV record will often be redundant. However, you should +remember that there may still be older versions of Synapse in the federation +which do not understand .well-known URIs, so if you removed your SRV record you +would no longer be able to federate with them. + +It is therefore best to leave the SRV record in place for now. Synapse 0.34 and +earlier will follow the SRV record (and not care about the invalid +certificate). Synapse 0.99 and later will follow the .well-known URI, with the +correct certificate chain. + +### It used to work just fine, why are you breaking everything? + +We have always wanted Matrix servers to be as easy to set up as possible, and +so back when we started federation in 2014 we didn't want admins to have to go +through the cumbersome process of buying a valid TLS certificate to run a +server. This was before Let's Encrypt came along and made getting a free and +valid TLS certificate straightforward. So instead, we adopted a system based on +[Perspectives](https://en.wikipedia.org/wiki/Convergence_(SSL)): an approach +where you check a set of "notary servers" (in practice, homeservers) to vouch +for the validity of a certificate rather than having it signed by a CA. As long +as enough different notaries agree on the certificate's validity, then it is +trusted. + +However, in practice this has never worked properly. Most people only use the +default notary server (matrix.org), leading to inadvertent centralisation which +we want to eliminate. Meanwhile, we never implemented the full consensus +algorithm to query the servers participating in a room to determine consensus +on whether a given certificate is valid. This is fiddly to get right +(especially in face of sybil attacks), and we found ourselves questioning +whether it was worth the effort to finish the work and commit to maintaining a +secure certificate validation system as opposed to focusing on core Matrix +development. + +Meanwhile, Let's Encrypt came along in 2016, and put the final nail in the +coffin of the Perspectives project (which was already pretty dead). So, the +Spec Core Team decided that a better approach would be to mandate valid TLS +certificates for federation alongside the rest of the Web. More details can be +found in +[MSC1711](https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md#background-the-failure-of-the-perspectives-approach). + +This results in a breaking change, which is disruptive, but absolutely critical +for the security model. However, the existence of Let's Encrypt as a trivial +way to replace the old self-signed certificates with valid CA-signed ones helps +smooth things over massively, especially as Synapse can now automate Let's +Encrypt certificate generation if needed. + +### Can I manage my own certificates rather than having Synapse renew certificates itself? + +Yes, you are welcome to manage your certificates yourself. Synapse will only +attempt to obtain certificates from Let's Encrypt if you configure it to do +so.The only requirement is that there is a valid TLS cert present for +federation end points. + +### Do you still recommend against using a reverse-proxy on the federation port? + +We no longer actively recommend against using a reverse proxy. Many admins will +find it easier to direct federation traffic to a reverse-proxy and manage their +own TLS certificates, and this is a supported configuration. + +### Do I still need to give my TLS certificates to Synapse if I am using a reverse proxy? + +Practically speaking, this is no longer necessary. + +If you are using a reverse-proxy for all of your TLS traffic, then you can set +`no_tls: True`. In that case, the only reason Synapse needs the certificate is +to populate a legacy 'tls_fingerprints' field in the federation API. This is +ignored by Synapse 0.99.0 and later, and the only time pre-0.99 Synapses will +check it is when attempting to fetch the server keys - and generally this is +delegated via `matrix.org`, which is on 0.99.0. + +However, there is a bug in Synapse 0.99.0 +[4554]() which prevents +Synapse from starting if you do not give it a TLS certificate. To work around +this, you can give it any TLS certificate at all. This will be fixed soon. + +### Do I need the same certificate for the client and federation port? + +No. There is nothing stopping you doing so, particularly if you are using a +reverse-proxy. However, Synapse will use the same certificate on any ports +where TLS is configured. + +### How do I tell Synapse to reload my keys/certificates after I replace them? + +Synapse will reload the keys and certificates when it receives a SIGHUP - for +example kill -HUP $(cat homeserver.pid). Alternatively, simply restart Synapse, +though this will result in downtime while it restarts. -- cgit 1.4.1 From 61dc53abe9ac6fce9a69a6655262853a66c09b11 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 5 Feb 2019 17:36:05 +0000 Subject: fix some thinkos in UPGRADE.rst --- UPGRADE.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index 75aef366bd..3643477250 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -5,20 +5,20 @@ Before upgrading check if any special steps are required to upgrade from the what you currently have installed to current version of synapse. The extra instructions that may be required are listed later in this document. -1. If synapse was installed in a virtualenv then active that virtualenv before - upgrading. If synapse is installed in a virtualenv in ``~/.synapse/`` then +1. If synapse was installed in a virtualenv then activate that virtualenv before + upgrading. If synapse is installed in a virtualenv in ``~/synapse/env`` then run: .. code:: bash - source ~/.synapse/bin/activate + source ~/synapse/env/bin/activate 2. If synapse was installed using pip then upgrade to the latest version by running: .. code:: bash - pip install --upgrade matrix-synapse + pip install --upgrade matrix-synapse[all] # restart synapse synctl restart @@ -31,8 +31,9 @@ instructions that may be required are listed later in this document. # Pull the latest version of the master branch. git pull - # Update the versions of synapse's python dependencies. - python synapse/python_dependencies.py | xargs pip install --upgrade + + # Update synapse and its python dependencies. + pip install --upgrade .[all] # restart synapse ./synctl restart -- cgit 1.4.1 From b05dd4ac06e88797477ef1991d1b2e44583afb9a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 5 Feb 2019 18:59:57 +0000 Subject: faq cleanups --- UPGRADE.rst | 2 +- docs/MSC1711_certificates_FAQ.md | 54 ++++++++++++++-------------------------- 2 files changed, 19 insertions(+), 37 deletions(-) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index 3643477250..d869b7111b 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -57,7 +57,7 @@ will need to replace any self-signed certificates with those verified by a root CA. Information on how to do so can be found at `the ACME docs `_. -For more information on configuring TLS certificates see the `FAQ `_ +For more information on configuring TLS certificates see the `FAQ `_. Upgrading to v0.34.0 ==================== diff --git a/docs/MSC1711_certificates_FAQ.md b/docs/MSC1711_certificates_FAQ.md index efe6330647..eee37d9457 100644 --- a/docs/MSC1711_certificates_FAQ.md +++ b/docs/MSC1711_certificates_FAQ.md @@ -1,4 +1,4 @@ -# MSC 1711 Certificates FAQ +# MSC1711 Certificates FAQ The goal of Synapse 0.99.0 is to act as a stepping stone to Synapse 1.0.0. It supports the r0.1 release of the server to server specification, but is @@ -165,11 +165,8 @@ You can do this with a `.well-known` file as follows: ### Synapse 0.99.0 has just been released, what do I need to do right now? -Upgrade as soon as you can in preparation for Synapse 1.0.0. - -### How do I upgrade? - -Follow the upgrade notes here [UPGRADE.rst](https://github.com/matrix-org/synapse/blob/master/UPGRADE.rst) +Upgrade as soon as you can in preparation for Synapse 1.0.0, and update your +TLS certificates as [above](#configuring-certificates-for-compatibility-with-synapse-100). ### What will happen if I do not set up a valid federation certificate immediately? @@ -186,39 +183,24 @@ homeserver will not be able to federate with any Synapse >= 1.0.0 ### When do I need a SRV record or .well-known URI? If your homeserver listens on the default federation port (8448), and your -server_name points to the host that your homeserver runs on, you do not need an -SRV record or .well-known/matrix/server URI.\ -For instance, if you registered example.com and pointed its DNS A record at a +`server_name` points to the host that your homeserver runs on, you do not need an +SRV record or `.well-known/matrix/server` URI. + +For instance, if you registered `example.com` and pointed its DNS A record at a fresh Upcloud VPS or similar, you could install Synapse 0.99 on that host, -giving it a server_name of example.com, and it would automatically generate a +giving it a server_name of `example.com`, and it would automatically generate a valid TLS certificate for you via Let's Encrypt and no SRV record or -.well-known URI would be needed. +`.well-known` URI would be needed. This is the common case, although you can add an SRV record or -.well-known/matrix/server URI for completeness if you wish. +`.well-known/matrix/server` URI for completeness if you wish. -**However**, if your server does not listen on port 8448, or if your server_name +**However**, if your server does not listen on port 8448, or if your `server_name` does not point to the host that your homeserver runs on, you will need to let other servers know how to find it. -The easiest way to do this is with a .well-known/matrix/server URI on the -webroot of the domain to advertise your server. For instance, if you ran -"matrixhosting.com" and you were hosting a Matrix server for `example.com`, you -would ask `example.com` to create a file at -`https://example.com/.well-known/matrix/server` with contents: - -```json -{"m.server": "example.matrixhosting.com:8448"} -``` - -...which would tell servers trying to connect to example.com to instead connect -to example.matrixhosting.com on port 8448. You would then configure Synapse -with a server_name of "example.com", but generate a TLS certificate for -example.matrixhosting.com. - -As an alternative, you can still use an SRV DNS record for the delegation, but -this will require you to have a certificate for the matrix domain (example.com -in this example). See "Can I still use an SRV record?". +In this case, you should see ["If you do have an SRV record +currently"](#if-you-do-have-an-srv-record-currently) above. ### Can I still use an SRV record? @@ -244,13 +226,13 @@ also need to use a .well-known URI instead. However, see also "I have created a ### I have created a .well-known URI. Do I still need an SRV record? -As of Synapse 0.99, Synapse will first check for the existence of a .well-known -URL and follow any delegation it suggests. It will only then check for the +As of Synapse 0.99, Synapse will first check for the existence of a `.well-known` +URI and follow any delegation it suggests. It will only then check for the existence of an SRV record. That means that the SRV record will often be redundant. However, you should remember that there may still be older versions of Synapse in the federation -which do not understand .well-known URIs, so if you removed your SRV record you +which do not understand `.well-known` URIs, so if you removed your SRV record you would no longer be able to federate with them. It is therefore best to leave the SRV record in place for now. Synapse 0.34 and @@ -332,5 +314,5 @@ where TLS is configured. ### How do I tell Synapse to reload my keys/certificates after I replace them? Synapse will reload the keys and certificates when it receives a SIGHUP - for -example kill -HUP $(cat homeserver.pid). Alternatively, simply restart Synapse, -though this will result in downtime while it restarts. +example `kill -HUP $(cat homeserver.pid)`. Alternatively, simply restart +Synapse, though this will result in downtime while it restarts. -- cgit 1.4.1 From 6575df647da9d946dae0a41881d27b1569fff9c5 Mon Sep 17 00:00:00 2001 From: "Juuso \"Linda\" Lapinlampi" Date: Fri, 8 Feb 2019 21:26:16 +0000 Subject: UPGRADE.rst: Fix a typo in "Upgrading Synapse" section See: https://en.wiktionary.org/wiki/successful --- UPGRADE.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'UPGRADE.rst') diff --git a/UPGRADE.rst b/UPGRADE.rst index d869b7111b..228222d534 100644 --- a/UPGRADE.rst +++ b/UPGRADE.rst @@ -39,7 +39,7 @@ instructions that may be required are listed later in this document. ./synctl restart -To check whether your update was sucessful, you can check the Server header +To check whether your update was successful, you can check the Server header returned by the Client-Server API: .. code:: bash -- cgit 1.4.1