From a4da2a741238bfa185661468a39c0366176153a4 Mon Sep 17 00:00:00 2001 From: maquis196 Date: Mon, 12 Oct 2020 22:51:30 +0100 Subject: [PATCH 1/6] matrix-org/synapse#8508 - Add note to manhole.md about bind_addresses when using docker --- docs/manhole.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/manhole.md b/docs/manhole.md index 75b6ae40e0cb..637723cb5744 100644 --- a/docs/manhole.md +++ b/docs/manhole.md @@ -18,6 +18,9 @@ listeners: (`bind_addresses` in the above is important: it ensures that access to the manhole is only possible for local users). +**Docker Note** +If you are using docker, you will need to use 0.0.0.0 for the bind_addresses above. This is so docker can forward traffic to synapse. + Note that this will give administrative access to synapse to **all users** with shell access to the server. It should therefore **not** be enabled in environments where untrusted users have shell access. From c63c67bc6ccec7f10c1f849e5fc59951717ce3e3 Mon Sep 17 00:00:00 2001 From: maquis196 Date: Mon, 12 Oct 2020 22:56:02 +0100 Subject: [PATCH 2/6] Added changelog entry and signed off in this commit. Signed-off-by: Christopher May-Townsend --- changelog.d/8526.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/8526.doc diff --git a/changelog.d/8526.doc b/changelog.d/8526.doc new file mode 100644 index 000000000000..cbf48680c12f --- /dev/null +++ b/changelog.d/8526.doc @@ -0,0 +1 @@ +Added note about docker in manhole.md regarding which ip address to bind to. Contributed by @Maquis196. From 8d3ce81de05c5692172d6d03db2baf74a78af604 Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 13 Oct 2020 10:32:10 +0100 Subject: [PATCH 3/6] Update manhole.md to include a working docker example --- docs/manhole.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/manhole.md b/docs/manhole.md index 637723cb5744..9f1f5d46e1b0 100644 --- a/docs/manhole.md +++ b/docs/manhole.md @@ -19,7 +19,14 @@ listeners: manhole is only possible for local users). **Docker Note** -If you are using docker, you will need to use 0.0.0.0 for the bind_addresses above. This is so docker can forward traffic to synapse. +If you are using docker, please ensure you use the following example; + +```yaml +listeners: + - port: 9000 + bind_addresses: ['0.0.0.0'] + type: manhole +``` Note that this will give administrative access to synapse to **all users** with shell access to the server. It should therefore **not** be enabled in From 1c716c5ac6ab128656e54202d35593d9fcfbcc97 Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 13 Oct 2020 11:26:43 +0100 Subject: [PATCH 4/6] latest changes to the documentation --- docs/manhole.md | 42 ++++++++++++++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/docs/manhole.md b/docs/manhole.md index 9f1f5d46e1b0..4729840fd11d 100644 --- a/docs/manhole.md +++ b/docs/manhole.md @@ -5,32 +5,54 @@ The "manhole" allows server administrators to access a Python shell on a running Synapse installation. This is a very powerful mechanism for administration and debugging. +**_Security Warning_** + +Note that this will give administrative access to synapse to **all users** with +shell access to the server. It should therefore **not** be enabled in +environments where untrusted users have shell access. + +*** + To enable it, first uncomment the `manhole` listener configuration in -`homeserver.yaml`: +`homeserver.yaml`. The configuration is slightly different if you're using docker. + +#### Docker config + +If you are using Docker, set `bind_addresses` to `['0.0.0.0']` as shown: ```yaml listeners: - port: 9000 - bind_addresses: ['::1', '127.0.0.1'] + bind_addresses: ['0.0.0.0'] type: manhole ``` -(`bind_addresses` in the above is important: it ensures that access to the -manhole is only possible for local users). +You will then need to change the docker command to the following to include the +manhole port forwarding. The `-p 127.0.0.1:9000:9000` below is important: it +ensures that access to the `manhole` is only possible for local users). -**Docker Note** -If you are using docker, please ensure you use the following example; +```bash +docker run -d --name synapse \ + --mount type=volume,src=synapse-data,dst=/data \ + -p 8008:8008 \ + -p 127.0.0.1:9000:9000 \ + matrixdotorg/synapse:latest +``` + +#### Native config + +If you are not using docker, set `bind_addresses` to `['::1', '127.0.0.1']` as shown. +The `bind_addresses` in the example below is important: it ensures that access to the +`manhole` is only possible for local users). ```yaml listeners: - port: 9000 - bind_addresses: ['0.0.0.0'] + bind_addresses: ['::1', '127.0.0.1'] type: manhole ``` -Note that this will give administrative access to synapse to **all users** with -shell access to the server. It should therefore **not** be enabled in -environments where untrusted users have shell access. +#### Accessing synapse manhole Then restart synapse, and point an ssh client at port 9000 on localhost, using the username `matrix`: From a8155887edb31561b3bdd53f0fedda5946bcbcfc Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 13 Oct 2020 12:10:33 +0100 Subject: [PATCH 5/6] cosmetic changes --- docs/manhole.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manhole.md b/docs/manhole.md index 4729840fd11d..60d8eafcc8b7 100644 --- a/docs/manhole.md +++ b/docs/manhole.md @@ -28,8 +28,8 @@ listeners: ``` You will then need to change the docker command to the following to include the -manhole port forwarding. The `-p 127.0.0.1:9000:9000` below is important: it -ensures that access to the `manhole` is only possible for local users). +`manhole` port forwarding. The `-p 127.0.0.1:9000:9000` below is important: it +ensures that access to the `manhole` is only possible for local users. ```bash docker run -d --name synapse \ From 234c25667799d3e8f3ee0a2067a15a1e79e17221 Mon Sep 17 00:00:00 2001 From: Christopher May-Townsend Date: Tue, 13 Oct 2020 18:09:21 +0100 Subject: [PATCH 6/6] Update docs/manhole.md Co-authored-by: Jonathan de Jong --- docs/manhole.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manhole.md b/docs/manhole.md index 60d8eafcc8b7..37d1d7823c00 100644 --- a/docs/manhole.md +++ b/docs/manhole.md @@ -27,7 +27,7 @@ listeners: type: manhole ``` -You will then need to change the docker command to the following to include the +When using `docker run` to start the server, you will then need to change the command to the following to include the `manhole` port forwarding. The `-p 127.0.0.1:9000:9000` below is important: it ensures that access to the `manhole` is only possible for local users.