From 526eacb38ee4243afaf5964509f3c49d69eacc65 Mon Sep 17 00:00:00 2001 From: dklimpel <5740567+dklimpel@users.noreply.github.com> Date: Wed, 21 Jul 2021 14:43:41 +0200 Subject: [PATCH 1/6] Add documentation for forward proxy --- docs/SUMMARY.md | 1 + docs/setup/forward_proxy.md | 71 +++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 docs/setup/forward_proxy.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index db4ef1a44e86..096f319fdf81 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -7,6 +7,7 @@ - [Installation](setup/installation.md) - [Using Postgres](postgres.md) - [Configuring a Reverse Proxy](reverse_proxy.md) + - [Configuring a Forward Proxy](setup/forward_proxy.md) - [Configuring a Turn Server](turn-howto.md) - [Delegation](delegate.md) diff --git a/docs/setup/forward_proxy.md b/docs/setup/forward_proxy.md new file mode 100644 index 000000000000..e01f84e8fa90 --- /dev/null +++ b/docs/setup/forward_proxy.md @@ -0,0 +1,71 @@ +# Using a forward proxy with Synapse + +You can use Synapse with a forward or outbound proxy. This will be neccssary +for expamle in corporate environments behind a DMZ (demilitarized zone). +Synapse supports routing outbound HTTP(S) requests via a proxy. Only HTTP(S) +proxy is supported, not SOCKS proxy or anything else. + +## Configure + +The `http_proxy`, `https_proxy`, `no_proxy` environment variable is used to +specify proxy settings. The environment variable is not case sensitive. +- `http_proxy`: Proxy server to use for HTTP requests. +- `https_proxy`: Proxy server to use for HTTPS requests. +- `no_proxy`: Comma-separated list of hosts, IP addresses, or IP ranges in CIDR + format which do not use a proxy and Synapse use a direct connection. + +The proxy setting has the form: `[scheme://][:@][:]` +- Supported scheme is `http://` and `https://`. Default scheme is `http://`. + It is recommended to set a scheme. The default value is for compatibility + reasons. If scheme is set to `https://` the connection uses TLS between + Synapse and proxy. + + **NOTE**: Synapse validates the certificates. If the certificate is not + valid, then the connection is dropped. +- Default port if not given is `1080`. +- Username and password is optional and will be used for authenticate against + proxy. + +**Examples** +- HTTP_PROXY=http://USERNAME:PASSWORD@10.0.1.1:8080/ +- HTTPS_PROXY=http://USERNAME:PASSWORD@proxy.example.com:8080/ +- NO_PROXY=master.hostname.example.com,10.1.0.0/16,172.30.0.0/16 + +**NOTE**: +Blacklisting IP addresses does not work for connections throug a proxy because +the proxy server resolves DNS names and not Synapse. In this case you have to +use your firewall or proxy for blacklisting IP addresses. + +## Connection types + +The proxy will be **used** for: + +- push +- url previews +- phone-home stats +- recaptcha validation +- CAS auth validation + +It will **not be used** for: + +- Application Services +- Identity servers +- Outbound federation +- In worker configurations + - connections from workers to masters + - connections from workers to redis + +## Troubleshooting + +If a proxy server is used with TLS (HTTPS) and no connections are established, +it is most likely due to the proxy's certificates. To test this, the validation +in Synapse can be deactivated. + +**NOTE**: This has an impact on security and is for testing purposes only! + +To deactivate the certificate validation, the following setting must be made in +[homserver.yaml](../usage/configuration/homeserver_sample_config.md). + +```yaml +use_insecure_ssl_client_just_for_testing_do_not_use: true +``` From 71c1d1a921902f7a7f5908e2c8461e38a21e29bc Mon Sep 17 00:00:00 2001 From: dklimpel <5740567+dklimpel@users.noreply.github.com> Date: Wed, 21 Jul 2021 14:48:25 +0200 Subject: [PATCH 2/6] newsfile --- changelog.d/10443.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/10443.doc diff --git a/changelog.d/10443.doc b/changelog.d/10443.doc new file mode 100644 index 000000000000..0dcb284f9f50 --- /dev/null +++ b/changelog.d/10443.doc @@ -0,0 +1 @@ +Add documentation for forward proxy. \ No newline at end of file From 569ac59d888b4f2f05aeb9356a49445fb7d51003 Mon Sep 17 00:00:00 2001 From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> Date: Mon, 26 Jul 2021 19:06:57 +0200 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Patrick Cloke --- docs/SUMMARY.md | 2 +- docs/setup/forward_proxy.md | 31 +++++++++++++++---------------- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 096f319fdf81..51db97fca13e 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -7,7 +7,7 @@ - [Installation](setup/installation.md) - [Using Postgres](postgres.md) - [Configuring a Reverse Proxy](reverse_proxy.md) - - [Configuring a Forward Proxy](setup/forward_proxy.md) + - [Configuring a Forward/Outbound Proxy](setup/forward_proxy.md) - [Configuring a Turn Server](turn-howto.md) - [Delegation](delegate.md) diff --git a/docs/setup/forward_proxy.md b/docs/setup/forward_proxy.md index e01f84e8fa90..0bbe876428e2 100644 --- a/docs/setup/forward_proxy.md +++ b/docs/setup/forward_proxy.md @@ -1,30 +1,29 @@ # Using a forward proxy with Synapse -You can use Synapse with a forward or outbound proxy. This will be neccssary -for expamle in corporate environments behind a DMZ (demilitarized zone). +You can use Synapse with a forward or outbound proxy. An example of when +this is necessary is in corporate environments behind a DMZ (demilitarized zone). Synapse supports routing outbound HTTP(S) requests via a proxy. Only HTTP(S) proxy is supported, not SOCKS proxy or anything else. ## Configure -The `http_proxy`, `https_proxy`, `no_proxy` environment variable is used to +The `http_proxy`, `https_proxy`, `no_proxy` environment variables are used to specify proxy settings. The environment variable is not case sensitive. - `http_proxy`: Proxy server to use for HTTP requests. - `https_proxy`: Proxy server to use for HTTPS requests. - `no_proxy`: Comma-separated list of hosts, IP addresses, or IP ranges in CIDR - format which do not use a proxy and Synapse use a direct connection. + format which should not use the proxy. Synapse will directly connect to these hosts. -The proxy setting has the form: `[scheme://][:@][:]` -- Supported scheme is `http://` and `https://`. Default scheme is `http://`. - It is recommended to set a scheme. The default value is for compatibility - reasons. If scheme is set to `https://` the connection uses TLS between - Synapse and proxy. +The `http_proxy` and `https_proxy` environment variables have the form: `[scheme://][:@][:]` +- Supported schemes are `http://` and `https://`. The default scheme is `http://` + for compatibility reasons; it is recommended to set a scheme. If scheme is set + to `https://` the connection uses TLS between Synapse and the proxy. **NOTE**: Synapse validates the certificates. If the certificate is not valid, then the connection is dropped. - Default port if not given is `1080`. -- Username and password is optional and will be used for authenticate against - proxy. +- Username and password are optional and will be used to authenticate against + the proxy. **Examples** - HTTP_PROXY=http://USERNAME:PASSWORD@10.0.1.1:8080/ @@ -32,9 +31,9 @@ The proxy setting has the form: `[scheme://][:@][: Date: Mon, 26 Jul 2021 21:36:13 +0200 Subject: [PATCH 4/6] update proxy/no proxy list --- docs/setup/forward_proxy.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/setup/forward_proxy.md b/docs/setup/forward_proxy.md index 0bbe876428e2..3c822607dd2d 100644 --- a/docs/setup/forward_proxy.md +++ b/docs/setup/forward_proxy.md @@ -44,6 +44,8 @@ The proxy will be **used** for: - phone-home stats - recaptcha validation - CAS auth validation +- OpenID Connect +- federation (check public_key revocation) It will **not be used** for: @@ -53,6 +55,9 @@ It will **not be used** for: - In worker configurations - connections between workers - connections from workers to Redis +- fetch keys from other servers +- download remote media +- extension modules ## Troubleshooting From e6141894f289704b426378dd37ba56cd843b66f0 Mon Sep 17 00:00:00 2001 From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> Date: Mon, 26 Jul 2021 22:21:02 +0200 Subject: [PATCH 5/6] Update forward_proxy.md --- docs/setup/forward_proxy.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/setup/forward_proxy.md b/docs/setup/forward_proxy.md index 3c822607dd2d..c1c135aa99df 100644 --- a/docs/setup/forward_proxy.md +++ b/docs/setup/forward_proxy.md @@ -57,7 +57,6 @@ It will **not be used** for: - connections from workers to Redis - fetch keys from other servers - download remote media -- extension modules ## Troubleshooting From 80a5c14072a1fdc21702da48e64f831f027f6d85 Mon Sep 17 00:00:00 2001 From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> Date: Wed, 4 Aug 2021 20:28:05 +0200 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Patrick Cloke --- changelog.d/10443.doc | 2 +- docs/setup/forward_proxy.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/changelog.d/10443.doc b/changelog.d/10443.doc index 0dcb284f9f50..3588e5487fe0 100644 --- a/changelog.d/10443.doc +++ b/changelog.d/10443.doc @@ -1 +1 @@ -Add documentation for forward proxy. \ No newline at end of file +Add documentation for configuration a forward proxy. diff --git a/docs/setup/forward_proxy.md b/docs/setup/forward_proxy.md index c1c135aa99df..a0720ab342e7 100644 --- a/docs/setup/forward_proxy.md +++ b/docs/setup/forward_proxy.md @@ -45,7 +45,7 @@ The proxy will be **used** for: - recaptcha validation - CAS auth validation - OpenID Connect -- federation (check public_key revocation) +- Federation (checking public key revocation) It will **not be used** for: @@ -55,8 +55,8 @@ It will **not be used** for: - In worker configurations - connections between workers - connections from workers to Redis -- fetch keys from other servers -- download remote media +- Fetching public keys of other servers +- Downloading remote media ## Troubleshooting