Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Add note to manhole.md about bind_address when using with docker #8526

Merged
merged 6 commits into from
Oct 14, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/8526.doc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Added note about docker in manhole.md regarding which ip address to bind to. Contributed by @Maquis196.
46 changes: 39 additions & 7 deletions docs/manhole.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +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).
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.

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.
```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: ['::1', '127.0.0.1']
type: manhole
```

maquis196 marked this conversation as resolved.
Show resolved Hide resolved
#### Accessing synapse manhole

Then restart synapse, and point an ssh client at port 9000 on localhost, using
the username `matrix`:
Expand Down