Getting Started#

Installation#

synadm can run either on the server running Synapse (recommended), or off the Synapse server (requires additional external configuration). It functions on Linux and macOS. If running synadm outside of the Synapse server, this will change how Synapse and reverse proxies are configured.

There are multiple ways to install synadm:

Using pipx
From your distribution’s package manager

pipx method (recommended)#

To install synadm, we recommend using pipx to install it from PyPI on your Synapse server:

pipx install synadm

Updating is not much different, just a different command:

pipx upgrade synadm

The easiest way to install pipx is from your Linux distribution’s package manager (or homebrew on macOS).

Distribution packages method#

You can alternatively also install synadm directly from your Linux distribution’s repositories, if a package exists. The disadvantage is that they may be a couple releases behind, even for rolling release distributions, but differences won’t be much.

You can click the list to open Repology to also see distributions which are out of support. Anything older than 0.44 is colored extremely red because it is very outdated (2+ years old), and is missing a significant amount of features.

How to install a package depends on your distribution. We don’t have all the commands documented here.

Configuring synadm#

Now that synadm is installed, here’s the overview:

(Optional, not documented here) Creating a dedicated admin account
Run synadm config, but typing anything for the “user token”
Run synadm matrix login <USER_ID> to get a token
Run synadm config again but adding a usable token
Test things work by running synadm version or some other command

