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.
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 uncomment the
manhole listener configuration in
homeserver.yaml. The configuration is slightly different if you're using docker.
If you are using Docker, set
['0.0.0.0'] as shown:
listeners: - port: 9000 bind_addresses: ['0.0.0.0'] type: manhole
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
If you are not using docker, set
['::1', '127.0.0.1'] as shown.
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
The following config options are available:
username- The username for the manhole (defaults to
password- The password for the manhole (defaults to
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)
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
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
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=''>>