New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for ACME setup #4547

Merged
merged 11 commits into from Feb 1, 2019

Conversation

Projects
None yet
3 participants
@anoadragon453
Copy link
Member

anoadragon453 commented Feb 1, 2019

Add documentation for ACME certificate provisioning in Synapse v0.99.0+.

@codecov-io

This comment has been minimized.

Copy link

codecov-io commented Feb 1, 2019

Codecov Report

Merging #4547 into release-v0.99.0 will decrease coverage by 0.01%.
The diff coverage is n/a.

@@                Coverage Diff                 @@
##           release-v0.99.0   #4547      +/-   ##
==================================================
- Coverage            74.91%   74.9%   -0.02%     
==================================================
  Files                  338     338              
  Lines                34495   34495              
  Branches              5619    5619              
==================================================
- Hits                 25843   25839       -4     
- Misses                7069    7074       +5     
+ Partials              1583    1582       -1
README.rst Outdated
automatically for you for free** through `Let's Encrypt
<https://letsencrypt.org/>`_ if you tell it to.

Note: Synapse does not currently hot-renew Let's Encrypt certificates for

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

meh, let's leave this out

README.rst Outdated

Synapse requires valid TLS certificates for communication between servers
(port ``8448`` by default) in addition to those that are client-facing (port
``443``). Synapse **will provision server-to-server certificates

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

we should mention that they can be the same cert if the server_name is the same as the hostname that the client connects to.

README.rst Outdated
**Using a reverse proxy**

A reverse proxy such as Apache or Nginx allows a single process (the web
server) to listen on port 80 and redirect traffic to the appropriate program

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

s/redirect/proxy/

README.rst Outdated
not being used for any other purpose then all that is necessary is the
following:

Install ``authbind``::

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member
Suggested change Beta
Install ``authbind``::
Install ``authbind``. For example, on Debian/Ubuntu::
README.rst Outdated
# authbind syntax. don't start Synapse yet
authbind --deep <synapse start command>

If using the `Systemd`_ service file above, you can change the following line

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

there is no systemd file; need to change this to use synctl

README.rst Outdated
certificate, but please be aware that a valid certificate will be required in
Synapse v1.0.

If you would like to do initial testing with a client without having to setup

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

I don't think this is limited to initial testing?

README.rst Outdated
the default 8448. However, if you are thinking of using a reverse-proxy on the
federation port, which is not recommended, be sure to read
`Reverse-proxying the federation port`_ first.)
the default 8448.

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member
Suggested change Beta
the default 8448.
the default 8448.)
README.rst Outdated
``Certificates[0].SHA256Fingerprint`` (the fingerprint of the certificate
presented by your reverse-proxy) matches ``Keys.tls_fingerprints[0].sha256``
(the fingerprint of the certificate Synapse is using).
Please see `ACME setup`_ for details on reverse-proxying the federation port.

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

the acme setup section doesn't say anything about reverse-proxying port 8448. Suggest removing this sentence.

@anoadragon453 anoadragon453 force-pushed the anoa/acme_docs branch from 98ea34c to 09ca6e7 Feb 1, 2019

@anoadragon453 anoadragon453 changed the base branch from develop to release-v0.99.0 Feb 1, 2019

@anoadragon453 anoadragon453 force-pushed the anoa/acme_docs branch from 09ca6e7 to 7f914a2 Feb 1, 2019

anoadragon453 added some commits Feb 1, 2019

Show resolved Hide resolved README.rst Outdated
Show resolved Hide resolved README.rst Outdated
README.rst Outdated

authbind --deep <synapse start command>

If you would like to use your own certificates, you can do so by

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

can we take this out of the acme>authbind section? maybe put it above 'ACME setup' ?

README.rst Outdated
If you would like to use your own certificates, you can do so by
changing ``tls_certificate_path`` and ``tls_private_key_path`` in
``homeserver.yaml``; alternatively, you can use a reverse-proxy, but be sure
to read `Using a reverse proxy with Synapse`_ when doing so. Apart from port

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

I don't think there's anything terribly relevant in the "Using a reverse proxy" section; I'd omit the link.

README.rst Outdated
changing ``tls_certificate_path`` and ``tls_private_key_path`` in
``homeserver.yaml``; alternatively, you can use a reverse-proxy, but be sure
to read `Using a reverse proxy with Synapse`_ when doing so. Apart from port
8448 using TLS, both ports are the same in the default configuration.

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

which ports?

This comment has been minimized.

@anoadragon453

anoadragon453 Feb 1, 2019

Author Member

I'm not sure what this is talking about. Tempted to just take out the line.

README.rst Outdated
8448 for server-server connections. All the Matrix endpoints begin ``/_matrix``,
so an example nginx configuration might look like::
The recommended setup is therefore to configure your reverse-proxy on port
443 to port 8008 of synapse for client connections, and port 8448 for

This comment has been minimized.

@richvdh

richvdh Feb 1, 2019

Member

this makes no sense.

I think the recommendation (if you're going to use a reverse-proxy) should be:

  • set no_tls: True and remove the tls listeners from the synapse config
  • have reverse proxy listen on both 443 and 8448, and forward both to port 8008.

However, this is starting to all get out of scope. For now I suggest: you remove this paragraph and just say "An example nginx configuration for forwarding client connections to synapse is::"

@anoadragon453 anoadragon453 requested review from matrix-org/synapse-core and removed request for matrix-org/synapse-core Feb 1, 2019

richvdh and others added some commits Feb 1, 2019

Update README.rst
Co-Authored-By: anoadragon453 <1342360+anoadragon453@users.noreply.github.com>
Update README.rst
Co-Authored-By: anoadragon453 <1342360+anoadragon453@users.noreply.github.com>

@anoadragon453 anoadragon453 requested a review from matrix-org/synapse-core Feb 1, 2019

@anoadragon453 anoadragon453 merged commit 142b2cd into release-v0.99.0 Feb 1, 2019

0 of 5 checks passed

ci/circleci: sytestpy2merged Your tests failed on CircleCI
Details
ci/circleci: sytestpy2postgresmerged Your tests failed on CircleCI
Details
ci/circleci: sytestpy3merged Your tests failed on CircleCI
Details
ci/circleci: sytestpy3postgresmerged Your tests failed on CircleCI
Details
continuous-integration/travis-ci/pr The Travis CI build is in progress
Details

@anoadragon453 anoadragon453 deleted the anoa/acme_docs branch Feb 1, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment