# 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 uncomment the `manhole` listener configuration in `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:

    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=''>>