+ +

Using the synapse manhole

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.

Configuring the manhole

To enable it, first add the manhole listener configuration in your +homeserver.yaml. You can find information on how to do that +in the configuration manual. +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:

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.

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).

listeners:
+  - port: 9000
+    bind_addresses: ['::1', '127.0.0.1']
+    type: manhole
+

Security settings

The following config options are available:

username - The username for the manhole (defaults to matrix)
password - The password for the manhole (defaults to rabbithole)
ssh_priv_key - The path to a private SSH key (defaults to a hardcoded value)
ssh_pub_key - The path to a public SSH key (defaults to a hardcoded value)

For example:

manhole_settings:
+  username: manhole
+  password: mypassword
+  ssh_priv_key: "/home/synapse/manhole_keys/id_rsa"
+  ssh_pub_key: "/home/synapse/manhole_keys/id_rsa.pub"
+

Accessing synapse manhole

Then restart synapse, and point an ssh client at port 9000 on localhost, using +the username and password configured in homeserver.yaml - with the default +configuration, this would be:

ssh -p9000 matrix@localhost
+

Then enter the password when prompted (the default is rabbithole).

This gives a Python REPL in which hs gives access to the +synapse.server.HomeServer object - which in turn gives access to many other +parts of the process.

Note that, prior to Synapse 1.41, any call which returns a coroutine will need to be wrapped in ensureDeferred.

As a simple example, retrieving an event from the database:

>>> from twisted.internet import defer
+>>> defer.ensureDeferred(hs.get_datastores().main.get_event('$1416420717069yeQaw:matrix.org'))
+<Deferred at 0x7ff253fc6998 current result: <FrozenEvent event_id='$1416420717069yeQaw:matrix.org', type='m.room.create', state_key=''>>
+

+ +