Running synadm config before logging in is required, because synadm automatically launches the configuration process if it’s not completely configured, even for the login command (this is known under issue #141).

You can alternatively get an access token by logging into an admin account using Element/SchildiChat, and grabbing the access in the “Help & About” section of settings.

Detailed walk through#

Here’s the full setup process with details and terminal output:

Run synadm config and configure it.

Here’s an example run through in v0.49 with a new config:
Example synadm config run#
```
 $ synadm config
 ERROR [Errno 2] No such file or directory: '/home/username/.config/synadm.yaml' while reading configuration file
 ERROR Config entry missing: user,
 Running configurator...
 Synapse admin user name []: @synapse_admin_api_user:example.com
 Synapse admin user token [NOT SET]:
 Synapse protocol (http, unix) [http]:
 Synapse base URL (or path to socket) [http://localhost:8008]: http://localhost:8448
 Synapse Admin API path [/_synapse/admin]:
 Matrix API path [/_matrix]:
 Default output format (yaml, json, minified, human, pprint): human
 Default http timeout [30]: 600
 Homeserver name ("auto-retrieval" or the domain part in your MXID) [auto-retrieval]: example.com
 Verify certificate [True]:
 Server discovery mode (used with homeserver name auto-retrieval) (well-known, dns) [well-known]:
 Restricting access to config file to user only.
```
When asked for the “Synapse admin user token”, keymash on the keyboard and press enter, you’ll retrieve a valid token later. If you do have a valid token, you can input the token instead. Currently, anything you type/paste will be invisible with no feedback, not even redacted characters.

With “Synapse protocol” set to http, “Synapse base URL” must be prefixed with http:// or https://. Otherwise with “Synapse protocol” set to unix, the “Synapse base URL” becomes the absolute path to the unix socket. This should only be used if Synapse is configured to listen on a unix socket, and you wish to interface directly with Synapse.

“Homeserver name” must be the domain name after the colon in your Matrix User ID (MXID). You can set it to auto-retrieval for synadm to figure that out for you, but it’s best if you set this value manually. This is however only used with Media Quarantine/Unquarantine and Local Media Deletion, but those will not function without the correct homeserver name.
Run synadm matrix login <USER_ID> to get a token.

If at this stage synadm seems to launching the configuration, enter anything for “Synapse admin user token”, it does not matter for now.

You do need to specify the MXID again on the command line. After running the command, you’ll be asked for the password, then you’ll get a token from Synapse if the login is successful.
Example synadm matrix login run#
```
 $ synadm matrix login @synapse_admin_api_user:example.com
 Password:
 user_id       @synapse_admin_api_user:example.com
 access_token  syt_Yg_mjSzQDosTiKyLoLiFjIh_4F8t0w
 home_server   example.com
 device_id     YSQKGHVGHG
 well_known    {'m.homeserver': {'base_url': 'http://example.com/'}}
```
Copy the value after access_token, starting with syt_ followed by random characters. Make sure to keep this value a secret, because this is the token for the Matrix account that presumably has admin privileges, which can do a lot of things.

This command only works with direct password logins, and not SSO logins. Use Element/SchildiChat to login and take access token from settings (within the “Advanced & Help” section in settings) if you cannot use a direct password login.
Run synadm config again to add the token to the configuration.

Your configuration is not overwritten when you run synadm config with an existing config. You can press enter to use configured values.

If you didn’t input a valid token earlier (because you’re logging in), you will need to run it again and then paste the token.

See example syandm config run for how synadm config looks like again. Remember that synadm config will not give any visual typing feedback at all, not even redacted characters.

Note: The access token is written in the configuration (at ~/.config/synadm.yml), stored in plain-text, and guarded purely through filesystem permissions, which is not perfectly secure. synadm does not automatically adjust permissions to be unreadable for anyone other than the user on operating systems not considered “posix” by Python.

The access token being stored in plain text is kind a moot point for synadm users using it on the same server that’s also running Synapse, because Synapse stores access tokens directly in the database and more critical things like the signing keys (See issue #189). This will be different if you’re using synadm on your laptop/desktop, accessing your Synapse remotely, which becomes less of a moot point.

Run synadm version to see if it works

synadm version is a command that fetches the currently running Synapse version, using the Admin API
Example synadm version output#
```
 $ synadm version
 server_version  1.139.2
```
If this doesn’t work, check the following things:
- Does the account you’re using have Admin API privileges? See how to make an account become a Synapse server admin.

Using synadm#

You can now run synadm and do various API calls and stuff to administrate your Synapse homeserver.

The rule of thumb of using synadm is: add --help to commands if you’re not sure what arguments to pass, or what commands exist.

All commands have some sort of help text, accessible with --help. The documentation on this site is mostly a mirror of that, at least within Command Line Reference.

synadm commands can be structured differently. If you know your way around Synapse’s Admin API documentation but don’t know which command that correlates to, API to CLI Mapping lists the correlations.

You can also use synadm as part of shell scripts. We have some surface information at Scripting Examples.

We don’t recommend importing synadm into Python scripts however, as that use case is currently poorly supported. We suggest running synadm like a program, even for Python scripts.

Troubleshooting#

Is Synapse reachable over the configured URL? Can you curl it, and the API endpoints?
Does the account you’re using have Admin API privileges? See how to make an account become a Synapse server admin.
Are you using Media Workers, and are media specific commands failing? synadm currently does not support Media Workers. A workaround is making your reverse proxy to the media workers and the main Synapse instance, directing requests to the right thing based on endpoints. We currently don’t have documentation on how to configure your reverse proxy, but the Admin API endpoints handled by the media worker is in Synapse’s docs.

Getting help#

If you’re still scratching your head confused, you can join our Matrix room at #synadm:peek-a-boo.at to ask synadm questions. We currently don’t have other platforms available.

The synadm room is separate from the Synapse room at #synapse:matrix.org. If your homeserver is broken, you may get better help there. Note that the Synapse room may be difficult to join on resource limited Synapse homeservers, and will generally take at least a few minutes.

synadm also supports the --verbose or -v argument, placed like this: synadm -v subcommand. This is incorrect: synadm subcommand -v, the verbose argument must be place immediately after synadm and before any subcommands.

Repeating the -v argument means more verbose log levels, the first enabling INFO, and the second enabling DEBUG, and more. Be careful when sharing logs if you use synadm -vvv subcommand, as your token is certainly exposed beyond the DEBUG level.