From 1cf4a68108a77607c8aff1ee8f6216df251c4e7e Mon Sep 17 00:00:00 2001 From: Christopher May-Townsend Date: Wed, 14 Oct 2020 15:28:59 +0100 Subject: [PATCH] Add note to manhole.md about bind_address when using with docker (#8526) Signed-off-by: Christopher May-Townsend --- changelog.d/8526.doc | 1 + docs/manhole.md | 46 +++++++++++++++++++++++++++++++++++++------- 2 files changed, 40 insertions(+), 7 deletions(-) create mode 100644 changelog.d/8526.doc diff --git a/changelog.d/8526.doc b/changelog.d/8526.doc new file mode 100644 index 0000000000..cbf48680c1 --- /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. diff --git a/docs/manhole.md b/docs/manhole.md index 75b6ae40e0..37d1d7823c 100644 --- a/docs/manhole.md +++ b/docs/manhole.md @@ -5,8 +5,45 @@ 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: ['0.0.0.0'] + type: manhole +``` + +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. + +```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: @@ -15,12 +52,7 @@ listeners: type: manhole ``` -(`bind_addresses` in the above is important: it ensures that access to the -manhole is only possible for local users). - -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`: