Create 6032.misc

Update saml.md
Add developer docs for using SAML without a server
2019-09-12 14:21:22 -06:00 · 2019-09-12 14:19:49 -06:00 · 2019-09-12 13:52:10 -06:00
1426 changed files with 62839 additions and 162150 deletions
@@ -0,0 +1,22 @@
 version: '3.1'
 services:
  postgres:
    image: postgres:9.5
    environment:
      POSTGRES_PASSWORD: postgres
    command: -c fsync=off
  testenv:
    image: python:3.5
    depends_on:
      - postgres
    env_file: .env
    environment:
      SYNAPSE_POSTGRES_HOST: postgres
      SYNAPSE_POSTGRES_USER: postgres
      SYNAPSE_POSTGRES_PASSWORD: postgres
    working_dir: /src
    volumes:
      - ..:/src
@@ -0,0 +1,22 @@
 version: '3.1'
 services:
  postgres:
    image: postgres:11
    environment:
      POSTGRES_PASSWORD: postgres
    command: -c fsync=off
  testenv:
    image: python:3.7
    depends_on:
      - postgres
    env_file: .env
    environment:
      SYNAPSE_POSTGRES_HOST: postgres
      SYNAPSE_POSTGRES_USER: postgres
      SYNAPSE_POSTGRES_PASSWORD: postgres
    working_dir: /src
    volumes:
      - ..:/src
@@ -0,0 +1,22 @@
 version: '3.1'
 services:
  postgres:
    image: postgres:9.5
    environment:
      POSTGRES_PASSWORD: postgres
    command: -c fsync=off
  testenv:
    image: python:3.7
    depends_on:
      - postgres
    env_file: .env
    environment:
      SYNAPSE_POSTGRES_HOST: postgres
      SYNAPSE_POSTGRES_USER: postgres
      SYNAPSE_POSTGRES_PASSWORD: postgres
    working_dir: /src
    volumes:
      - ..:/src
@@ -0,0 +1,48 @@
 # -*- coding: utf-8 -*-
 # Copyright 2019 The Matrix.org Foundation C.I.C.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 import sys
 from tap.parser import Parser
 from tap.line import Result, Unknown, Diagnostic
 out = ["### TAP Output for " + sys.argv[2]]
 p = Parser()
 in_error = False
 for line in p.parse_file(sys.argv[1]):
    if isinstance(line, Result):
        if in_error:
            out.append("")
            out.append("</pre></code></details>")
            out.append("")
            out.append("----")
            out.append("")
        in_error = False
        if not line.ok and not line.todo:
            in_error = True
            out.append("FAILURE Test #%d: ``%s``" % (line.number, line.description))
            out.append("")
            out.append("<details><summary>Show log</summary><code><pre>")
    elif isinstance(line, Diagnostic) and in_error:
        out.append(line.text)
 if out:
    for line in out[:-3]:
        print(line)
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-set -e
+set -ex
 if [[ "$BUILDKITE_BRANCH" =~ ^(develop|master|dinsic|shhs|release-.*)$ ]]; then
    echo "Not merging forward, as this is a release branch"
@@ -18,8 +18,6 @@ else
    GITBASE=$BUILDKITE_PULL_REQUEST_BASE_BRANCH
 fi
 echo "--- merge_base_branch $GITBASE"
 # Show what we are before
 git --no-pager show -s
@@ -1,19 +0,0 @@
 # Configuration file used for testing the 'synapse_port_db' script.
 # Tells the script to connect to the postgresql database that will be available in the
 # CI's Docker setup at the point where this file is considered.
 server_name: "localhost:8800"
 signing_key_path: ".buildkite/test.signing.key"
 report_stats: false
 database:
  name: "psycopg2"
  args:
    user: postgres
    host: postgres
    password: postgres
    database: synapse
 # Suppress the key server warning.
 trusted_key_servers: []
@@ -1,31 +0,0 @@
 #!/usr/bin/env python
 # Copyright 2019 The Matrix.org Foundation C.I.C.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 #     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 import sys
 import psycopg2
 # a very simple replacment for `psql`, to make up for the lack of the postgres client
 # libraries in the synapse docker image.
 # We use "postgres" as a database because it's bound to exist and the "synapse" one
 # doesn't exist yet.
 db_conn = psycopg2.connect(
    user="postgres", host="postgres", password="postgres", dbname="postgres"
 )
 db_conn.autocommit = True
 cur = db_conn.cursor()
 for c in sys.argv[1:]:
    cur.execute(c)
@@ -1,16 +0,0 @@
 #!/usr/bin/env bash
 # this script is run by buildkite in a plain `bionic` container; it installs the
 # minimal requirements for tox and hands over to the py3-old tox environment.
 set -ex
 apt-get update
 apt-get install -y python3 python3-dev python3-pip libxml2-dev libxslt-dev xmlsec1 zlib1g-dev tox
 export LANG="C.UTF-8"
 # Prevent virtualenv from auto-updating pip to an incompatible version
 export VIRTUALENV_NO_DOWNLOAD=1
 exec tox -e py3-old,combine
@@ -1,57 +0,0 @@
 #!/usr/bin/env bash
 #
 # Test script for 'synapse_port_db'.
 #   - sets up synapse and deps
 #   - runs the port script on a prepopulated test sqlite db
 #   - also runs it against an new sqlite db
 set -xe
 cd `dirname $0`/../..
 echo "--- Install dependencies"
 # Install dependencies for this test.
 pip install psycopg2 coverage coverage-enable-subprocess
 # Install Synapse itself. This won't update any libraries.
 pip install -e .
 echo "--- Generate the signing key"
 # Generate the server's signing key.
 python -m synapse.app.homeserver --generate-keys -c .buildkite/sqlite-config.yaml
 echo "--- Prepare test database"
 # Make sure the SQLite3 database is using the latest schema and has no pending background update.
 scripts-dev/update_database --database-config .buildkite/sqlite-config.yaml
 # Create the PostgreSQL database.
 ./.buildkite/scripts/postgres_exec.py "CREATE DATABASE synapse"
 echo "+++ Run synapse_port_db against test database"
 coverage run scripts/synapse_port_db --sqlite-database .buildkite/test_db.db --postgres-config .buildkite/postgres-config.yaml
 # We should be able to run twice against the same database.
 echo "+++ Run synapse_port_db a second time"
 coverage run scripts/synapse_port_db --sqlite-database .buildkite/test_db.db --postgres-config .buildkite/postgres-config.yaml
 #####
 # Now do the same again, on an empty database.
 echo "--- Prepare empty SQLite database"
 # we do this by deleting the sqlite db, and then doing the same again.
 rm .buildkite/test_db.db
 scripts-dev/update_database --database-config .buildkite/sqlite-config.yaml
 # re-create the PostgreSQL database.
 ./.buildkite/scripts/postgres_exec.py \
  "DROP DATABASE synapse" \
  "CREATE DATABASE synapse"
 echo "+++ Run synapse_port_db against empty database"
 coverage run scripts/synapse_port_db --sqlite-database .buildkite/test_db.db --postgres-config .buildkite/postgres-config.yaml
@@ -1,16 +0,0 @@
 # Configuration file used for testing the 'synapse_port_db' script.
 # Tells the 'update_database' script to connect to the test SQLite database to upgrade its
 # schema and run background updates on it.
 server_name: "localhost:8800"
 signing_key_path: ".buildkite/test.signing.key"
 report_stats: false
 database:
  name: "sqlite3"
  args:
    database: ".buildkite/test_db.db"
 # Suppress the key server warning.
 trusted_key_servers: []
@@ -1,10 +1,30 @@
 # This file serves as a blacklist for SyTest tests that we expect will fail in
 # Synapse when run under worker mode. For more details, see sytest-blacklist.
 Message history can be paginated
 Can re-join room if re-invited
-# new failures as of https://github.com/matrix-org/sytest/pull/732
+/upgrade creates a new room
 Device list doesn't change if remote server is down
-# https://buildkite.com/matrix-dot-org/synapse/builds/6134#6f67bf47-e234-474d-80e8-c6e1868b15c5
+The only membership state included in an initial sync is for all the senders in the timeline
-Server correctly handles incoming m.device_list_update
+
 Local device key changes get to remote servers
 If remote user leaves room we no longer receive device updates
 Forgotten room messages cannot be paginated
 Inbound federation can get public room list
 Members from the gap are included in gappy incr LL sync
 Leaves are present in non-gapped incremental syncs
 Old leaves are present in gapped incremental syncs
 User sees updates to presence from other users in the incremental sync.
 Gapped incremental syncs include all state changes
 Old members are included in gappy incr LL sync if they start speaking
@@ -1,35 +1,24 @@
-version: 2.1
+version: 2
 jobs:
  dockerhubuploadrelease:
-    docker:
+    machine: true
      - image: docker:git
    steps:
      - checkout
-      - docker_prepare
+      - run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:${CIRCLE_TAG} -t matrixdotorg/synapse:${CIRCLE_TAG}-py3 .
      - run: docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
-      # for release builds, we want to get the amd64 image out asap, so first
+      - run: docker push matrixdotorg/synapse:${CIRCLE_TAG}
-      # we do an amd64-only build, before following up with a multiarch build.
+      - run: docker push matrixdotorg/synapse:${CIRCLE_TAG}-py3
      - docker_build:
          tag: -t matrixdotorg/synapse:${CIRCLE_TAG}
          platforms: linux/amd64
      - docker_build:
          tag: -t matrixdotorg/synapse:${CIRCLE_TAG}
          platforms: linux/amd64,linux/arm64
  dockerhubuploadlatest:
-    docker:
+    machine: true
      - image: docker:git
    steps:
      - checkout
-      - docker_prepare
+      - run: docker build -f docker/Dockerfile --label gitsha1=${CIRCLE_SHA1} -t matrixdotorg/synapse:latest -t matrixdotorg/synapse:latest-py3 .
      - run: docker login --username $DOCKER_HUB_USERNAME --password $DOCKER_HUB_PASSWORD
-      # for `latest`, we don't want the arm images to disappear, so don't update the tag
+      - run: docker push matrixdotorg/synapse:latest
-      # until all of the platforms are built.
+      - run: docker push matrixdotorg/synapse:latest-py3
      - docker_build:
          tag: -t matrixdotorg/synapse:latest
          platforms: linux/amd64,linux/arm64
 workflows:
  version: 2
  build:
    jobs:
      - dockerhubuploadrelease:
@@ -41,38 +30,4 @@ workflows:
      - dockerhubuploadlatest:
          filters:
            branches:
-              only: [ master, main ]
+              only: master
 commands:
  docker_prepare:
    description: Sets up a remote docker server, downloads the buildx cli plugin, and enables multiarch images
    parameters:
      buildx_version:
        type: string
        default: "v0.4.1"
    steps:
      - setup_remote_docker:
          # 19.03.13 was the most recent available on circleci at the time of
          # writing.
          version: 19.03.13
      - run: apk add --no-cache curl
      - run: mkdir -vp ~/.docker/cli-plugins/ ~/dockercache
      - run: curl --silent -L "https://github.com/docker/buildx/releases/download/<< parameters.buildx_version >>/buildx-<< parameters.buildx_version >>.linux-amd64" > ~/.docker/cli-plugins/docker-buildx
      - run: chmod a+x ~/.docker/cli-plugins/docker-buildx
      # install qemu links in /proc/sys/fs/binfmt_misc on the docker instance running the circleci job
      - run: docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
      # create a context named `builder` for the builds
      - run: docker context create builder
      # create a buildx builder using the new context, and set it as the default
      - run: docker buildx create builder --use
  docker_build:
    description: Builds and pushed images to dockerhub using buildx
    parameters:
      platforms:
        type: string
        default: linux/amd64
      tag:
        type: string
    steps:
      - run: docker buildx build -f docker/Dockerfile --push --platform << parameters.platforms >> --label gitsha1=${CIRCLE_SHA1} << parameters.tag >> --progress=plain .
@@ -1,8 +0,0 @@
 # Black reformatting (#5482).
 32e7c9e7f20b57dd081023ac42d6931a8da9b3a3
 # Target Python 3.5 with black (#8664).
 aff1eb7c671b0a3813407321d2702ec46c71fa56
 # Update black to 20.8b1 (#9381).
 0a00b7ff14890987f09112a2ae696c61001e6cf1
@@ -1,5 +0,0 @@
 **If you are looking for support** please ask in **#synapse:matrix.org**
 (using a matrix.org account if necessary). We do not use GitHub issues for
 support.
 **If you want to report a security issue** please see https://matrix.org/security-disclosure-policy/
@@ -6,11 +6,9 @@ about: Create a report to help us improve
 <!--
-**THIS IS NOT A SUPPORT CHANNEL!**
+**IF YOU HAVE SUPPORT QUESTIONS ABOUT RUNNING OR CONFIGURING YOUR OWN HOME SERVER**:
-**IF YOU HAVE SUPPORT QUESTIONS ABOUT RUNNING OR CONFIGURING YOUR OWN HOME SERVER**,
+You will likely get better support more quickly if you ask in ** #matrix:matrix.org ** ;)
 please ask in **#synapse:matrix.org** (using a matrix.org account if necessary)
 If you want to report a security issue, please see https://matrix.org/security-disclosure-policy/
 This is a bug report template. By following the instructions below and
 filling out the sections with your information, you will help the us to get all
@@ -46,26 +44,22 @@ those (please be careful to remove any personal or private data). Please surroun
 <!-- IMPORTANT: please answer the following questions, to help us narrow down the problem -->
 <!-- Was this issue identified on matrix.org or another homeserver? -->
- **Homeserver**:
+- **Homeserver**: 
 If not matrix.org:
 <!--
- What version of Synapse is running?
+What version of Synapse is running?
-
+You can find the Synapse version by inspecting the server headers (replace matrix.org with
-You can find the Synapse version with this command:
+your own homeserver domain):
-
+$ curl -v https://matrix.org/_matrix/client/versions 2>&1 | grep "Server:"
 $ curl http://localhost:8008/_synapse/admin/v1/server_version
 (You may need to replace `localhost:8008` if Synapse is not configured to
 listen on that port.)
 -->
- **Version**:
+- **Version**: 
- **Install method**:
+- **Install method**: 
 <!-- examples: package manager/git clone/pip  -->
- **Platform**:
+- **Platform**: 
 <!--
 Tell us about the environment in which your homeserver is operating
 distro, hardware, if it's running in a vm/container, etc.
@@ -1,12 +1,7 @@
 ### Pull Request Checklist
-<!-- Please read CONTRIBUTING.md before submitting your pull request -->
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
 * [ ] Pull request is based on the develop branch
-* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.md#changelog). The entry should:
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.rst#changelog)
-  - Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from `EventStore` to `EventWorkerStore`.".
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.rst#sign-off)
  - Use markdown where necessary, mostly for `code blocks`.
  - End with either a period (.) or an exclamation mark (!).
  - Start with a capital letter.
 * [ ] Pull request includes a [sign off](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.md#sign-off)
 * [ ] Code style is correct (run the [linters](https://github.com/matrix-org/synapse/blob/master/CONTRIBUTING.md#code-style))
@@ -1,64 +0,0 @@
 name: Deploy the documentation
 on:
  push:
    branches:
      # For bleeding-edge documentation
      - develop
      # For documentation specific to a release
      - 'release-v*'
  workflow_dispatch:
 jobs:
  pages:
    name: GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup mdbook
        uses: peaceiris/actions-mdbook@4b5ef36b314c2599664ca107bb8c02412548d79d # v1.1.14
        with:
          mdbook-version: '0.4.9'
      - name: Build the documentation
        run: mdbook build
      # Deploy to the latest documentation directories
      - name: Deploy latest documentation
        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          keep_files: true
          publish_dir: ./book
          destination_dir: ./develop
      - name: Get the current Synapse version
        id: vars
        # The $GITHUB_REF value for a branch looks like `refs/heads/release-v1.2`. We do some
        # shell magic to remove the "refs/heads/release-v" bit from this, to end up with "1.2",
        # our major/minor version number, and set this to a var called `branch-version`.
        #
        # We then use some python to get Synapse's full version string, which may look
        # like "1.2.3rc4". We set this to a var called `synapse-version`. We use this
        # to determine if this release is still an RC, and if so block deployment.
        run: |
          echo ::set-output name=branch-version::${GITHUB_REF#refs/heads/release-v}
          echo ::set-output name=synapse-version::`python3 -c 'import synapse; print(synapse.__version__)'`
      # Deploy to the version-specific directory
      - name: Deploy release-specific documentation
        # We only carry out this step if we're running on a release branch,
        # and the current Synapse version does not have "rc" in the name.
        #
        # The result is that only full releases are deployed, but can be
        # updated if the release branch gets retroactive fixes.
        if: ${{ startsWith( github.ref, 'refs/heads/release-v' ) && !contains( steps.vars.outputs.synapse-version, 'rc') }}
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          keep_files: true
          publish_dir: ./book
          # The resulting documentation will end up in a directory named `vX.Y`.
          destination_dir: ./v${{ steps.vars.outputs.branch-version }}
@@ -1,346 +0,0 @@
 name: Tests
 on:
  push:
    branches: ["develop", "release-*"]
  pull_request:
 jobs:
  lint:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        toxenv:
          - "check-sampleconfig"
          - "check_codestyle"
          - "check_isort"
          - "mypy"
          - "packaging"
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install tox
      - run: tox -e ${{ matrix.toxenv }}
  lint-crlf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Check line endings
        run: scripts-dev/check_line_terminators.sh
  lint-newsfile:
    if: ${{ github.base_ref == 'develop'  || contains(github.base_ref, 'release-') }}
    runs-on: ubuntu-latest
    steps:
      # Note: This and the script can be simplified once we drop Buildkite. See:
      #   https://github.com/actions/checkout/issues/266#issuecomment-638346893
      #   https://github.com/actions/checkout/issues/416
      - uses: actions/checkout@v2
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
      - uses: actions/setup-python@v2
      - run: pip install tox
      - name: Patch Buildkite-specific test script
        run: |
          sed -i -e 's/\$BUILDKITE_PULL_REQUEST/${{ github.event.number }}/' \
            scripts-dev/check-newsfragment
      - run: scripts-dev/check-newsfragment
  lint-sdist:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: "3.x"
      - run: pip install wheel
      - run: python setup.py sdist bdist_wheel
      - uses: actions/upload-artifact@v2
        with:
          name: Python Distributions
          path: dist/*
  # Dummy step to gate other tests on without repeating the whole list
  linting-done:
    if: ${{ always() }} # Run this even if prior jobs were skipped
    needs: [lint, lint-crlf, lint-newsfile, lint-sdist]
    runs-on: ubuntu-latest
    steps:
      - run: "true"
  trial:
    if: ${{ !failure() }} # Allow previous steps to be skipped, but not fail
    needs: linting-done
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.6", "3.7", "3.8", "3.9"]
        database: ["sqlite"]
        include:
          # Newest Python without optional deps
          - python-version: "3.9"
            toxenv: "py-noextras,combine"
          # Oldest Python with PostgreSQL
          - python-version: "3.6"
            database: "postgres"
            postgres-version: "9.6"
          # Newest Python with PostgreSQL
          - python-version: "3.9"
            database: "postgres"
            postgres-version: "13"
    steps:
      - uses: actions/checkout@v2
      - run: sudo apt-get -qq install xmlsec1
      - name: Set up PostgreSQL ${{ matrix.postgres-version }}
        if: ${{ matrix.postgres-version }}
        run: |
          docker run -d -p 5432:5432 \
            -e POSTGRES_PASSWORD=postgres \
            -e POSTGRES_INITDB_ARGS="--lc-collate C --lc-ctype C --encoding UTF8" \
            postgres:${{ matrix.postgres-version }}
      - uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install tox
      - name: Await PostgreSQL
        if: ${{ matrix.postgres-version }}
        timeout-minutes: 2
        run: until pg_isready -h localhost; do sleep 1; done
      - run: tox -e py,combine
        env:
          TRIAL_FLAGS: "--jobs=2"
          SYNAPSE_POSTGRES: ${{ matrix.database == 'postgres' || '' }}
          SYNAPSE_POSTGRES_HOST: localhost
          SYNAPSE_POSTGRES_USER: postgres
          SYNAPSE_POSTGRES_PASSWORD: postgres
      - name: Dump logs
        # Note: Dumps to workflow logs instead of using actions/upload-artifact
        #       This keeps logs colocated with failing jobs
        #       It also ignores find's exit code; this is a best effort affair
        run: >-
          find _trial_temp -name '*.log'
          -exec echo "::group::{}" \;
          -exec cat {} \;
          -exec echo "::endgroup::" \;
          || true
  trial-olddeps:
    if: ${{ !failure() }} # Allow previous steps to be skipped, but not fail
    needs: linting-done
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Test with old deps
        uses: docker://ubuntu:bionic # For old python and sqlite
        with:
          workdir: /github/workspace
          entrypoint: .buildkite/scripts/test_old_deps.sh
        env:
          TRIAL_FLAGS: "--jobs=2"
      - name: Dump logs
        # Note: Dumps to workflow logs instead of using actions/upload-artifact
        #       This keeps logs colocated with failing jobs
        #       It also ignores find's exit code; this is a best effort affair
        run: >-
          find _trial_temp -name '*.log'
          -exec echo "::group::{}" \;
          -exec cat {} \;
          -exec echo "::endgroup::" \;
          || true
  trial-pypy:
    # Very slow; only run if the branch name includes 'pypy'
    if: ${{ contains(github.ref, 'pypy') && !failure() }}
    needs: linting-done
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["pypy-3.6"]
    steps:
      - uses: actions/checkout@v2
      - run: sudo apt-get -qq install xmlsec1 libxml2-dev libxslt-dev
      - uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install tox
      - run: tox -e py,combine
        env:
          TRIAL_FLAGS: "--jobs=2"
      - name: Dump logs
        # Note: Dumps to workflow logs instead of using actions/upload-artifact
        #       This keeps logs colocated with failing jobs
        #       It also ignores find's exit code; this is a best effort affair
        run: >-
          find _trial_temp -name '*.log'
          -exec echo "::group::{}" \;
          -exec cat {} \;
          -exec echo "::endgroup::" \;
          || true
  sytest:
    if: ${{ !failure() }}
    needs: linting-done
    runs-on: ubuntu-latest
    container:
      image: matrixdotorg/sytest-synapse:${{ matrix.sytest-tag }}
      volumes:
        - ${{ github.workspace }}:/src
      env:
        BUILDKITE_BRANCH: ${{ github.head_ref }}
        POSTGRES: ${{ matrix.postgres && 1}}
        MULTI_POSTGRES: ${{ (matrix.postgres == 'multi-postgres') && 1}}
        WORKERS: ${{ matrix.workers && 1 }}
        REDIS: ${{ matrix.redis && 1 }}
        BLACKLIST: ${{ matrix.workers && 'synapse-blacklist-with-workers' }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - sytest-tag: bionic
          - sytest-tag: bionic
            postgres: postgres
          - sytest-tag: testing
            postgres: postgres
          - sytest-tag: bionic
            postgres: multi-postgres
            workers: workers
          - sytest-tag: buster
            postgres: multi-postgres
            workers: workers
          - sytest-tag: buster
            postgres: postgres
            workers: workers
            redis: redis
    steps:
      - uses: actions/checkout@v2
      - name: Prepare test blacklist
        run: cat sytest-blacklist .buildkite/worker-blacklist > synapse-blacklist-with-workers
      - name: Run SyTest
        run: /bootstrap.sh synapse
        working-directory: /src
      - name: Summarise results.tap
        if: ${{ always() }}
        run: /sytest/scripts/tap_to_gha.pl /logs/results.tap
      - name: Upload SyTest logs
        uses: actions/upload-artifact@v2
        if: ${{ always() }}
        with:
          name: Sytest Logs - ${{ job.status }} - (${{ join(matrix.*, ', ') }})
          path: |
            /logs/results.tap
            /logs/**/*.log*
  portdb:
    if: ${{ !failure() }} # Allow previous steps to be skipped, but not fail
    needs: linting-done
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - python-version: "3.6"
            postgres-version: "9.6"
          - python-version: "3.9"
            postgres-version: "13"
    services:
      postgres:
        image: postgres:${{ matrix.postgres-version }}
        ports:
          - 5432:5432
        env:
          POSTGRES_PASSWORD: "postgres"
          POSTGRES_INITDB_ARGS: "--lc-collate C --lc-ctype C --encoding UTF8"
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v2
      - run: sudo apt-get -qq install xmlsec1
      - uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}
      - name: Patch Buildkite-specific test scripts
        run: |
          sed -i -e 's/host="postgres"/host="localhost"/' .buildkite/scripts/postgres_exec.py
          sed -i -e 's/host: postgres/host: localhost/' .buildkite/postgres-config.yaml
          sed -i -e 's|/src/||' .buildkite/{sqlite,postgres}-config.yaml
          sed -i -e 's/\$TOP/\$GITHUB_WORKSPACE/' .coveragerc
      - run: .buildkite/scripts/test_synapse_port_db.sh
  complement:
    if: ${{ !failure() }}
    needs: linting-done
    runs-on: ubuntu-latest
    container:
      # https://github.com/matrix-org/complement/blob/master/dockerfiles/ComplementCIBuildkite.Dockerfile
      image: matrixdotorg/complement:latest
      env:
        CI: true
      ports:
        - 8448:8448
      volumes:
        - /var/run/docker.sock:/var/run/docker.sock
    steps:
      - name: Run actions/checkout@v2 for synapse
        uses: actions/checkout@v2
        with:
          path: synapse
      # Attempt to check out the same branch of Complement as the PR. If it
      # doesn't exist, fallback to master.
      - name: Checkout complement
        shell: bash
        run: |
          mkdir -p complement
          # Attempt to use the version of complement which best matches the current
          # build. Depending on whether this is a PR or release, etc. we need to
          # use different fallbacks.
          #
          # 1. First check if there's a similarly named branch (GITHUB_HEAD_REF
          #    for pull requests, otherwise GITHUB_REF).
          # 2. Attempt to use the base branch, e.g. when merging into release-vX.Y
          #    (GITHUB_BASE_REF for pull requests).
          # 3. Use the default complement branch ("master").
          for BRANCH_NAME in "$GITHUB_HEAD_REF" "$GITHUB_BASE_REF" "${GITHUB_REF#refs/heads/}" "master"; do
            # Skip empty branch names and merge commits.
            if [[ -z "$BRANCH_NAME" || $BRANCH_NAME =~ ^refs/pull/.* ]]; then
              continue
            fi
            (wget -O - "https://github.com/matrix-org/complement/archive/$BRANCH_NAME.tar.gz" | tar -xz --strip-components=1 -C complement) && break
          done
      # Build initial Synapse image
      - run: docker build -t matrixdotorg/synapse:latest -f docker/Dockerfile .
        working-directory: synapse
      # Build a ready-to-run Synapse image based on the initial image above.
      # This new image includes a config file, keys for signing and TLS, and
      # other settings to make it suitable for testing under Complement.
      - run: docker build -t complement-synapse -f Synapse.Dockerfile .
        working-directory: complement/dockerfiles
      # Run Complement
      - run: go test -v -tags synapse_blacklist,msc2403,msc2946,msc3083 ./tests
        env:
          COMPLEMENT_BASE_IMAGE: complement-synapse:latest
        working-directory: complement
@@ -6,25 +6,19 @@
 *.egg
 *.egg-info
 *.lock
-*.py[cod]
+*.pyc
 *.snap
 *.tac
 _trial_temp/
 _trial_temp*/
 /out
 .DS_Store
 __pycache__/
 # stuff that is likely to exist when you run a server locally
 /*.db
 /*.log
 /*.log.*
 /*.log.config
 /*.pid
 /.python-version
 /*.signing.key
 /env/
 /.venv*/
 /homeserver*.yaml
 /logs
 /media_store/
@@ -46,6 +40,3 @@ __pycache__/
 /docs/build/
 /htmlcov
 /pip-wheel-metadata/
 # docs
 book/
@@ -1,8 +1,34 @@
-The following is an incomplete list of people outside the core team who have
+Erik Johnston <erik at matrix.org>
-contributed to Synapse. It is no longer maintained: more recent contributions
+ * HS core
-are listed in the `changelog <CHANGES.md>`_.
+ * Federation API impl
----
+Mark Haines <mark at matrix.org>
 * HS core
 * Crypto
 * Content repository
 * CS v2 API impl
 Kegan Dougal <kegan at matrix.org>
 * HS core
 * CS v1 API impl
 * AS API impl
 Paul "LeoNerd" Evans <paul at matrix.org>
 * HS core
 * Presence
 * Typing Notifications
 * Performance metrics and caching layer
 Dave Baker <dave at matrix.org>
 * Push notifications
 * Auth CS v2 impl
 Matthew Hodgson <matthew at matrix.org>
 * General doc & housekeeping
 * Vertobot/vertobridge matrix<->verto PoC
 Emmanuel Rohee <manu at matrix.org>
 * Supporting iOS clients (testability and fallback registration)
 Turned to Dust <dwinslow86 at gmail.com>
 * ArchLinux installation instructions
@@ -36,16 +62,16 @@ Christoph Witzany <christoph at web.crofting.com>
 * Add LDAP support for authentication
 Pierre Jaury <pierre at jaury.eu>
- * Docker packaging
+* Docker packaging
 Serban Constantin <serban.constantin at gmail dot com>
 * Small bug fix
 Jason Robinson <jasonr at matrix.org>
 * Minor fixes
 Joseph Weston <joseph at weston.cloud>
- * Add admin API for querying HS version
+ + Add admin API for querying HS version
 Benjamin Saunders <ben.e.saunders at gmail dot com>
 * Documentation improvements
 Werner Sembach <werner.sembach at fau dot de>
 * Automatically remove a group/community when it is empty
@@ -1,404 +0,0 @@
 Welcome to Synapse
 This document aims to get you started with contributing to this repo! 
 - [1. Who can contribute to Synapse?](#1-who-can-contribute-to-synapse)
 - [2. What do I need?](#2-what-do-i-need)
 - [3. Get the source.](#3-get-the-source)
 - [4. Install the dependencies](#4-install-the-dependencies)
  * [Under Unix (macOS, Linux, BSD, ...)](#under-unix-macos-linux-bsd-)
  * [Under Windows](#under-windows)
 - [5. Get in touch.](#5-get-in-touch)
 - [6. Pick an issue.](#6-pick-an-issue)
 - [7. Turn coffee and documentation into code and documentation!](#7-turn-coffee-and-documentation-into-code-and-documentation)
 - [8. Test, test, test!](#8-test-test-test)
  * [Run the linters.](#run-the-linters)
  * [Run the unit tests.](#run-the-unit-tests)
  * [Run the integration tests.](#run-the-integration-tests)
 - [9. Submit your patch.](#9-submit-your-patch)
  * [Changelog](#changelog)
    + [How do I know what to call the changelog file before I create the PR?](#how-do-i-know-what-to-call-the-changelog-file-before-i-create-the-pr)
    + [Debian changelog](#debian-changelog)
  * [Sign off](#sign-off)
 - [10. Turn feedback into better code.](#10-turn-feedback-into-better-code)
 - [11. Find a new issue.](#11-find-a-new-issue)
 - [Notes for maintainers on merging PRs etc](#notes-for-maintainers-on-merging-prs-etc)
 - [Conclusion](#conclusion)
 # 1. Who can contribute to Synapse?
 Everyone is welcome to contribute code to [matrix.org
 projects](https://github.com/matrix-org), provided that they are willing to
 license their contributions under the same license as the project itself. We
 follow a simple 'inbound=outbound' model for contributions: the act of
 submitting an 'inbound' contribution means that the contributor agrees to
 license the code under the same terms as the project's overall 'outbound'
 license - in our case, this is almost always Apache Software License v2 (see
 [LICENSE](LICENSE)).
 # 2. What do I need?
 The code of Synapse is written in Python 3. To do pretty much anything, you'll need [a recent version of Python 3](https://wiki.python.org/moin/BeginnersGuide/Download).
 The source code of Synapse is hosted on GitHub. You will also need [a recent version of git](https://github.com/git-guides/install-git).
 For some tests, you will need [a recent version of Docker](https://docs.docker.com/get-docker/).
 # 3. Get the source.
 The preferred and easiest way to contribute changes is to fork the relevant
 project on GitHub, and then [create a pull request](
 https://help.github.com/articles/using-pull-requests/) to ask us to pull your
 changes into our repo.
 Please base your changes on the `develop` branch.
 ```sh
 git clone git@github.com:YOUR_GITHUB_USER_NAME/synapse.git
 git checkout develop
 ```
 If you need help getting started with git, this is beyond the scope of the document, but you
 can find many good git tutorials on the web.
 # 4. Install the dependencies
 ## Under Unix (macOS, Linux, BSD, ...)
 Once you have installed Python 3 and added the source, please open a terminal and
 setup a *virtualenv*, as follows:
 ```sh
 cd path/where/you/have/cloned/the/repository
 python3 -m venv ./env
 source ./env/bin/activate
 pip install -e ".[all,lint,mypy,test]"
 pip install tox
 ```
 This will install the developer dependencies for the project.
 ## Under Windows
 TBD
 # 5. Get in touch.
 Join our developer community on Matrix: #synapse-dev:matrix.org !
 # 6. Pick an issue.
 Fix your favorite problem or perhaps find a [Good First Issue](https://github.com/matrix-org/synapse/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22)
 to work on.
 # 7. Turn coffee and documentation into code and documentation!
 Synapse's code style is documented [here](docs/code_style.md). Please follow
 it, including the conventions for the [sample configuration
 file](docs/code_style.md#configuration-file-format).
 There is a growing amount of documentation located in the [docs](docs)
 directory. This documentation is intended primarily for sysadmins running their
 own Synapse instance, as well as developers interacting externally with
 Synapse. [docs/dev](docs/dev) exists primarily to house documentation for
 Synapse developers. [docs/admin_api](docs/admin_api) houses documentation
 regarding Synapse's Admin API, which is used mostly by sysadmins and external
 service developers.
 If you add new files added to either of these folders, please use [GitHub-Flavoured
 Markdown](https://guides.github.com/features/mastering-markdown/).
 Some documentation also exists in [Synapse's GitHub
 Wiki](https://github.com/matrix-org/synapse/wiki), although this is primarily
 contributed to by community authors.
 # 8. Test, test, test!
 <a name="test-test-test"></a>
 While you're developing and before submitting a patch, you'll
 want to test your code.
 ## Run the linters.
 The linters look at your code and do two things:
 - ensure that your code follows the coding style adopted by the project;
 - catch a number of errors in your code.
 They're pretty fast, don't hesitate!
 ```sh
 source ./env/bin/activate
 ./scripts-dev/lint.sh
 ```
 Note that this script *will modify your files* to fix styling errors.
 Make sure that you have saved all your files.
 If you wish to restrict the linters to only the files changed since the last commit
 (much faster!), you can instead run:
 ```sh
 source ./env/bin/activate
 ./scripts-dev/lint.sh -d
 ```
 Or if you know exactly which files you wish to lint, you can instead run:
 ```sh
 source ./env/bin/activate
 ./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
 ```
 ## Run the unit tests.
 The unit tests run parts of Synapse, including your changes, to see if anything
 was broken. They are slower than the linters but will typically catch more errors.
 ```sh
 source ./env/bin/activate
 trial tests
 ```
 If you wish to only run *some* unit tests, you may specify
 another module instead of `tests` - or a test class or a method:
 ```sh
 source ./env/bin/activate
 trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
 ```
 If your tests fail, you may wish to look at the logs (the default log level is `ERROR`):
 ```sh
 less _trial_temp/test.log
 ```
 To increase the log level for the tests, set `SYNAPSE_TEST_LOG_LEVEL`:
 ```sh
 SYNAPSE_TEST_LOG_LEVEL=DEBUG trial tests
 ```
 ## Run the integration tests.
 The integration tests are a more comprehensive suite of tests. They
 run a full version of Synapse, including your changes, to check if
 anything was broken. They are slower than the unit tests but will
 typically catch more errors.
 The following command will let you run the integration test with the most common
 configuration:
 ```sh
 $ docker run --rm -it -v /path/where/you/have/cloned/the/repository\:/src:ro -v /path/to/where/you/want/logs\:/logs matrixdotorg/sytest-synapse:py37
 ```
 This configuration should generally cover  your needs. For more details about other configurations, see [documentation in the SyTest repo](https://github.com/matrix-org/sytest/blob/develop/docker/README.md).
 # 9. Submit your patch.
 Once you're happy with your patch, it's time to prepare a Pull Request.
 To prepare a Pull Request, please:
 1. verify that [all the tests pass](#test-test-test), including the coding style;
 2. [sign off](#sign-off) your contribution;
 3. `git push` your commit to your fork of Synapse;
 4. on GitHub, [create the Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request);
 5. add a [changelog entry](#changelog) and push it to your Pull Request;
 6. for most contributors, that's all - however, if you are a member of the organization `matrix-org`, on GitHub, please request a review from `matrix.org / Synapse Core`.
 ## Changelog
 All changes, even minor ones, need a corresponding changelog / newsfragment
 entry. These are managed by [Towncrier](https://github.com/hawkowl/towncrier).
 To create a changelog entry, make a new file in the `changelog.d` directory named
 in the format of `PRnumber.type`. The type can be one of the following:
 * `feature`
 * `bugfix`
 * `docker` (for updates to the Docker image)
 * `doc` (for updates to the documentation)
 * `removal` (also used for deprecations)
 * `misc` (for internal-only changes)
 This file will become part of our [changelog](
 https://github.com/matrix-org/synapse/blob/master/CHANGES.md) at the next
 release, so the content of the file should be a short description of your
 change in the same style as the rest of the changelog. The file can contain Markdown
 formatting, and should end with a full stop (.) or an exclamation mark (!) for
 consistency.
 Adding credits to the changelog is encouraged, we value your
 contributions and would like to have you shouted out in the release notes!
 For example, a fix in PR #1234 would have its changelog entry in
 `changelog.d/1234.bugfix`, and contain content like:
 > The security levels of Florbs are now validated when received
 > via the `/federation/florb` endpoint. Contributed by Jane Matrix.
 If there are multiple pull requests involved in a single bugfix/feature/etc,
 then the content for each `changelog.d` file should be the same. Towncrier will
 merge the matching files together into a single changelog entry when we come to
 release.
 ### How do I know what to call the changelog file before I create the PR?
 Obviously, you don't know if you should call your newsfile
 `1234.bugfix` or `5678.bugfix` until you create the PR, which leads to a
 chicken-and-egg problem.
 There are two options for solving this:
 1. Open the PR without a changelog file, see what number you got, and *then*
    add the changelog file to your branch (see [Updating your pull
    request](#updating-your-pull-request)), or:
 1. Look at the [list of all
    issues/PRs](https://github.com/matrix-org/synapse/issues?q=), add one to the
    highest number you see, and quickly open the PR before somebody else claims
    your number.
    [This
    script](https://github.com/richvdh/scripts/blob/master/next_github_number.sh)
    might be helpful if you find yourself doing this a lot.
 Sorry, we know it's a bit fiddly, but it's *really* helpful for us when we come
 to put together a release!
 ### Debian changelog
 Changes which affect the debian packaging files (in `debian`) are an
 exception to the rule that all changes require a `changelog.d` file.
 In this case, you will need to add an entry to the debian changelog for the
 next release. For this, run the following command:
 ```
 dch
 ```
 This will make up a new version number (if there isn't already an unreleased
 version in flight), and open an editor where you can add a new changelog entry.
 (Our release process will ensure that the version number and maintainer name is
 corrected for the release.)
 If your change affects both the debian packaging *and* files outside the debian
 directory, you will need both a regular newsfragment *and* an entry in the
 debian changelog. (Though typically such changes should be submitted as two
 separate pull requests.)
 ## Sign off
 In order to have a concrete record that your contribution is intentional
 and you agree to license it under the same terms as the project's license, we've adopted the
 same lightweight approach that the Linux Kernel
 [submitting patches process](
 https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>),
 [Docker](https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
 projects use: the DCO (Developer Certificate of Origin:
 http://developercertificate.org/). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix:
 ```
 Developer Certificate of Origin
 Version 1.1
 Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
 660 York Street, Suite 102,
 San Francisco, CA 94110 USA
 Everyone is permitted to copy and distribute verbatim copies of this
 license document, but changing it is not allowed.
 Developer's Certificate of Origin 1.1
 By making a contribution to this project, I certify that:
 (a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or
 (b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or
 (c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.
 (d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
 ```
 If you agree to this for your contribution, then all that's needed is to
 include the line in your commit or pull request comment:
 ```
 Signed-off-by: Your Name <your@email.example.org>
 ```
 We accept contributions under a legally identifiable name, such as
 your name on government documentation or common-law names (names
 claimed by legitimate usage or repute). Unfortunately, we cannot
 accept anonymous contributions at this time.
 Git allows you to add this signoff automatically when using the `-s`
 flag to `git commit`, which uses the name and email set in your
 `user.name` and `user.email` git configs.
 # 10. Turn feedback into better code.
 Once the Pull Request is opened, you will see a few things:
 1. our automated CI (Continuous Integration) pipeline will run (again) the linters, the unit tests, the integration tests and more;
 2. one or more of the developers will take a look at your Pull Request and offer feedback.
 From this point, you should:
 1. Look at the results of the CI pipeline.
   - If there is any error, fix the error.
 2. If a developer has requested changes, make these changes and let us know if it is ready for a developer to review again.
 3. Create a new commit with the changes.
   - Please do NOT overwrite the history. New commits make the reviewer's life easier.
   - Push this commits to your Pull Request.
 4. Back to 1.
 Once both the CI and the developers are happy, the patch will be merged into Synapse and released shortly!
 # 11. Find a new issue.
 By now, you know the drill!
 # Notes for maintainers on merging PRs etc
 There are some notes for those with commit access to the project on how we
 manage git [here](docs/dev/git.md).
 # Conclusion
 That's it! Matrix is a very open and collaborative project as you might expect
 given our obsession with open communication. If we're going to successfully
 matrix together all the fragmented communication technologies out there we are
 reliant on contributions and collaboration from the community to do so. So
 please get involved - and we hope you have as much fun hacking on Matrix as we
 do!
@@ -0,0 +1,198 @@
 Contributing code to Matrix
 ===========================
 Everyone is welcome to contribute code to Matrix
 (https://github.com/matrix-org), provided that they are willing to license
 their contributions under the same license as the project itself. We follow a
 simple 'inbound=outbound' model for contributions: the act of submitting an
 'inbound' contribution means that the contributor agrees to license the code
 under the same terms as the project's overall 'outbound' license - in our
 case, this is almost always Apache Software License v2 (see LICENSE).
 How to contribute
 ~~~~~~~~~~~~~~~~~
 The preferred and easiest way to contribute changes to Matrix is to fork the
 relevant project on github, and then create a pull request to ask us to pull
 your changes into our repo
 (https://help.github.com/articles/using-pull-requests/)
 **The single biggest thing you need to know is: please base your changes on
 the develop branch - /not/ master.**
 We use the master branch to track the most recent release, so that folks who
 blindly clone the repo and automatically check out master get something that
 works. Develop is the unstable branch where all the development actually
 happens: the workflow is that contributors should fork the develop branch to
 make a 'feature' branch for a particular contribution, and then make a pull
 request to merge this back into the matrix.org 'official' develop branch. We
 use github's pull request workflow to review the contribution, and either ask
 you to make any refinements needed or merge it and make them ourselves. The
 changes will then land on master when we next do a release.
 We use `Buildkite <https://buildkite.com/matrix-dot-org/synapse>`_ for
 continuous integration.  Buildkite builds need to be authorised by a
 maintainer. If your change breaks the build, this will be shown in GitHub, so
 please keep an eye on the pull request for feedback.
 To run unit tests in a local development environment, you can use:
 - ``tox -e py35`` (requires tox to be installed by ``pip install tox``)
  for SQLite-backed Synapse on Python 3.5.
 - ``tox -e py36`` for SQLite-backed Synapse on Python 3.6.
 - ``tox -e py36-postgres`` for PostgreSQL-backed Synapse on Python 3.6
  (requires a running local PostgreSQL with access to create databases).
 - ``./test_postgresql.sh`` for PostgreSQL-backed Synapse on Python 3.5
  (requires Docker). Entirely self-contained, recommended if you don't want to
  set up PostgreSQL yourself.
 Docker images are available for running the integration tests (SyTest) locally,
 see the `documentation in the SyTest repo
 <https://github.com/matrix-org/sytest/blob/develop/docker/README.md>`_ for more
 information.
 Code style
 ~~~~~~~~~~
 All Matrix projects have a well-defined code-style - and sometimes we've even
 got as far as documenting it... For instance, synapse's code style doc lives
 at https://github.com/matrix-org/synapse/tree/master/docs/code_style.rst.
 Please ensure your changes match the cosmetic style of the existing project,
 and **never** mix cosmetic and functional changes in the same commit, as it
 makes it horribly hard to review otherwise.
 Changelog
 ~~~~~~~~~
 All changes, even minor ones, need a corresponding changelog / newsfragment
 entry. These are managed by Towncrier
 (https://github.com/hawkowl/towncrier).
 To create a changelog entry, make a new file in the ``changelog.d`` file named
 in the format of ``PRnumber.type``. The type can be one of the following:
 * ``feature``.
 * ``bugfix``.
 * ``docker`` (for updates to the Docker image).
 * ``doc`` (for updates to the documentation).
 * ``removal`` (also used for deprecations).
 * ``misc`` (for internal-only changes).
 The content of the file is your changelog entry, which should be a short
 description of your change in the same style as the rest of our `changelog
 <https://github.com/matrix-org/synapse/blob/master/CHANGES.md>`_. The file can
 contain Markdown formatting, and should end with a full stop ('.') for
 consistency.
 Adding credits to the changelog is encouraged, we value your
 contributions and would like to have you shouted out in the release notes!
 For example, a fix in PR #1234 would have its changelog entry in
 ``changelog.d/1234.bugfix``, and contain content like "The security levels of
 Florbs are now validated when recieved over federation. Contributed by Jane
 Matrix.".
 Debian changelog
 ----------------
 Changes which affect the debian packaging files (in ``debian``) are an
 exception.
 In this case, you will need to add an entry to the debian changelog for the
 next release. For this, run the following command::
  dch
 This will make up a new version number (if there isn't already an unreleased
 version in flight), and open an editor where you can add a new changelog entry.
 (Our release process will ensure that the version number and maintainer name is
 corrected for the release.)
 If your change affects both the debian packaging *and* files outside the debian
 directory, you will need both a regular newsfragment *and* an entry in the
 debian changelog. (Though typically such changes should be submitted as two
 separate pull requests.)
 Attribution
 ~~~~~~~~~~~
 Everyone who contributes anything to Matrix is welcome to be listed in the
 AUTHORS.rst file for the project in question. Please feel free to include a
 change to AUTHORS.rst in your pull request to list yourself and a short
 description of the area(s) you've worked on. Also, we sometimes have swag to
 give away to contributors - if you feel that Matrix-branded apparel is missing
 from your life, please mail us your shipping address to matrix at matrix.org and
 we'll try to fix it :)
 Sign off
 ~~~~~~~~
 In order to have a concrete record that your contribution is intentional
 and you agree to license it under the same terms as the project's license, we've adopted the
 same lightweight approach that the Linux Kernel
 `submitting patches process <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`_, Docker
 (https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
 projects use: the DCO (Developer Certificate of Origin:
 http://developercertificate.org/). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix::
    Developer Certificate of Origin
    Version 1.1
    Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
    660 York Street, Suite 102,
    San Francisco, CA 94110 USA
    Everyone is permitted to copy and distribute verbatim copies of this
    license document, but changing it is not allowed.
    Developer's Certificate of Origin 1.1
    By making a contribution to this project, I certify that:
    (a) The contribution was created in whole or in part by me and I
        have the right to submit it under the open source license
        indicated in the file; or
    (b) The contribution is based upon previous work that, to the best
        of my knowledge, is covered under an appropriate open source
        license and I have the right under that license to submit that
        work with modifications, whether created in whole or in part
        by me, under the same open source license (unless I am
        permitted to submit under a different license), as indicated
        in the file; or
    (c) The contribution was provided directly to me by some other
        person who certified (a), (b) or (c) and I have not modified
        it.
    (d) I understand and agree that this project and the contribution
        are public and that a record of the contribution (including all
        personal information I submit with it, including my sign-off) is
        maintained indefinitely and may be redistributed consistent with
        this project or the open source license(s) involved.
 If you agree to this for your contribution, then all that's needed is to
 include the line in your commit or pull request comment::
    Signed-off-by: Your Name <your@email.example.org>
 We accept contributions under a legally identifiable name, such as
 your name on government documentation or common-law names (names
 claimed by legitimate usage or repute). Unfortunately, we cannot
 accept anonymous contributions at this time.
 Git allows you to add this signoff automatically when using the ``-s``
 flag to ``git commit``, which uses the name and email set in your
 ``user.name`` and ``user.email`` git configs.
 Conclusion
 ~~~~~~~~~~
 That's it!  Matrix is a very open and collaborative project as you might expect
 given our obsession with open communication.  If we're going to successfully
 matrix together all the fragmented communication technologies out there we are
 reliant on contributions and collaboration from the community to do so.  So
 please get involved - and we hope you have as much fun hacking on Matrix as we
 do!
@@ -1,45 +1,17 @@
-# Installation Instructions
+- [Choosing your server name](#choosing-your-server-name)
-
+- [Installing Synapse](#installing-synapse)
-There are 3 steps to follow under **Installation Instructions**.
+  - [Installing from source](#installing-from-source)
-
+    - [Platform-Specific Instructions](#platform-specific-instructions)
 - [Installation Instructions](#installation-instructions)
  - [Choosing your server name](#choosing-your-server-name)
  - [Installing Synapse](#installing-synapse)
    - [Installing from source](#installing-from-source)
      - [Platform-specific prerequisites](#platform-specific-prerequisites)
        - [Debian/Ubuntu/Raspbian](#debianubunturaspbian)
        - [ArchLinux](#archlinux)
        - [CentOS/Fedora](#centosfedora)
        - [macOS](#macos)
        - [OpenSUSE](#opensuse)
        - [OpenBSD](#openbsd)
        - [Windows](#windows)
    - [Prebuilt packages](#prebuilt-packages)
      - [Docker images and Ansible playbooks](#docker-images-and-ansible-playbooks)
      - [Debian/Ubuntu](#debianubuntu)
        - [Matrix.org packages](#matrixorg-packages)
        - [Downstream Debian packages](#downstream-debian-packages)
        - [Downstream Ubuntu packages](#downstream-ubuntu-packages)
      - [Fedora](#fedora)
      - [OpenSUSE](#opensuse-1)
      - [SUSE Linux Enterprise Server](#suse-linux-enterprise-server)
      - [ArchLinux](#archlinux-1)
      - [Void Linux](#void-linux)
      - [FreeBSD](#freebsd)
      - [OpenBSD](#openbsd-1)
      - [NixOS](#nixos)
  - [Setting up Synapse](#setting-up-synapse)
    - [Using PostgreSQL](#using-postgresql)
    - [TLS certificates](#tls-certificates)
    - [Client Well-Known URI](#client-well-known-uri)
    - [Email](#email)
    - [Registering a user](#registering-a-user)
    - [Setting up a TURN server](#setting-up-a-turn-server)
    - [URL previews](#url-previews)
    - [Troubleshooting Installation](#troubleshooting-installation)
  - [Prebuilt packages](#prebuilt-packages)
 - [Setting up Synapse](#setting-up-synapse)
  - [TLS certificates](#tls-certificates)
  - [Email](#email)
  - [Registering a user](#registering-a-user)
  - [Setting up a TURN server](#setting-up-a-turn-server)
  - [URL previews](#url-previews)
-
+# Choosing your server name
 ## Choosing your server name
 It is important to choose the name for your server before you install Synapse,
 because it cannot be changed later.
@@ -55,24 +27,27 @@ that your email address is probably `user@example.com` rather than
 `user@email.example.com`) - but doing so may require more advanced setup: see
 [Setting up Federation](docs/federate.md).
-## Installing Synapse
+# Installing Synapse
-### Installing from source
+## Installing from source
 (Prebuilt packages are available for some platforms - see [Prebuilt packages](#prebuilt-packages).)
 When installing from source please make sure that the [Platform-specific prerequisites](#platform-specific-prerequisites) are already installed.
 System requirements:
 - POSIX-compliant system (tested on Linux & OS X)
- Python 3.5.2 or later, up to Python 3.9.
+- Python 3.5, 3.6, or 3.7
 - At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org
 Synapse is written in Python but some of the libraries it uses are written in
 C. So before we can install Synapse itself we need a working C compiler and the
 header files for Python C extensions. See [Platform-Specific
 Instructions](#platform-specific-instructions) for information on installing
 these on various platforms.
 To install the Synapse homeserver run:
-```sh
+```
 mkdir -p ~/synapse
 virtualenv -p python3 ~/synapse/env
 source ~/synapse/env/bin/activate
@@ -89,15 +64,15 @@ prefer.
 This Synapse installation can then be later upgraded by using pip again with the
 update flag:
-```sh
+```
 source ~/synapse/env/bin/activate
 pip install -U matrix-synapse
 ```
 Before you can start Synapse, you will need to generate a configuration
-file. To do this, run (in your virtualenv, as before):
+file. To do this, run (in your virtualenv, as before)::
-```sh
+```
 cd ~/synapse
 python -m synapse.app.homeserver \
    --server-name my.domain.name \
@@ -109,169 +84,189 @@ python -m synapse.app.homeserver \
 ... substituting an appropriate value for `--server-name`.
 This command will generate you a config file that you can then customise, but it will
-also generate a set of keys for you. These keys will allow your homeserver to
+also generate a set of keys for you. These keys will allow your Home Server to
-identify itself to other homeserver, so don't lose or delete them. It would be
+identify itself to other Home Servers, so don't lose or delete them. It would be
 wise to back them up somewhere safe. (If, for whatever reason, you do need to
-change your homeserver's keys, you may find that other homeserver have the
+change your Home Server's keys, you may find that other Home Servers have the
 old key cached. If you update the signing key, you should change the name of the
 key in the `<server name>.signing.key` file (the second word) to something
-different. See the [spec](https://matrix.org/docs/spec/server_server/latest.html#retrieving-server-keys) for more information on key management).
+different. See the
 [spec](https://matrix.org/docs/spec/server_server/latest.html#retrieving-server-keys)
 for more information on key management.)
 To actually run your new homeserver, pick a working directory for Synapse to
-run (e.g. `~/synapse`), and:
+run (e.g. `~/synapse`), and::
-```sh
+    cd ~/synapse
-cd ~/synapse
+    source env/bin/activate
-source env/bin/activate
+    synctl start
 synctl start
 ```
-#### Platform-specific prerequisites
+### Platform-Specific Instructions
-Synapse is written in Python but some of the libraries it uses are written in
+#### Debian/Ubuntu/Raspbian
 C. So before we can install Synapse itself we need a working C compiler and the
 header files for Python C extensions.
 ##### Debian/Ubuntu/Raspbian
 Installing prerequisites on Ubuntu or Debian:
-```sh
+```
-sudo apt install build-essential python3-dev libffi-dev \
+sudo apt-get install build-essential python3-dev libffi-dev \
-                     python3-pip python3-setuptools sqlite3 \
+                     python-pip python-setuptools sqlite3 \
-                     libssl-dev virtualenv libjpeg-dev libxslt1-dev
+                     libssl-dev python-virtualenv libjpeg-dev libxslt1-dev
 ```
-##### ArchLinux
+#### ArchLinux
 Installing prerequisites on ArchLinux:
-```sh
+```
 sudo pacman -S base-devel python python-pip \
               python-setuptools python-virtualenv sqlite3
 ```
-##### CentOS/Fedora
+#### CentOS/Fedora
-Installing prerequisites on CentOS or Fedora Linux:
+Installing prerequisites on CentOS 7 or Fedora 25:
-```sh
+```
-sudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
+sudo yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
-                 libwebp-devel libxml2-devel libxslt-devel libpq-devel \
+                 lcms2-devel libwebp-devel tcl-devel tk-devel redhat-rpm-config \
-                 python3-virtualenv libffi-devel openssl-devel python3-devel
+                 python-virtualenv libffi-devel openssl-devel
-sudo dnf groupinstall "Development Tools"
+sudo yum groupinstall "Development Tools"
 ```
-##### macOS
+#### Mac OS X
-Installing prerequisites on macOS:
+Installing prerequisites on Mac OS X:
-```sh
+```
 xcode-select --install
 sudo easy_install pip
 sudo pip install virtualenv
 brew install pkg-config libffi
 ```
-On macOS Catalina (10.15) you may need to explicitly install OpenSSL
+#### OpenSUSE
 via brew and inform `pip` about it so that `psycopg2` builds:
 ```sh
 brew install openssl@1.1
 export LDFLAGS="-L/usr/local/opt/openssl/lib"
 export CPPFLAGS="-I/usr/local/opt/openssl/include"
 ```
 ##### OpenSUSE
 Installing prerequisites on openSUSE:
-```sh
+```
 sudo zypper in -t pattern devel_basis
 sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \
               python-devel libffi-devel libopenssl-devel libjpeg62-devel
 ```
-##### OpenBSD
+#### OpenBSD
-A port of Synapse is available under `net/synapse`. The filesystem
+Installing prerequisites on OpenBSD:
 underlying the homeserver directory (defaults to `/var/synapse`) has to be
 mounted with `wxallowed` (cf. `mount(8)`), so creating a separate filesystem
 and mounting it to `/var/synapse` should be taken into consideration.
-To be able to build Synapse's dependency on python the `WRKOBJDIR`
+```
-(cf. `bsd.port.mk(5)`) for building python, too, needs to be on a filesystem
+doas pkg_add python libffi py-pip py-setuptools sqlite3 py-virtualenv \
-mounted with `wxallowed` (cf. `mount(8)`).
+              libxslt jpeg
 Creating a `WRKOBJDIR` for building python under `/usr/local` (which on a
 default OpenBSD installation is mounted with `wxallowed`):
 ```sh
 doas mkdir /usr/local/pobj_wxallowed
 ```
-Assuming `PORTS_PRIVSEP=Yes` (cf. `bsd.port.mk(5)`) and `SUDO=doas` are
+There is currently no port for OpenBSD. Additionally, OpenBSD's security
-configured in `/etc/mk.conf`:
+settings require a slightly more difficult installation process.
-```sh
+XXX: I suspect this is out of date.
 doas chown _pbuild:_pbuild /usr/local/pobj_wxallowed
 ```
-Setting the `WRKOBJDIR` for building python:
+1. Create a new directory in `/usr/local` called `_synapse`. Also, create a
   new user called `_synapse` and set that directory as the new user's home.
   This is required because, by default, OpenBSD only allows binaries which need
   write and execute permissions on the same memory space to be run from
   `/usr/local`.
 2. `su` to the new `_synapse` user and change to their home directory.
 3. Create a new virtualenv: `virtualenv -p python2.7 ~/.synapse`
 4. Source the virtualenv configuration located at
   `/usr/local/_synapse/.synapse/bin/activate`. This is done in `ksh` by
   using the `.` command, rather than `bash`'s `source`.
 5. Optionally, use `pip` to install `lxml`, which Synapse needs to parse
   webpages for their titles.
 6. Use `pip` to install this repository: `pip install matrix-synapse`
 7. Optionally, change `_synapse`'s shell to `/bin/false` to reduce the
   chance of a compromised Synapse server being used to take over your box.
-```sh
+After this, you may proceed with the rest of the install directions.
 echo WRKOBJDIR_lang/python/3.7=/usr/local/pobj_wxallowed  \\nWRKOBJDIR_lang/python/2.7=/usr/local/pobj_wxallowed >> /etc/mk.conf
 ```
-Building Synapse:
+#### Windows
 ```sh
 cd /usr/ports/net/synapse
 make install
 ```
 ##### Windows
 If you wish to run or develop Synapse on Windows, the Windows Subsystem For
 Linux provides a Linux environment on Windows 10 which is capable of using the
 Debian, Fedora, or source installation methods. More information about WSL can
-be found at <https://docs.microsoft.com/en-us/windows/wsl/install-win10> for
+be found at https://docs.microsoft.com/en-us/windows/wsl/install-win10 for
-Windows 10 and <https://docs.microsoft.com/en-us/windows/wsl/install-on-server>
+Windows 10 and https://docs.microsoft.com/en-us/windows/wsl/install-on-server
 for Windows Server.
-### Prebuilt packages
+### Troubleshooting Installation
 XXX a bunch of this is no longer relevant.
 Synapse requires pip 8 or later, so if your OS provides too old a version you
 may need to manually upgrade it::
    sudo pip install --upgrade pip
 Installing may fail with `Could not find any downloads that satisfy the requirement pymacaroons-pynacl (from matrix-synapse==0.12.0)`.
 You can fix this by manually upgrading pip and virtualenv::
    sudo pip install --upgrade virtualenv
 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::
    pip install --upgrade ndg-httpsclient
 Installing may fail with `mock requires setuptools>=17.1. Aborting installation`.
 You can fix this by upgrading setuptools::
    pip install --upgrade setuptools
 If pip crashes mid-installation for reason (e.g. lost terminal), pip may
 refuse to run until you remove the temporary installation directory it
 created. To reset the installation::
    rm -rf /tmp/pip_install_matrix
 pip seems to leak *lots* of memory during installation.  For instance, a Linux
 host with 512MB of RAM may run out of memory whilst installing Twisted.  If this
 happens, you will have to individually install the dependencies which are
 failing, e.g.::
    pip install twisted
 ## Prebuilt packages
 As an alternative to installing from source, prebuilt packages are available
 for a number of platforms.
-#### Docker images and Ansible playbooks
+### Docker images and Ansible playbooks
-There is an official synapse image available at
+There is an offical synapse image available at
-<https://hub.docker.com/r/matrixdotorg/synapse> which can be used with
+https://hub.docker.com/r/matrixdotorg/synapse which can be used with
-the docker-compose file available at [contrib/docker](contrib/docker). Further
+the docker-compose file available at [contrib/docker](contrib/docker). Further information on
-information on this including configuration options is available in the README
+this including configuration options is available in the README on
-on hub.docker.com.
+hub.docker.com.
 Alternatively, Andreas Peters (previously Silvio Fricke) has contributed a
 Dockerfile to automate a synapse server in a single Docker image, at
-<https://hub.docker.com/r/avhost/docker-matrix/tags/>
+https://hub.docker.com/r/avhost/docker-matrix/tags/
 Slavi Pantaleev has created an Ansible playbook,
 which installs the offical Docker image of Matrix Synapse
-along with many other Matrix-related services (Postgres database, Element, coturn,
+along with many other Matrix-related services (Postgres database, riot-web, coturn, mxisd, SSL support, etc.).
 ma1sd, SSL support, etc.).
 For more details, see
-<https://github.com/spantaleev/matrix-docker-ansible-deploy>
+https://github.com/spantaleev/matrix-docker-ansible-deploy
 #### Debian/Ubuntu
-##### Matrix.org packages
+### Debian/Ubuntu
 #### Matrix.org packages
 Matrix.org provides Debian/Ubuntu packages of the latest stable version of
-Synapse via <https://packages.matrix.org/debian/>. They are available for Debian
+Synapse via https://packages.matrix.org/debian/. They are available for Debian
 9 (Stretch), Ubuntu 16.04 (Xenial), and later. To use them:
-```sh
+```
 sudo apt install -y lsb-release wget apt-transport-https
 sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
 echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" |
@@ -291,61 +286,56 @@ The fingerprint of the repository signing key (as shown by `gpg
 /usr/share/keyrings/matrix-org-archive-keyring.gpg`) is
 `AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058`.
-##### Downstream Debian packages
+#### Downstream Debian/Ubuntu packages
-We do not recommend using the packages from the default Debian `buster`
+For `buster` and `sid`, Synapse is available in the Debian repositories and
-repository at this time, as they are old and suffer from known security
+it should be possible to install it with simply:
 vulnerabilities. You can install the latest version of Synapse from
 [our repository](#matrixorg-packages) or from `buster-backports`. Please
 see the [Debian documentation](https://backports.debian.org/Instructions/)
 for information on how to use backports.
-If you are using Debian `sid` or testing, Synapse is available in the default
+```
-repositories and it should be possible to install it simply with:
+    sudo apt install matrix-synapse
 ```sh
 sudo apt install matrix-synapse
 ```
-##### Downstream Ubuntu packages
+There is also a version of `matrix-synapse` in `stretch-backports`. Please see
 the [Debian documentation on
 backports](https://backports.debian.org/Instructions/) for information on how
 to use them.
-We do not recommend using the packages in the default Ubuntu repository
+We do not recommend using the packages in downstream Ubuntu at this time, as
-at this time, as they are old and suffer from known security vulnerabilities.
+they are old and suffer from known security vulnerabilities.
 The latest version of Synapse can be installed from [our repository](#matrixorg-packages).
-#### Fedora
+### Fedora
 Synapse is in the Fedora repositories as `matrix-synapse`:
-```sh
+```
 sudo dnf install matrix-synapse
 ```
 Oleg Girko provides Fedora RPMs at
-<https://obs.infoserver.lv/project/monitor/matrix-synapse>
+https://obs.infoserver.lv/project/monitor/matrix-synapse
-#### OpenSUSE
+### OpenSUSE
 Synapse is in the OpenSUSE repositories as `matrix-synapse`:
-```sh
+```
 sudo zypper install matrix-synapse
 ```
-#### SUSE Linux Enterprise Server
+### SUSE Linux Enterprise Server
 Unofficial package are built for SLES 15 in the openSUSE:Backports:SLE-15 repository at
-<https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/>
+https://download.opensuse.org/repositories/openSUSE:/Backports:/SLE-15/standard/
-#### ArchLinux
+### 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
+https://www.archlinux.org/packages/community/any/matrix-synapse/, which should pull in most of
 the necessary dependencies.
 pip may be outdated (6.0.7-1 and needs to be upgraded to 6.0.8-1 ):
-```sh
+```
 sudo pip install --upgrade pip
 ```
@@ -354,197 +344,91 @@ 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):
-```sh
+```
 sudo pip uninstall py-bcrypt
 sudo pip install py-bcrypt
 ```
-#### Void Linux
+### FreeBSD
 Synapse can be found in the void repositories as 'synapse':
 ```sh
 xbps-install -Su
 xbps-install -S synapse
 ```
 #### FreeBSD
 Synapse can be installed via FreeBSD Ports or Packages contributed by Brendan Molloy from:
- Ports: `cd /usr/ports/net-im/py-matrix-synapse && make install clean`
+ - Ports: `cd /usr/ports/net-im/py-matrix-synapse && make install clean`
- Packages: `pkg install py37-matrix-synapse`
+ - Packages: `pkg install py27-matrix-synapse`
 #### OpenBSD
-As of OpenBSD 6.7 Synapse is available as a pre-compiled binary. The filesystem
+### NixOS
 underlying the homeserver directory (defaults to `/var/synapse`) has to be
 mounted with `wxallowed` (cf. `mount(8)`), so creating a separate filesystem
 and mounting it to `/var/synapse` should be taken into consideration.
 Installing Synapse:
 ```sh
 doas pkg_add synapse
 ```
 #### NixOS
 Robin Lambertz has packaged Synapse for NixOS at:
-<https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix>
+https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/matrix-synapse.nix
-## Setting up Synapse
+# Setting up Synapse
 Once you have installed synapse as above, you will need to configure it.
-### Using PostgreSQL
+## TLS certificates
-By default Synapse uses an [SQLite](https://sqlite.org/) database and in doing so trades
+The default configuration exposes a single HTTP port: http://localhost:8008. It
-performance for convenience. Almost all installations should opt to use [PostgreSQL](https://www.postgresql.org)
+is suitable for local testing, but for any practical use, you will either need
-instead. Advantages include:
+to enable a reverse proxy, or configure Synapse to expose an HTTPS port.
- significant performance improvements due to the superior threading and
+For information on using a reverse proxy, see
-  caching model, smarter query optimiser
+[docs/reverse_proxy.rst](docs/reverse_proxy.rst).
 - allowing the DB to be run on separate hardware
-For information on how to install and use PostgreSQL in Synapse, please see
+To configure Synapse to expose an HTTPS port, you will need to edit
-[docs/postgres.md](docs/postgres.md)
+`homeserver.yaml`, as follows:
-SQLite is only acceptable for testing purposes. SQLite should not be used in
+* First, under the `listeners` section, uncomment the configuration for the
 a production server. Synapse will perform poorly when using
 SQLite, especially when participating in large rooms.
 ### TLS certificates
 The default configuration exposes a single HTTP port on the local
 interface: `http://localhost:8008`. It is suitable for local testing,
 but for any practical use, you will need Synapse's APIs to be served
 over HTTPS.
 The recommended way to do so is to set up a reverse proxy on port
 `8448`. You can find documentation on doing so in
 [docs/reverse_proxy.md](docs/reverse_proxy.md).
 Alternatively, you can configure Synapse to expose an HTTPS port. To do
 so, you will need to edit `homeserver.yaml`, as follows:
 - 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:
 ```yaml
  - port: 8448
    type: http
    tls: true
    resources:
      - names: [client, federation]
  ```
-
+    - port: 8448
- You will also need to uncomment the `tls_certificate_path` and
+      type: http
-  `tls_private_key_path` lines under the `TLS` section. You will need to manage
+      tls: true
-  provisioning of these certificates yourself.
+      resources:
-
+        - names: [client, federation]
-  If you are using your own certificate, be sure to use a `.pem` file that
+  ```
-  includes the full certificate chain including any intermediate certificates
+* You will also need to uncomment the `tls_certificate_path` and
-  (for instance, if using certbot, use `fullchain.pem` as your certificate, not
+  `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). If you
  are using your own certificate, be sure to use a `.pem` file that includes
  the full certificate chain including any intermediate certificates (for
  instance, if using certbot, use `fullchain.pem` as your certificate, not
  `cert.pem`).
 For a more detailed guide to configuring your server for federation, see
-[federate.md](docs/federate.md).
+[federate.md](docs/federate.md)
 ### Client Well-Known URI
-Setting up the client Well-Known URI is optional but if you set it up, it will
+## Email
 allow users to enter their full username (e.g. `@user:<server_name>`) into clients
 which support well-known lookup to automatically configure the homeserver and
 identity server URLs. This is useful so that users don't have to memorize or think
 about the actual homeserver URL you are using.
-The URL `https://<server_name>/.well-known/matrix/client` should return JSON in
+It is desirable for Synapse to have the capability to send email. For example,
-the following format.
+this is required to support the 'password reset' feature.
 ```json
 {
  "m.homeserver": {
    "base_url": "https://<matrix.example.com>"
  }
 }
 ```
 It can optionally contain identity server information as well.
 ```json
 {
  "m.homeserver": {
    "base_url": "https://<matrix.example.com>"
  },
  "m.identity_server": {
    "base_url": "https://<identity.example.com>"
  }
 }
 ```
 To work in browser based clients, the file must be served with the appropriate
 Cross-Origin Resource Sharing (CORS) headers. A recommended value would be
 `Access-Control-Allow-Origin: *` which would allow all browser based clients to
 view it.
 In nginx this would be something like:
 ```nginx
 location /.well-known/matrix/client {
    return 200 '{"m.homeserver": {"base_url": "https://<matrix.example.com>"}}';
    default_type application/json;
    add_header Access-Control-Allow-Origin *;
 }
 ```
 You should also ensure the `public_baseurl` option in `homeserver.yaml` is set
 correctly. `public_baseurl` should be set to the URL that clients will use to
 connect to your server. This is the same URL you put for the `m.homeserver`
 `base_url` above.
 ```yaml
 public_baseurl: "https://<matrix.example.com>"
 ```
 ### Email
 It is desirable for Synapse to have the capability to send email. This allows
 Synapse to send password reset emails, send verifications when an email address
 is added to a user's account, and send email notifications to users when they
 receive new messages.
 To configure an SMTP server for Synapse, modify the configuration section
-headed `email`, and be sure to have at least the `smtp_host`, `smtp_port`
+headed ``email``, and be sure to have at least the ``smtp_host``, ``smtp_port``
-and `notif_from` fields filled out.  You may also need to set `smtp_user`,
+and ``notif_from`` fields filled out. You may also need to set ``smtp_user``,
-`smtp_pass`, and `require_transport_security`.
+``smtp_pass``, and ``require_transport_security``.
-If email is not configured, password reset, registration and notifications via
+If Synapse is not configured with an SMTP server, password reset via email will
-email will be disabled.
+ be disabled by default.
-### Registering a user
+## Registering a user
-The easiest way to create a new user is to do so from a client like [Element](https://element.io/).
+The easiest way to create a new user is to do so from a client like [Riot](https://riot.im).
-Alternatively, you can do so from the command line. This can be done as follows:
+Alternatively you can do so from the command line if you have installed via pip.
- 1. If synapse was installed via pip, activate the virtualenv as follows (if Synapse was
+This can be done as follows:
    installed via a prebuilt package, `register_new_matrix_user` should already be
    on the search path):
    ```sh
    cd ~/synapse
    source env/bin/activate
    synctl start # if not already running
    ```
 2. Run the following command:
    ```sh
    register_new_matrix_user -c homeserver.yaml http://localhost:8008
    ```
 This will prompt you to add details for the new user, and will then connect to
 the running Synapse to create the new user. For example:
 ```
 $ source ~/synapse/env/bin/activate
 $ synctl start # if not already running
 $ register_new_matrix_user -c homeserver.yaml http://localhost:8008
 New user localpart: erikj
 Password:
 Confirm password:
@@ -559,35 +443,22 @@ value is generated by `--generate-config`), but it should be kept secret, as
 anyone with knowledge of it can register users, including admin accounts,
 on your server even if `enable_registration` is `false`.
-### Setting up a TURN server
+## Setting up a TURN server
 For reliable VoIP calls to be routed via this homeserver, you MUST configure
-a TURN server. See [docs/turn-howto.md](docs/turn-howto.md) for details.
+a TURN server.  See [docs/turn-howto.rst](docs/turn-howto.rst) for details.
-### URL previews
+## URL previews
 Synapse includes support for previewing URLs, which is disabled by default.  To
 turn it on you must enable the `url_preview_enabled: True` config parameter
 and explicitly specify the IP ranges that Synapse is not allowed to spider for
 previewing in the `url_preview_ip_range_blacklist` configuration parameter.
 This is critical from a security perspective to stop arbitrary Matrix users
-spidering 'internal' URLs on your network. At the very least we recommend that
+spidering 'internal' URLs on your network.  At the very least we recommend that
 your loopback and RFC1918 IP addresses are blacklisted.
-This also requires the optional `lxml` python dependency to be  installed. This
+This also requires the optional lxml and netaddr python dependencies to be
-in turn requires the `libxml2` library to be available - on  Debian/Ubuntu this
+installed.  This in turn requires the libxml2 library to be available - on
-means `apt-get install libxml2-dev`, or equivalent for your OS.
+Debian/Ubuntu this means `apt-get install libxml2-dev`, or equivalent for
-
+your OS.
 ### Troubleshooting Installation
 `pip` seems to leak *lots* of memory during installation. For instance, a Linux
 host with 512MB of RAM may run out of memory whilst installing Twisted. If this
 happens, you will have to individually install the dependencies which are
 failing, e.g.:
 ```sh
 pip install twisted
 ```
 If you have any other problems, feel free to ask in
 [#synapse:matrix.org](https://matrix.to/#/#synapse:matrix.org).
@@ -8,22 +8,20 @@ include demo/demo.tls.dh
 include demo/*.py
 include demo/*.sh
-recursive-include synapse/storage *.sql
+recursive-include synapse/storage/schema *.sql
-recursive-include synapse/storage *.sql.postgres
+recursive-include synapse/storage/schema *.sql.postgres
-recursive-include synapse/storage *.sql.sqlite
+recursive-include synapse/storage/schema *.sql.sqlite
-recursive-include synapse/storage *.py
+recursive-include synapse/storage/schema *.py
-recursive-include synapse/storage *.txt
+recursive-include synapse/storage/schema *.txt
 recursive-include synapse/storage *.md
 recursive-include docs *
 recursive-include scripts *
 recursive-include scripts-dev *
 recursive-include synapse *.pyi
 recursive-include tests *.py
-recursive-include tests *.pem
+include tests/http/ca.crt
-recursive-include tests *.p8
+include tests/http/ca.key
-recursive-include tests *.crt
+include tests/http/server.key
 recursive-include tests *.key
 recursive-include synapse/res *
 recursive-include synapse/static *.css
@@ -31,25 +29,25 @@ recursive-include synapse/static *.gif
 recursive-include synapse/static *.html
 recursive-include synapse/static *.js
 exclude .codecov.yml
 exclude .coveragerc
 exclude .dockerignore
 exclude .editorconfig
 exclude Dockerfile
-exclude mypy.ini
+exclude .dockerignore
 exclude sytest-blacklist
 exclude test_postgresql.sh
 exclude .editorconfig
 exclude sytest-blacklist
 include book.toml
 include pyproject.toml
 recursive-include changelog.d *
 prune .buildkite
 prune .circleci
 prune .codecov.yml
 prune .coveragerc
 prune .github
 prune contrib
 prune debian
 prune demo/etc
 prune docker
-prune snap
+prune mypy.ini
 prune stubs
 exclude jenkins*
 recursive-exclude jenkins *.sh
@@ -1,7 +1,3 @@
 =========================================================
 Synapse |support| |development| |license| |pypi| |python|
 =========================================================
 .. contents::
 Introduction
@@ -41,7 +37,7 @@ which handle:
 - Eventually-consistent cryptographically secure synchronisation of room
  state across a global open network of federated servers and services
 - Sending and receiving extensible messages in a room with (optional)
-  end-to-end encryption
+  end-to-end encryption[1]
 - Inviting, joining, leaving, kicking, banning room members
 - Managing user accounts (registration, login, logout)
 - Using 3rd Party IDs (3PIDs) such as email addresses, phone numbers,
@@ -78,15 +74,7 @@ at the `Matrix spec <https://matrix.org/docs/spec>`_, and experiment with the
 Thanks for using Matrix!
-Support
+[1] End-to-end encryption is currently in beta: `blog post <https://matrix.org/blog/2016/11/21/matrixs-olm-end-to-end-encryption-security-assessment-released-and-implemented-cross-platform-on-riot-at-last>`_.
 =======
 For support installing or managing Synapse, please join |room|_ (from a matrix.org
 account if necessary) and ask questions there. We do not use GitHub issues for
 support requests, only for bug reports and feature requests.
 .. |room| replace:: ``#synapse:matrix.org``
 .. _room: https://matrix.to/#/#synapse:matrix.org
 Synapse Installation
@@ -108,11 +96,12 @@ Unless you are running a test instance of Synapse on your local machine, in
 general, you will need to enable TLS support before you can successfully
 connect from a client: see `<INSTALL.md#tls-certificates>`_.
-An easy way to get started is to login or register via Element at
+An easy way to get started is to login or register via Riot at
-https://app.element.io/#/login or https://app.element.io/#/register respectively.
+https://riot.im/app/#/login or https://riot.im/app/#/register respectively.
 You will need to change the server you are logging into from ``matrix.org``
 and instead specify a Homeserver URL of ``https://<server_name>:8448``
 (or just ``https://<server_name>`` if you are using a reverse proxy).
 (Leave the identity server as the default - see `Identity servers`_.)
 If you prefer to use another client, refer to our
 `client breakdown <https://matrix.org/docs/projects/clients-matrix>`_.
@@ -126,10 +115,10 @@ Registering a new user from a client
 By default, registration of new users via Matrix clients is disabled. To enable
 it, specify ``enable_registration: true`` in ``homeserver.yaml``. (It is then
-recommended to also set up CAPTCHA - see `<docs/CAPTCHA_SETUP.md>`_.)
+recommended to also set up CAPTCHA - see `<docs/CAPTCHA_SETUP.rst>`_.)
 Once ``enable_registration`` is set to ``true``, it is possible to register a
-user via a Matrix client.
+user via `riot.im <https://riot.im/app/#/register>`_ or other Matrix clients.
 Your new user name will be formed partly from the ``server_name``, and partly
 from a localpart you specify when you create the account. Your name will take
@@ -142,45 +131,28 @@ the form of::
 As when logging in, you will need to specify a "Custom server".  Specify your
 desired ``localpart`` in the 'User name' box.
-Security note
+ACME setup
 ==========
 For details on having Synapse manage your federation TLS certificates
 automatically, please see `<docs/ACME.md>`_.
 Security Note
 =============
-Matrix serves raw, user-supplied data in some APIs -- specifically the `content
+Matrix serves raw user generated data in some APIs - specifically the `content
-repository endpoints`_.
+repository endpoints <https://matrix.org/docs/spec/client_server/latest.html#get-matrix-media-r0-download-servername-mediaid>`_.
-.. _content repository endpoints: https://matrix.org/docs/spec/client_server/latest.html#get-matrix-media-r0-download-servername-mediaid
+Whilst we have tried to mitigate against possible XSS attacks (e.g.
 https://github.com/matrix-org/synapse/pull/1021) we recommend running
 matrix homeservers on a dedicated domain name, to limit any malicious user generated
 content served to web browsers a matrix API from being able to attack webapps hosted
 on the same domain.  This is particularly true of sharing a matrix webclient and
 server on the same domain.
-Whilst we make a reasonable effort to mitigate against XSS attacks (for
+See https://github.com/vector-im/riot-web/issues/1977 and
-instance, by using `CSP`_), a Matrix homeserver should not be hosted on a
+https://developer.github.com/changes/2014-04-25-user-content-security for more details.
 domain hosting other web applications. This especially applies to sharing
 the domain with Matrix web clients and other sensitive applications like
 webmail. See
 https://developer.github.com/changes/2014-04-25-user-content-security for more
 information.
 .. _CSP: https://github.com/matrix-org/synapse/pull/1021
 Ideally, the homeserver should not simply be on a different subdomain, but on
 a completely different `registered domain`_ (also known as top-level site or
 eTLD+1). This is because `some attacks`_ are still possible as long as the two
 applications share the same registered domain.
 .. _registered domain: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-2.3
 .. _some attacks: https://en.wikipedia.org/wiki/Session_fixation#Attacks_using_cross-subdomain_cookie
 To illustrate this with an example, if your Element Web or other sensitive web
 application is hosted on ``A.example1.com``, you should ideally host Synapse on
 ``example2.com``. Some amount of protection is offered by hosting on
 ``B.example1.com`` instead, so this is also acceptable in some scenarios.
 However, you should *not* host your Synapse on ``A.example1.com``.
 Note that all of the above refers exclusively to the domain used in Synapse's
 ``public_baseurl`` setting. In particular, it has no bearing on the domain
 mentioned in MXIDs hosted on that server.
 Following this advice ensures that even if an XSS is found in Synapse, the
 impact to other applications will be minimal.
 Upgrading an existing Synapse
@@ -192,6 +164,30 @@ versions of synapse.
 .. _UPGRADE.rst: UPGRADE.rst
 Using PostgreSQL
 ================
 Synapse offers two database engines:
 * `SQLite <https://sqlite.org/>`_
 * `PostgreSQL <https://www.postgresql.org>`_
 By default Synapse uses SQLite in and doing so trades performance for convenience.
 SQLite is only recommended in Synapse for testing purposes or for servers with
 light workloads.
 Almost all installations should opt to use PostreSQL. Advantages include:
 * significant performance improvements due to the superior threading and
  caching model, smarter query optimiser
 * allowing the DB to be run on separate hardware
 * allowing basic active/backup high-availability with a "hot spare" synapse
  pointing at the same DB master, as well as enabling DB replication in
  synapse itself.
 For information on how to install and use PostgreSQL, please see
 `docs/postgres.rst <docs/postgres.rst>`_.
 .. _reverse-proxy:
 Using a reverse proxy with Synapse
@@ -200,13 +196,12 @@ Using a reverse proxy with Synapse
 It is recommended to put a reverse proxy such as
 `nginx <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>`_,
 `Apache <https://httpd.apache.org/docs/current/mod/mod_proxy_http.html>`_,
-`Caddy <https://caddyserver.com/docs/quick-starts/reverse-proxy>`_,
+`Caddy <https://caddyserver.com/docs/proxy>`_ or
-`HAProxy <https://www.haproxy.org/>`_ or
+`HAProxy <https://www.haproxy.org/>`_ in front of Synapse. One advantage of
 `relayd <https://man.openbsd.org/relayd.8>`_ in front of Synapse. One advantage of
 doing so is that it means that you can expose the default https port (443) to
 Matrix clients without needing to run Synapse with root privileges.
-For information on configuring one, see `<docs/reverse_proxy.md>`_.
+For information on configuring one, see `<docs/reverse_proxy.rst>`_.
 Identity Servers
 ================
@@ -241,9 +236,10 @@ email address.
 Password reset
 ==============
-Users can reset their password through their client. Alternatively, a server admin
+If a user has registered an email address to their account using an identity
-can reset a users password using the `admin API <docs/admin_api/user_admin_api.rst#reset-password>`_
+server, they can request a password-reset token via clients such as Riot.
-or by directly editing the database as shown below.
+
 A manual password reset can be done via direct database access as follows.
 First calculate the hash of the new password::
@@ -252,7 +248,7 @@ First calculate the hash of the new password::
    Confirm password:
    $2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-Then update the ``users`` table in the database::
+Then update the `users` table in the database::
    UPDATE users SET password_hash='$2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
        WHERE name='@test:test.com';
@@ -261,8 +257,6 @@ Then update the ``users`` table in the database::
 Synapse Development
 ===================
 Join our developer community on Matrix: `#synapse-dev:matrix.org <https://matrix.to/#/#synapse-dev:matrix.org>`_
 Before setting up a development environment for synapse, make sure you have the
 system dependencies (such as the python header files) installed - see
 `Installing from source <INSTALL.md#installing-from-source>`_.
@@ -276,53 +270,23 @@ directory of your choice::
 Synapse has a number of external dependencies, that are easiest
 to install using pip and a virtualenv::
-    python3 -m venv ./env
+    virtualenv -p python3 env
-    source ./env/bin/activate
+    source env/bin/activate
-    pip install -e ".[all,test]"
+    python -m pip install --no-use-pep517 -e .[all]
 This will run a process of downloading and installing all the needed
-dependencies into a virtual env. If any dependencies fail to install,
+dependencies into a virtual env.
 try installing the failing modules individually::
-    pip install -e "module-name"
+Once this is done, you may wish to run Synapse's unit tests, to
 check that everything is installed as it should be::
-We recommend using the demo which starts 3 federated instances running on ports `8080` - `8082`
+    python -m twisted.trial tests
-    ./demo/start.sh
+This should end with a 'PASSED' result::
-(to stop, you can use `./demo/stop.sh`)
+    Ran 143 tests in 0.601s
 If you just want to start a single instance of the app and run it directly::
    # Create the homeserver.yaml config once
    python -m synapse.app.homeserver \
      --server-name my.domain.name \
      --config-path homeserver.yaml \
      --generate-config \
      --report-stats=[yes|no]
    # Start the app
    python -m synapse.app.homeserver --config-path homeserver.yaml
 Running the unit tests
 ======================
 After getting up and running, you may wish to run Synapse's unit tests to
 check that everything is installed correctly::
    trial tests
 This should end with a 'PASSED' result (note that exact numbers will
 differ)::
    Ran 1337 tests in 716.064s
    PASSED (skips=15, successes=1322)
 For more tips on running the unit tests, like running a specific test or
 to see the logging output, see the `CONTRIBUTING doc <CONTRIBUTING.md#run-the-unit-tests>`_.
    PASSED (successes=143)
 Running the Integration Tests
 =============================
@@ -336,21 +300,22 @@ Testing with SyTest is recommended for verifying that changes related to the
 Client-Server API are functioning correctly. See the `installation instructions
 <https://github.com/matrix-org/sytest#installing>`_ for details.
 Building Internal API Documentation
 ===================================
-Platform dependencies
+Before building internal API documentation install sphinx and
-=====================
+sphinxcontrib-napoleon::
-Synapse uses a number of platform dependencies such as Python and PostgreSQL,
+    pip install sphinx
-and aims to follow supported upstream versions. See the
+    pip install sphinxcontrib-napoleon
 `<docs/deprecation_policy.md>`_ document for more details.
 Building internal API documentation::
    python setup.py build_sphinx
 Troubleshooting
 ===============
 Need help? Join our community support room on Matrix:
 `#synapse:matrix.org <https://matrix.to/#/#synapse:matrix.org>`_
 Running out of File Handles
 ---------------------------
@@ -415,42 +380,4 @@ massive excess of outgoing federation requests (see `discussion
 indicate that your server is also issuing far more outgoing federation
 requests than can be accounted for by your users' activity, this is a
 likely cause. The misbehavior can be worked around by setting
-the following in the Synapse config file:
+``use_presence: false`` in the Synapse config file.
 .. code-block:: yaml
   presence:
       enabled: false
 People can't accept room invitations from me
 --------------------------------------------
 The typical failure mode here is that you send an invitation to someone
 to join a room or direct chat, but when they go to accept it, they get an
 error (typically along the lines of "Invalid signature"). They might see
 something like the following in their logs::
    2019-09-11 19:32:04,271 - synapse.federation.transport.server - 288 - WARNING - GET-11752 - authenticate_request failed: 401: Invalid signature for server <server> with key ed25519:a_EqML: Unable to verify signature for <server>
 This is normally caused by a misconfiguration in your reverse-proxy. See
 `<docs/reverse_proxy.md>`_ and double-check that your settings are correct.
 .. |support| image:: https://img.shields.io/matrix/synapse:matrix.org?label=support&logo=matrix
  :alt: (get support on #synapse:matrix.org)
  :target: https://matrix.to/#/#synapse:matrix.org
 .. |development| image:: https://img.shields.io/matrix/synapse-dev:matrix.org?label=development&logo=matrix
  :alt: (discuss development on #synapse-dev:matrix.org)
  :target: https://matrix.to/#/#synapse-dev:matrix.org
 .. |license| image:: https://img.shields.io/github/license/matrix-org/synapse
  :alt: (check license in LICENSE file)
  :target: LICENSE
 .. |pypi| image:: https://img.shields.io/pypi/v/matrix-synapse
  :alt: (latest version released on PyPi)
  :target: https://pypi.org/project/matrix-synapse
 .. |python| image:: https://img.shields.io/pypi/pyversions/matrix-synapse
  :alt: (supported python versions)
  :target: https://pypi.org/project/matrix-synapse
@@ -2,893 +2,108 @@ Upgrading Synapse
 =================
 Before upgrading check if any special steps are required to upgrade from the
-version you currently have installed to the current version of Synapse. The extra
+what you currently have installed to current version of synapse. The extra
 instructions that may be required are listed later in this document.
-* Check that your versions of Python and PostgreSQL are still supported.
+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:
-  Synapse follows upstream lifecycles for `Python`_ and `PostgreSQL`_, and
+   .. code:: bash
  removes support for versions which are no longer maintained.
  The website https://endoflife.date also offers convenient summaries.
  .. _Python: https://devguide.python.org/devcycle/#end-of-life-branches
  .. _PostgreSQL: https://www.postgresql.org/support/versioning/
 * If Synapse was installed using `prebuilt packages
  <INSTALL.md#prebuilt-packages>`_, you will need to follow the normal process
  for upgrading those packages.
 * If Synapse was installed from source, then:
  1. Activate the virtualenv before upgrading. For example, if Synapse is
     installed in a virtualenv in ``~/synapse/env`` then run:
     .. code:: bash
       source ~/synapse/env/bin/activate
-  2. If Synapse was installed using pip then upgrade to the latest version by
+2. If synapse was installed using pip then upgrade to the latest version by
-     running:
+   running:
-     .. code:: bash
+   .. code:: bash
-       pip install --upgrade matrix-synapse
+       pip install --upgrade matrix-synapse[all]
-     If Synapse was installed using git then upgrade to the latest version by
+       # restart synapse
-     running:
+       synctl restart
     .. code:: bash
   If synapse was installed using git then upgrade to the latest version by
   running:
   .. code:: bash
       # Pull the latest version of the master branch.
       git pull
       pip install --upgrade .
-  3. Restart Synapse:
+       # Update synapse and its python dependencies.
-
+       pip install --upgrade .[all]
     .. code:: bash
       # restart synapse
       ./synctl restart
-To check whether your update was successful, you can check the running server
+
-version with:
+To check whether your update was successful, you can check the Server header
 returned by the Client-Server API:
 .. code:: bash
-    # you may need to replace 'localhost:8008' if synapse is not configured
+    # replace <host.name> with the hostname of your synapse homeserver.
-    # to listen on port 8008.
+    # You may need to specify a port (eg, :8448) if your server is not
-
+    # configured on port 443.
-    curl http://localhost:8008/_synapse/admin/v1/server_version
+    curl -kv https://<host.name>/_matrix/client/versions 2>&1 | grep "Server:"
 Rolling back to older versions
 ------------------------------
 Rolling back to previous releases can be difficult, due to database schema
 changes between releases. Where we have been able to test the rollback process,
 this will be noted below.
 In general, you will need to undo any changes made during the upgrade process,
 for example:
 * pip:
  .. code:: bash
     source env/bin/activate
     # replace `1.3.0` accordingly:
     pip install matrix-synapse==1.3.0
 * Debian:
  .. code:: bash
     # replace `1.3.0` and `stretch` accordingly:
     wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb
     dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
 Upgrading to v1.37.0
 ====================
 Deprecation of the current spam checker interface
 -------------------------------------------------
 The current spam checker interface is deprecated in favour of a new generic modules system.
 Authors of spam checker modules can refer to `this documentation <https://matrix-org.github.io/synapse/develop/modules.html#porting-an-existing-module-that-uses-the-old-interface>`_
 to update their modules. Synapse administrators can refer to `this documentation <https://matrix-org.github.io/synapse/develop/modules.html#using-modules>`_
 to update their configuration once the modules they are using have been updated.
 We plan to remove support for the current spam checker interface in August 2021.
 More module interfaces will be ported over to this new generic system in future versions
 of Synapse.
 Upgrading to v1.34.0
 ====================
 ``room_invite_state_types`` configuration setting
 -----------------------------------------------
 The ``room_invite_state_types`` configuration setting has been deprecated and
 replaced with ``room_prejoin_state``. See the `sample configuration file <https://github.com/matrix-org/synapse/blob/v1.34.0/docs/sample_config.yaml#L1515>`_.
 If you have set ``room_invite_state_types`` to the default value you should simply
 remove it from your configuration file. The default value used to be:
 .. code:: yaml
   room_invite_state_types:
      - "m.room.join_rules"
      - "m.room.canonical_alias"
      - "m.room.avatar"
      - "m.room.encryption"
      - "m.room.name"
 If you have customised this value, you should remove ``room_invite_state_types`` and
 configure ``room_prejoin_state`` instead.
 Upgrading to v1.33.0
 ====================
 Account Validity HTML templates can now display a user's expiration date
 ------------------------------------------------------------------------
 This may affect you if you have enabled the account validity feature, and have made use of a
 custom HTML template specified by the ``account_validity.template_dir`` or ``account_validity.account_renewed_html_path``
 Synapse config options.
 The template can now accept an ``expiration_ts`` variable, which represents the unix timestamp in milliseconds for the
 future date of which their account has been renewed until. See the
 `default template <https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_renewed.html>`_
 for an example of usage.
 ALso note that a new HTML template, ``account_previously_renewed.html``, has been added. This is is shown to users
 when they attempt to renew their account with a valid renewal token that has already been used before. The default
 template contents can been found
 `here <https://github.com/matrix-org/synapse/blob/release-v1.33.0/synapse/res/templates/account_previously_renewed.html>`_,
 and can also accept an ``expiration_ts`` variable. This template replaces the error message users would previously see
 upon attempting to use a valid renewal token more than once.
 Upgrading to v1.32.0
 ====================
 Regression causing connected Prometheus instances to become overwhelmed
 -----------------------------------------------------------------------
 This release introduces `a regression <https://github.com/matrix-org/synapse/issues/9853>`_
 that can overwhelm connected Prometheus instances. This issue is not present in
 Synapse v1.32.0rc1.
 If you have been affected, please downgrade to 1.31.0. You then may need to
 remove excess writeahead logs in order for Prometheus to recover. Instructions
 for doing so are provided
 `here <https://github.com/matrix-org/synapse/pull/9854#issuecomment-823472183>`_.
 Dropping support for old Python, Postgres and SQLite versions
 -------------------------------------------------------------
 In line with our `deprecation policy <https://github.com/matrix-org/synapse/blob/release-v1.32.0/docs/deprecation_policy.md>`_,
 we've dropped support for Python 3.5 and PostgreSQL 9.5, as they are no longer supported upstream.
 This release of Synapse requires Python 3.6+ and PostgresSQL 9.6+ or SQLite 3.22+.
 Removal of old List Accounts Admin API
 --------------------------------------
 The deprecated v1 "list accounts" admin API (``GET /_synapse/admin/v1/users/<user_id>``) has been removed in this version.
 The `v2 list accounts API <https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#list-accounts>`_
 has been available since Synapse 1.7.0 (2019-12-13), and is accessible under ``GET /_synapse/admin/v2/users``.
 The deprecation of the old endpoint was announced with Synapse 1.28.0 (released on 2021-02-25).
 Application Services must use type ``m.login.application_service`` when registering users
 -----------------------------------------------------------------------------------------
 In compliance with the
 `Application Service spec <https://matrix.org/docs/spec/application_service/r0.1.2#server-admin-style-permissions>`_,
 Application Services are now required to use the ``m.login.application_service`` type when registering users via the
 ``/_matrix/client/r0/register`` endpoint. This behaviour was deprecated in Synapse v1.30.0.
 Please ensure your Application Services are up to date.
 Upgrading to v1.29.0
 ====================
 Requirement for X-Forwarded-Proto header
 ----------------------------------------
 When using Synapse with a reverse proxy (in particular, when using the
 `x_forwarded` option on an HTTP listener), Synapse now expects to receive an
 `X-Forwarded-Proto` header on incoming HTTP requests. If it is not set, Synapse
 will log a warning on each received request.
 To avoid the warning, administrators using a reverse proxy should ensure that
 the reverse proxy sets `X-Forwarded-Proto` header to `https` or `http` to
 indicate the protocol used by the client.
 Synapse also requires the `Host` header to be preserved.
 See the `reverse proxy documentation <docs/reverse_proxy.md>`_, where the
 example configurations have been updated to show how to set these headers.
 (Users of `Caddy <https://caddyserver.com/>`_ are unaffected, since we believe it
 sets `X-Forwarded-Proto` by default.)
 Upgrading to v1.27.0
 ====================
 Changes to callback URI for OAuth2 / OpenID Connect and SAML2
 -------------------------------------------------------------
 This version changes the URI used for callbacks from OAuth2 and SAML2 identity providers:
 * If your server is configured for single sign-on via an OpenID Connect or OAuth2 identity
  provider, you will need to add ``[synapse public baseurl]/_synapse/client/oidc/callback``
  to the list of permitted "redirect URIs" at the identity provider.
  See `docs/openid.md <docs/openid.md>`_ for more information on setting up OpenID
  Connect.
 * If your server is configured for single sign-on via a SAML2 identity provider, you will
  need to add ``[synapse public baseurl]/_synapse/client/saml2/authn_response`` as a permitted
  "ACS location" (also known as "allowed callback URLs") at the identity provider.
  The "Issuer" in the "AuthnRequest" to the SAML2 identity provider is also updated to
  ``[synapse public baseurl]/_synapse/client/saml2/metadata.xml``. If your SAML2 identity
  provider uses this property to validate or otherwise identify Synapse, its configuration
  will need to be updated to use the new URL. Alternatively you could create a new, separate
  "EntityDescriptor" in your SAML2 identity provider with the new URLs and leave the URLs in
  the existing "EntityDescriptor" as they were.
 Changes to HTML templates
 -------------------------
 The HTML templates for SSO and email notifications now have `Jinja2's autoescape <https://jinja.palletsprojects.com/en/2.11.x/api/#autoescaping>`_
 enabled for files ending in ``.html``, ``.htm``, and ``.xml``. If you have customised
 these templates and see issues when viewing them you might need to update them.
 It is expected that most configurations will need no changes.
 If you have customised the templates *names* for these templates, it is recommended
 to verify they end in ``.html`` to ensure autoescape is enabled.
 The above applies to the following templates:
 * ``add_threepid.html``
 * ``add_threepid_failure.html``
 * ``add_threepid_success.html``
 * ``notice_expiry.html``
 * ``notice_expiry.html``
 * ``notif_mail.html`` (which, by default, includes ``room.html`` and ``notif.html``)
 * ``password_reset.html``
 * ``password_reset_confirmation.html``
 * ``password_reset_failure.html``
 * ``password_reset_success.html``
 * ``registration.html``
 * ``registration_failure.html``
 * ``registration_success.html``
 * ``sso_account_deactivated.html``
 * ``sso_auth_bad_user.html``
 * ``sso_auth_confirm.html``
 * ``sso_auth_success.html``
 * ``sso_error.html``
 * ``sso_login_idp_picker.html``
 * ``sso_redirect_confirm.html``
 Upgrading to v1.26.0
 ====================
 Rolling back to v1.25.0 after a failed upgrade
 ----------------------------------------------
 v1.26.0 includes a lot of large changes. If something problematic occurs, you
 may want to roll-back to a previous version of Synapse. Because v1.26.0 also
 includes a new database schema version, reverting that version is also required
 alongside the generic rollback instructions mentioned above. In short, to roll
 back to v1.25.0 you need to:
 1. Stop the server
 2. Decrease the schema version in the database:
   .. code:: sql
      UPDATE schema_version SET version = 58;
 3. Delete the ignored users & chain cover data:
   .. code:: sql
      DROP TABLE IF EXISTS ignored_users;
      UPDATE rooms SET has_auth_chain_index = false;
   For PostgreSQL run:
   .. code:: sql
      TRUNCATE event_auth_chain_links;
      TRUNCATE event_auth_chains;
   For SQLite run:
   .. code:: sql
      DELETE FROM event_auth_chain_links;
      DELETE FROM event_auth_chains;
 4. Mark the deltas as not run (so they will re-run on upgrade).
   .. code:: sql
      DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/01ignored_user.py";
      DELETE FROM applied_schema_deltas WHERE version = 59 AND file = "59/06chain_cover_index.sql";
 5. Downgrade Synapse by following the instructions for your installation method
   in the "Rolling back to older versions" section above.
 Upgrading to v1.25.0
 ====================
 Last release supporting Python 3.5
 ----------------------------------
 This is the last release of Synapse which guarantees support with Python 3.5,
 which passed its upstream End of Life date several months ago.
 We will attempt to maintain support through March 2021, but without guarantees.
 In the future, Synapse will follow upstream schedules for ending support of
 older versions of Python and PostgreSQL. Please upgrade to at least Python 3.6
 and PostgreSQL 9.6 as soon as possible.
 Blacklisting IP ranges
 ----------------------
 Synapse v1.25.0 includes new settings, ``ip_range_blacklist`` and
 ``ip_range_whitelist``, for controlling outgoing requests from Synapse for federation,
 identity servers, push, and for checking key validity for third-party invite events.
 The previous setting, ``federation_ip_range_blacklist``, is deprecated. The new
 ``ip_range_blacklist`` defaults to private IP ranges if it is not defined.
 If you have never customised ``federation_ip_range_blacklist`` it is recommended
 that you remove that setting.
 If you have customised ``federation_ip_range_blacklist`` you should update the
 setting name to ``ip_range_blacklist``.
 If you have a custom push server that is reached via private IP space you may
 need to customise ``ip_range_blacklist`` or ``ip_range_whitelist``.
 Upgrading to v1.24.0
 ====================
 Custom OpenID Connect mapping provider breaking change
 ------------------------------------------------------
 This release allows the OpenID Connect mapping provider to perform normalisation
 of the localpart of the Matrix ID. This allows for the mapping provider to
 specify different algorithms, instead of the [default way](https://matrix.org/docs/spec/appendices#mapping-from-other-character-sets).
 If your Synapse configuration uses a custom mapping provider
 (`oidc_config.user_mapping_provider.module` is specified and not equal to
 `synapse.handlers.oidc_handler.JinjaOidcMappingProvider`) then you *must* ensure
 that `map_user_attributes` of the mapping provider performs some normalisation
 of the `localpart` returned. To match previous behaviour you can use the
 `map_username_to_mxid_localpart` function provided by Synapse. An example is
 shown below:
 .. code-block:: python
  from synapse.types import map_username_to_mxid_localpart
  class MyMappingProvider:
      def map_user_attributes(self, userinfo, token):
          # ... your custom logic ...
          sso_user_id = ...
          localpart = map_username_to_mxid_localpart(sso_user_id)
          return {"localpart": localpart}
 Removal historical Synapse Admin API
 ------------------------------------
 Historically, the Synapse Admin API has been accessible under:
 * ``/_matrix/client/api/v1/admin``
 * ``/_matrix/client/unstable/admin``
 * ``/_matrix/client/r0/admin``
 * ``/_synapse/admin/v1``
 The endpoints with ``/_matrix/client/*`` prefixes have been removed as of v1.24.0.
 The Admin API is now only accessible under:
 * ``/_synapse/admin/v1``
 The only exception is the `/admin/whois` endpoint, which is
 `also available via the client-server API <https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid>`_.
 The deprecation of the old endpoints was announced with Synapse 1.20.0 (released
 on 2020-09-22) and makes it easier for homeserver admins to lock down external
 access to the Admin API endpoints.
 Upgrading to v1.23.0
 ====================
 Structured logging configuration breaking changes
 -------------------------------------------------
 This release deprecates use of the ``structured: true`` logging configuration for
 structured logging. If your logging configuration contains ``structured: true``
 then it should be modified based on the `structured logging documentation
 <https://github.com/matrix-org/synapse/blob/master/docs/structured_logging.md>`_.
 The ``structured`` and ``drains`` logging options are now deprecated and should
 be replaced by standard logging configuration of ``handlers`` and ``formatters``.
 A future will release of Synapse will make using ``structured: true`` an error.
 Upgrading to v1.22.0
 ====================
 ThirdPartyEventRules breaking changes
 -------------------------------------
 This release introduces a backwards-incompatible change to modules making use of
 ``ThirdPartyEventRules`` in Synapse. If you make use of a module defined under the
 ``third_party_event_rules`` config option, please make sure it is updated to handle
 the below change:
 The ``http_client`` argument is no longer passed to modules as they are initialised. Instead,
 modules are expected to make use of the ``http_client`` property on the ``ModuleApi`` class.
 Modules are now passed a ``module_api`` argument during initialisation, which is an instance of
 ``ModuleApi``. ``ModuleApi`` instances have a ``http_client`` property which acts the same as
 the ``http_client`` argument previously passed to ``ThirdPartyEventRules`` modules.
 Upgrading to v1.21.0
 ====================
 Forwarding ``/_synapse/client`` through your reverse proxy
 ----------------------------------------------------------
 The `reverse proxy documentation
 <https://github.com/matrix-org/synapse/blob/develop/docs/reverse_proxy.md>`_ has been updated
 to include reverse proxy directives for ``/_synapse/client/*`` endpoints. As the user password
 reset flow now uses endpoints under this prefix, **you must update your reverse proxy
 configurations for user password reset to work**.
 Additionally, note that the `Synapse worker documentation
 <https://github.com/matrix-org/synapse/blob/develop/docs/workers.md>`_ has been updated to
 state that the ``/_synapse/client/password_reset/email/submit_token`` endpoint can be handled
 by all workers. If you make use of Synapse's worker feature, please update your reverse proxy
 configuration to reflect this change.
 New HTML templates
 ------------------
 A new HTML template,
 `password_reset_confirmation.html <https://github.com/matrix-org/synapse/blob/develop/synapse/res/templates/password_reset_confirmation.html>`_,
 has been added to the ``synapse/res/templates`` directory. If you are using a
 custom template directory, you may want to copy the template over and modify it.
 Note that as of v1.20.0, templates do not need to be included in custom template
 directories for Synapse to start. The default templates will be used if a custom
 template cannot be found.
 This page will appear to the user after clicking a password reset link that has
 been emailed to them.
 To complete password reset, the page must include a way to make a `POST`
 request to
 ``/_synapse/client/password_reset/{medium}/submit_token``
 with the query parameters from the original link, presented as a URL-encoded form. See the file
 itself for more details.
 Updated Single Sign-on HTML Templates
 -------------------------------------
 The ``saml_error.html`` template was removed from Synapse and replaced with the
 ``sso_error.html`` template. If your Synapse is configured to use SAML and a
 custom ``sso_redirect_confirm_template_dir`` configuration then any customisations
 of the ``saml_error.html`` template will need to be merged into the ``sso_error.html``
 template. These templates are similar, but the parameters are slightly different:
 * The ``msg`` parameter should be renamed to ``error_description``.
 * There is no longer a ``code`` parameter for the response code.
 * A string ``error`` parameter is available that includes a short hint of why a
  user is seeing the error page.
 Upgrading to v1.18.0
 ====================
 Docker `-py3` suffix will be removed in future versions
 -------------------------------------------------------
 From 10th August 2020, we will no longer publish Docker images with the `-py3` tag suffix. The images tagged with the `-py3` suffix have been identical to the non-suffixed tags since release 0.99.0, and the suffix is obsolete.
 On 10th August, we will remove the `latest-py3` tag. Existing per-release tags (such as `v1.18.0-py3`) will not be removed, but no new `-py3` tags will be added.
 Scripts relying on the `-py3` suffix will need to be updated.
 Redis replication is now recommended in lieu of TCP replication
 ---------------------------------------------------------------
 When setting up worker processes, we now recommend the use of a Redis server for replication. **The old direct TCP connection method is deprecated and will be removed in a future release.**
 See `docs/workers.md <docs/workers.md>`_ for more details.
 Upgrading to v1.14.0
 ====================
 This version includes a database update which is run as part of the upgrade,
 and which may take a couple of minutes in the case of a large server. Synapse
 will not respond to HTTP requests while this update is taking place.
 Upgrading to v1.13.0
 ====================
 Incorrect database migration in old synapse versions
 ----------------------------------------------------
 A bug was introduced in Synapse 1.4.0 which could cause the room directory to
 be incomplete or empty if Synapse was upgraded directly from v1.2.1 or
 earlier, to versions between v1.4.0 and v1.12.x.
 This will *not* be a problem for Synapse installations which were:
 * created at v1.4.0 or later,
 * upgraded via v1.3.x, or
 * upgraded straight from v1.2.1 or earlier to v1.13.0 or later.
 If completeness of the room directory is a concern, installations which are
 affected can be repaired as follows:
 1. Run the following sql from a `psql` or `sqlite3` console:
   .. code:: sql
     INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES
        ('populate_stats_process_rooms', '{}', 'current_state_events_membership');
     INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES
        ('populate_stats_process_users', '{}', 'populate_stats_process_rooms');
 2. Restart synapse.
 New Single Sign-on HTML Templates
 ---------------------------------
 New templates (``sso_auth_confirm.html``, ``sso_auth_success.html``, and
 ``sso_account_deactivated.html``) were added to Synapse. If your Synapse is
 configured to use SSO and a custom  ``sso_redirect_confirm_template_dir``
 configuration then these templates will need to be copied from
 `synapse/res/templates <synapse/res/templates>`_ into that directory.
 Synapse SSO Plugins Method Deprecation
 --------------------------------------
 Plugins using the ``complete_sso_login`` method of
 ``synapse.module_api.ModuleApi`` should update to using the async/await
 version ``complete_sso_login_async`` which includes additional checks. The
 non-async version is considered deprecated.
 Rolling back to v1.12.4 after a failed upgrade
 ----------------------------------------------
 v1.13.0 includes a lot of large changes. If something problematic occurs, you
 may want to roll-back to a previous version of Synapse. Because v1.13.0 also
 includes a new database schema version, reverting that version is also required
 alongside the generic rollback instructions mentioned above. In short, to roll
 back to v1.12.4 you need to:
 1. Stop the server
 2. Decrease the schema version in the database:
   .. code:: sql
      UPDATE schema_version SET version = 57;
 3. Downgrade Synapse by following the instructions for your installation method
   in the "Rolling back to older versions" section above.
 Upgrading to v1.12.0
 ====================
 This version includes a database update which is run as part of the upgrade,
 and which may take some time (several hours in the case of a large
 server). Synapse will not respond to HTTP requests while this update is taking
 place.
 This is only likely to be a problem in the case of a server which is
 participating in many rooms.
 0. As with all upgrades, it is recommended that you have a recent backup of
   your database which can be used for recovery in the event of any problems.
 1. As an initial check to see if you will be affected, you can try running the
   following query from the `psql` or `sqlite3` console. It is safe to run it
   while Synapse is still running.
   .. code:: sql
      SELECT MAX(q.v) FROM (
        SELECT (
          SELECT ej.json AS v
          FROM state_events se INNER JOIN event_json ej USING (event_id)
          WHERE se.room_id=rooms.room_id AND se.type='m.room.create' AND se.state_key=''
          LIMIT 1
        ) FROM rooms WHERE rooms.room_version IS NULL
      ) q;
   This query will take about the same amount of time as the upgrade process: ie,
   if it takes 5 minutes, then it is likely that Synapse will be unresponsive for
   5 minutes during the upgrade.
   If you consider an outage of this duration to be acceptable, no further
   action is necessary and you can simply start Synapse 1.12.0.
   If you would prefer to reduce the downtime, continue with the steps below.
 2. The easiest workaround for this issue is to manually
   create a new index before upgrading. On PostgreSQL, his can be done as follows:
   .. code:: sql
      CREATE INDEX CONCURRENTLY tmp_upgrade_1_12_0_index
      ON state_events(room_id) WHERE type = 'm.room.create';
   The above query may take some time, but is also safe to run while Synapse is
   running.
   We assume that no SQLite users have databases large enough to be
   affected. If you *are* affected, you can run a similar query, omitting the
   ``CONCURRENTLY`` keyword. Note however that this operation may in itself cause
   Synapse to stop running for some time. Synapse admins are reminded that
   `SQLite is not recommended for use outside a test
   environment <https://github.com/matrix-org/synapse/blob/master/README.rst#using-postgresql>`_.
 3. Once the index has been created, the ``SELECT`` query in step 1 above should
   complete quickly. It is therefore safe to upgrade to Synapse 1.12.0.
 4. Once Synapse 1.12.0 has successfully started and is responding to HTTP
   requests, the temporary index can be removed:
   .. code:: sql
      DROP INDEX tmp_upgrade_1_12_0_index;
 Upgrading to v1.10.0
 ====================
 Synapse will now log a warning on start up if used with a PostgreSQL database
 that has a non-recommended locale set.
 See `docs/postgres.md <docs/postgres.md>`_ for details.
 Upgrading to v1.8.0
 ===================
 Specifying a ``log_file`` config option will now cause Synapse to refuse to
 start, and should be replaced by with the ``log_config`` option. Support for
 the ``log_file`` option was removed in v1.3.0 and has since had no effect.
 Upgrading to v1.7.0
 ===================
 In an attempt to configure Synapse in a privacy preserving way, the default
 behaviours of ``allow_public_rooms_without_auth`` and
 ``allow_public_rooms_over_federation`` have been inverted. This means that by
 default, only authenticated users querying the Client/Server API will be able
 to query the room directory, and relatedly that the server will not share
 room directory information with other servers over federation.
 If your installation does not explicitly set these settings one way or the other
 and you want either setting to be ``true`` then it will necessary to update
 your homeserver configuration file accordingly.
 For more details on the surrounding context see our `explainer
 <https://matrix.org/blog/2019/11/09/avoiding-unwelcome-visitors-on-private-matrix-servers>`_.
 Upgrading to v1.5.0
 ===================
 This release includes a database migration which may take several minutes to
 complete if there are a large number (more than a million or so) of entries in
 the ``devices`` table. This is only likely to a be a problem on very large
 installations.
 Upgrading to v1.4.0
 ===================
-New custom templates
+Config options
--------------------
+--------------
-If you have configured a custom template directory with the
+**Note: Registration by email address or phone number will not work in this release unless
-``email.template_dir`` option, be aware that there are new templates regarding
+some config options are changed from their defaults.**
 registration and threepid management (see below) that must be included.
-* ``registration.html`` and ``registration.txt``
+This is due to Synapse v1.4.0 now defaulting to sending registration and password reset tokens
-* ``registration_success.html`` and ``registration_failure.html``
+itself. This is for security reasons as well as putting less reliance on identity servers.
-* ``add_threepid.html`` and  ``add_threepid.txt``
+However, currently Synapse only supports sending emails, and does not have support for
-* ``add_threepid_failure.html`` and ``add_threepid_success.html``
+phone-based password reset or account registration. If Synapse is configured to handle these on
 its own, phone-based password resets and registration will be disabled. For Synapse to send
 emails, the ``email`` block of the config must be filled out. If not, then password resets and
 registration via email will be disabled entirely.
-Synapse will expect these files to exist inside the configured template
+This release also deprecates the ``email.trust_identity_server_for_password_resets`` option and
-directory, and **will fail to start** if they are absent.
+replaces it with the ``account_threepid_delegates`` dictionary. This option defines whether the
-To view the default templates, see `synapse/res/templates
+homeserver should delegate an external server (typically an `identity server
-<https://github.com/matrix-org/synapse/tree/master/synapse/res/templates>`_.
+<https://matrix.org/docs/spec/identity_service/r0.2.1>`_) to handle sending password reset or
 registration messages via email and SMS.
-3pid verification changes
+If ``email.trust_identity_server_for_password_resets`` is set to ``true``, and
 -------------------------
 **Note: As of this release, users will be unable to add phone numbers or email
 addresses to their accounts, without changes to the Synapse configuration. This
 includes adding an email address during registration.**
 It is possible for a user to associate an email address or phone number
 with their account, for a number of reasons:
 * for use when logging in, as an alternative to the user id.
 * in the case of email, as an alternative contact to help with account recovery.
 * in the case of email, to receive notifications of missed messages.
 Before an email address or phone number can be added to a user's account,
 or before such an address is used to carry out a password-reset, Synapse must
 confirm the operation with the owner of the email address or phone number.
 It does this by sending an email or text giving the user a link or token to confirm
 receipt. This process is known as '3pid verification'. ('3pid', or 'threepid',
 stands for third-party identifier, and we use it to refer to external
 identifiers such as email addresses and phone numbers.)
 Previous versions of Synapse delegated the task of 3pid verification to an
 identity server by default. In most cases this server is ``vector.im`` or
 ``matrix.org``.
 In Synapse 1.4.0, for security and privacy reasons, the homeserver will no
 longer delegate this task to an identity server by default. Instead,
 the server administrator will need to explicitly decide how they would like the
 verification messages to be sent.
 In the medium term, the ``vector.im`` and ``matrix.org`` identity servers will
 disable support for delegated 3pid verification entirely. However, in order to
 ease the transition, they will retain the capability for a limited
 period. Delegated email verification will be disabled on Monday 2nd December
 2019 (giving roughly 2 months notice). Disabling delegated SMS verification
 will follow some time after that once SMS verification support lands in
 Synapse.
 Once delegated 3pid verification support has been disabled in the ``vector.im`` and
 ``matrix.org`` identity servers, all Synapse versions that depend on those
 instances will be unable to verify email and phone numbers through them. There
 are no imminent plans to remove delegated 3pid verification from Sydent
 generally. (Sydent is the identity server project that backs the ``vector.im`` and
 ``matrix.org`` instances).
 Email
 ~~~~~
 Following upgrade, to continue verifying email (e.g. as part of the
 registration process), admins can either:-
 * Configure Synapse to use an email server.
 * Run or choose an identity server which allows delegated email verification
  and delegate to it.
 Configure SMTP in Synapse
 +++++++++++++++++++++++++
 To configure an SMTP server for Synapse, modify the configuration section
 headed ``email``, and be sure to have at least the ``smtp_host, smtp_port``
 and ``notif_from`` fields filled out.
 You may also need to set ``smtp_user``, ``smtp_pass``, and
 ``require_transport_security``.
 See the `sample configuration file <docs/sample_config.yaml>`_ for more details
 on these settings.
 Delegate email to an identity server
 ++++++++++++++++++++++++++++++++++++
 Some admins will wish to continue using email verification as part of the
 registration process, but will not immediately have an appropriate SMTP server
 at hand.
 To this end, we will continue to support email verification delegation via the
 ``vector.im`` and ``matrix.org`` identity servers for two months. Support for
 delegated email verification will be disabled on Monday 2nd December.
 The ``account_threepid_delegates`` dictionary defines whether the homeserver
 should delegate an external server (typically an `identity server
 <https://matrix.org/docs/spec/identity_service/r0.2.1>`_) to handle sending
 confirmation messages via email and SMS.
 So to delegate email verification, in ``homeserver.yaml``, set
 ``account_threepid_delegates.email`` to the base URL of an identity server. For
 example:
 .. code:: yaml
   account_threepid_delegates:
       email: https://example.com     # Delegate email sending to example.com
 Note that ``account_threepid_delegates.email`` replaces the deprecated
 ``email.trust_identity_server_for_password_resets``: if
 ``email.trust_identity_server_for_password_resets`` is set to ``true``, and
 ``account_threepid_delegates.email`` is not set, then the first entry in
-``trusted_third_party_id_servers`` will be used as the
+``trusted_third_party_id_servers`` will be used as the account threepid delegate for email.
-``account_threepid_delegate`` for email. This is to ensure compatibility with
+This is to ensure compatibility with existing Synapse installs that set up external server
-existing Synapse installs that set up external server handling for these tasks
+handling for these tasks before v1.4.0. If ``email.trust_identity_server_for_password_resets``
-before v1.4.0. If ``email.trust_identity_server_for_password_resets`` is
+is ``true`` and no trusted identity server domains are configured, Synapse will throw an error.
 ``true`` and no trusted identity server domains are configured, Synapse will
 report an error and refuse to start.
-If ``email.trust_identity_server_for_password_resets`` is ``false`` or absent
+If ``email.trust_identity_server_for_password_resets`` is ``false`` or absent and a threepid
-and no ``email`` delegate is configured in ``account_threepid_delegates``,
+type in ``account_threepid_delegates`` is not set to a domain, then Synapse will attempt to
-then Synapse will send email verification messages itself, using the configured
+send password reset and registration messages for that type.
 SMTP server (see above).
 that type.
-Phone numbers
+Email templates
-~~~~~~~~~~~~~
+---------------
-Synapse does not support phone-number verification itself, so the only way to
+If you have configured a custom template directory with the ``email.template_dir`` option, be
-maintain the ability for users to add phone numbers to their accounts will be
+aware that there are new templates regarding registration. ``registration.html`` and
-by continuing to delegate phone number verification to the ``matrix.org`` and
+``registration.txt`` have been added and contain the content that is sent to a client upon
-``vector.im`` identity servers (or another identity server that supports SMS
+registering via an email address.
 sending).
-The ``account_threepid_delegates`` dictionary defines whether the homeserver
+``registration_success.html`` and ``registration_failure.html`` are also new HTML templates
-should delegate an external server (typically an `identity server
+that will be shown to the user when they click the link in their registration emai , either
-<https://matrix.org/docs/spec/identity_service/r0.2.1>`_) to handle sending
+showing them a success or failure page (assuming a redirect URL is not configured).
 confirmation messages via email and SMS.
-So to delegate phone number verification, in ``homeserver.yaml``, set
+Synapse will expect these files to exist inside the configured template directory. To view the
-``account_threepid_delegates.msisdn`` to the base URL of an identity
+default templates, see `synapse/res/templates
-server. For example:
+<https://github.com/matrix-org/synapse/tree/master/synapse/res/templates>`_.
 .. code:: yaml
   account_threepid_delegates:
       msisdn: https://example.com     # Delegate sms sending to example.com
 The ``matrix.org`` and ``vector.im`` identity servers will continue to support
 delegated phone number verification via SMS until such time as it is possible
 for admins to configure their servers to perform phone number verification
 directly. More details will follow in a future release.
 Rolling back to v1.3.1
 ----------------------
 If you encounter problems with v1.4.0, it should be possible to roll back to
 v1.3.1, subject to the following:
 * The 'room statistics' engine was heavily reworked in this release (see
  `#5971 <https://github.com/matrix-org/synapse/pull/5971>`_), including
  significant changes to the database schema, which are not easily
  reverted. This will cause the room statistics engine to stop updating when
  you downgrade.
  The room statistics are essentially unused in v1.3.1 (in future versions of
  Synapse, they will be used to populate the room directory), so there should
  be no loss of functionality. However, the statistics engine will write errors
  to the logs, which can be avoided by setting the following in
  `homeserver.yaml`:
  .. code:: yaml
    stats:
      enabled: false
  Don't forget to re-enable it when you upgrade again, in preparation for its
  use in the room directory!
 Upgrading to v1.2.0
 ===================
 Some counter metrics have been renamed, with the old names deprecated. See
-`the metrics documentation <docs/metrics-howto.md#renaming-of-metrics--deprecation-of-old-names-in-12>`_
+`the metrics documentation <docs/metrics-howto.rst#renaming-of-metrics--deprecation-of-old-names-in-12>`_
 for details.
 Upgrading to v1.1.0
@@ -1,39 +0,0 @@
 # Documentation for possible options in this file is at
 # https://rust-lang.github.io/mdBook/format/config.html
 [book]
 title = "Synapse"
 authors = ["The Matrix.org Foundation C.I.C."]
 language = "en"
 multilingual = false
 # The directory that documentation files are stored in
 src = "docs"
 [build]
 # Prevent markdown pages from being automatically generated when they're
 # linked to in SUMMARY.md
 create-missing = false
 [output.html]
 # The URL visitors will be directed to when they try to edit a page
 edit-url-template = "https://github.com/matrix-org/synapse/edit/develop/{path}"
 # Remove the numbers that appear before each item in the sidebar, as they can
 # get quite messy as we nest deeper
 no-section-label = true
 # The source code URL of the repository
 git-repository-url = "https://github.com/matrix-org/synapse"
 # The path that the docs are hosted on
 site-url = "/synapse/"
 # Additional HTML, JS, CSS that's injected into each page of the book.
 # More information available in docs/website_files/README.md
 additional-css = [
    "docs/website_files/table-of-contents.css",
    "docs/website_files/remove-nav-buttons.css",
    "docs/website_files/indent-section-headers.css",
 ]
 additional-js = ["docs/website_files/table-of-contents.js"]
 theme = "docs/website_files/theme"
@@ -0,0 +1 @@
 Don't create broken room when power_level_content_override.users does not contain creator_id.
@@ -0,0 +1 @@
 Lay the groundwork for structured logging output.
@@ -0,0 +1 @@
 Make Opentracing work in worker mode.
@@ -0,0 +1 @@
 Update opentracing docs to use the unified `trace` method.
@@ -0,0 +1 @@
 Add the ability to send registration emails from the homeserver rather than delegating to an identity server.
@@ -0,0 +1 @@
 Retry well-known lookup before the cache expires, giving a grace period where the remote well-known can be down but we still use the old result.
@@ -0,0 +1 @@
 Add an admin API to purge old rooms from the database.
@@ -0,0 +1 @@
 Add retry to well-known lookups if we have recently seen a valid well-known record for the server.
@@ -0,0 +1 @@
 Pass opentracing contexts between servers when transmitting EDUs.
@@ -0,0 +1 @@
 Opentracing for device list updates.
@@ -0,0 +1 @@
 Opentracing for room and e2e keys.
@@ -0,0 +1 @@
 Add a tag recording a request's authenticated entity and corresponding servlet in opentracing.
@@ -0,0 +1 @@
 Fix database index so that different backup versions can have the same sessions.
@@ -0,0 +1 @@
 Add unstable support for MSC2197 (filtered search requests over federation), in order to allow upcoming room directory query performance improvements.
@@ -0,0 +1 @@
 Remove log line for debugging issue #5407.
@@ -0,0 +1 @@
 Fix Synapse looking for config options `password_reset_failure_template` and `password_reset_success_template`, when they are actually `password_reset_template_failure_html`, `password_reset_template_success_html`.
@@ -0,0 +1 @@
 Correctly retry all hosts returned from SRV when we fail to connect.
@@ -0,0 +1 @@
 Add `m.require_identity_server` key to `/versions`'s `unstable_features` section.
@@ -0,0 +1 @@
 Deprecate the `trusted_third_party_id_servers` option.
@@ -0,0 +1 @@
 Replace `trust_identity_server_for_password_resets` config option with `account_threepid_delegates`.
@@ -0,0 +1 @@
 Remove shared secret registration from client/r0/register endpoint. Contributed by Awesome Technologies Innovationslabor GmbH.
@@ -0,0 +1 @@
 Add admin API endpoint for setting whether or not a user is a server administrator.
@@ -0,0 +1 @@
 Fix stack overflow when recovering an appservice which had an outage.
@@ -0,0 +1 @@
 Refactor the Appservice scheduler code.
@@ -0,0 +1 @@
 Compatibility with v2 Identity Service APIs other than /lookup.
@@ -0,0 +1 @@
 Drop some unused tables.
@@ -0,0 +1 @@
 Add missing index on users_in_public_rooms to improve the performance of directory queries.
@@ -0,0 +1 @@
 Add config option to sign remote key query responses with a separate key.
@@ -0,0 +1 @@
 Improve the logging when we have an error when fetching signing keys.
@@ -0,0 +1 @@
 Switch to using the v2 Identity Service `/lookup` API where available, with fallback to v1. (Implements [MSC2134](https://github.com/matrix-org/matrix-doc/pull/2134) plus id_access_token authentication for v2 Identity Service APIs from [MSC2140](https://github.com/matrix-org/matrix-doc/pull/2140)).
@@ -0,0 +1 @@
 Add support for config templating.
@@ -0,0 +1 @@
 Users with the type of "support" or "bot" are no longer required to consent.
@@ -0,0 +1 @@
 Let synctl accept a directory of config files.
@@ -0,0 +1 @@
 Increase max display name size to 256.
@@ -0,0 +1 @@
 Fix error message which referred to public_base_url instead of public_baseurl. Thanks to @aaronraimist for the fix!
@@ -0,0 +1 @@
 Add support for database engine-specific schema deltas, based on file extension.
@@ -0,0 +1 @@
 Add admin API endpoint for getting whether or not a user is a server administrator.
@@ -0,0 +1 @@
 Fix 404 for thumbnail download when `dynamic_thumbnails` is `false` and the thumbnail was dynamically generated. Fix reported by rkfg.
@@ -0,0 +1 @@
 Fix a cache-invalidation bug for worker-based deployments.
@@ -0,0 +1 @@
 Update Buildkite pipeline to use plugins instead of buildkite-agent commands.
@@ -0,0 +1 @@
 Add link in sample config to the logging config schema.
@@ -0,0 +1 @@
 Remove unnecessary parentheses in return statements.
@@ -0,0 +1 @@
 Redact events in the database that have been redacted for a month.
@@ -0,0 +1 @@
 Remove unused jenkins/prepare_sytest.sh file.
@@ -0,0 +1 @@
 Add the ability to send registration emails from the homeserver rather than delegating to an identity server.
@@ -0,0 +1 @@
 Move Buildkite pipeline config to the pipelines repo.
@@ -0,0 +1 @@
 Update INSTALL.md to say that Python 2 is no longer supported.
@@ -0,0 +1 @@
 Remove unnecessary return statements in the codebase which were the result of a regex run.
@@ -0,0 +1 @@
 Remove left-over methods from C/S registration API.
@@ -0,0 +1 @@
 Remove `bind_email` and `bind_msisdn` parameters from /register ala MSC2140.
@@ -0,0 +1 @@
 Fix admin API for listing media in a room not being available with an external media repo.
@@ -0,0 +1 @@
 Fix list media admin API always returning an error.
@@ -0,0 +1 @@
 Replace `trust_identity_server_for_password_resets` config option with `account_threepid_delegates`.
@@ -0,0 +1 @@
 Avoid changing UID/GID if they are already correct.
@@ -0,0 +1 @@
 Fix room and user stats tracking.
@@ -0,0 +1 @@
 Cleanup event auth type initialisation.
@@ -0,0 +1 @@
 Add POST /_matrix/client/r0/account/3pid/unbind endpoint from MSC2140 for unbinding a 3PID from an identity server without removing it from the homeserver user account.
@@ -0,0 +1 @@
 Setting metrics_flags.known_servers to True in the configuration will publish the synapse_federation_known_servers metric over Prometheus. This represents the total number of servers your server knows about (i.e. is in rooms with), including itself.
@@ -0,0 +1 @@
 Include missing opentracing contexts in outbout replication requests.
@@ -0,0 +1 @@
 Add minimum opentracing for client servlets.
@@ -0,0 +1 @@
 Fix sending of EDUs when opentracing is enabled with an empty whitelist.
@@ -0,0 +1 @@
 Check at setup that opentracing is installed if it's enabled in the config.
@@ -0,0 +1 @@
 Trace replication send times.
@@ -0,0 +1 @@
 Fix invalid references to None while opentracing if the log context slips.
@@ -0,0 +1 @@
 Clean up dependency checking at setup.
@@ -0,0 +1 @@
 Fix invalid references to None while opentracing if the log context slips.
@@ -0,0 +1 @@
 Add the ability to send registration emails from the homeserver rather than delegating to an identity server.
@@ -0,0 +1 @@
 Add the ability to send registration emails from the homeserver rather than delegating to an identity server.
@@ -0,0 +1 @@
 Return a M_MISSING_PARAM if `sid` is not provided to `/account/3pid`.
@@ -0,0 +1 @@
 Fix room and user stats tracking.
@@ -0,0 +1 @@
 Add opentracing span over HTTP push processing.
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Travis Ralston	ed12c4ce66	Create 6032.misc	2019-09-12 14:21:22 -06:00
Travis Ralston	ec3b927d28	Update saml.md	2019-09-12 14:19:49 -06:00
Travis Ralston	a633a97c7a	Add developer docs for using SAML without a server	2019-09-12 13:52:10 -06:00
		`@@ -0,0 +1 @@`
							`Don't create broken room when power_level_content_override.users does not contain creator_id.`
		`@@ -0,0 +1 @@`
							`Lay the groundwork for structured logging output.`
		`@@ -0,0 +1 @@`
							Update opentracing docs to use the unified `trace` method.
		`@@ -0,0 +1 @@`
							`Add the ability to send registration emails from the homeserver rather than delegating to an identity server.`
		`@@ -0,0 +1 @@`
							`Retry well-known lookup before the cache expires, giving a grace period where the remote well-known can be down but we still use the old result.`
		`@@ -0,0 +1 @@`
							`Add an admin API to purge old rooms from the database.`
		`@@ -0,0 +1 @@`
							`Add retry to well-known lookups if we have recently seen a valid well-known record for the server.`
		`@@ -0,0 +1 @@`
							`Pass opentracing contexts between servers when transmitting EDUs.`
		`@@ -0,0 +1 @@`
							`Add a tag recording a request's authenticated entity and corresponding servlet in opentracing.`