synapse-admin service

This page is also available in: Deutsch, Русский

Synapse-admin is a tool you can use to administrate your (Matrix) Synapse homeserver - managing user accounts, deleting media and chat history to reclaim disk space, etc. On this page, you can find how-to instructions for that tool.

synapse-admin users page

Login

By default, synapse-admin is hosted on https://matrix.your-server.com/synapse-admin and has the following fields:

and an initially-hidden “label” with homeserver implementation and version (eg Synapse version 1.62.0 on the screenshot below). That label will be visible only when the correct value is set into the Homeserver URL field.

synapse-admin login page

Common issues

Incorrect or empty Homeserver URL

Usually, that means that you typed only the local part of your MXID in the Username field. You have to enter the full MXID (@username:your-server.com), not just username or @username. In some specific cases, like CDN without CORS headers, synapse-admin may fail to set the correct value automatically and you may need to adjust it manually.

No label with homeserver version

If you don’t see something like Synapse version x.xx.x under the Homeserver URL field, you entered an incorrect value in the Homeserver URL field or your homeserver may be down (in 99% of cases the Homeserver URL value is specified incorrectly).

Network error

You may see different error messages, but all of them can be split into the following groups:

Invalid Homeserver URL

Yes, if your Homeserver URL field doesn’t contain a value like https://matrix.your-server.com, that’s usually the problem

Username instead of MXID

If you enter a username (local part of your MXID) into the Username field, it won’t work. You have to enter the full MXID (@username:your-server.com), not just username or @username.

The user doesn’t have homeserver admin permissions

You can log in into synapse-admin and use the Synapse Admin API (they’re different things) only using matrix users having homeserver admin permissions.

Bulk Registration

To register a lot of users at once, you may use the CSV Import feature of synapse-admin.

First of all, you need to prepare .csv file with the user data you want to import with the following content:

id,displayname,password,is_guest,admin,deactivated
jane.doe,Jane Doe,secretpassword,false,false,false

NOTE: the second line is an example

Next, you need to open the CSV Import page (click on the CSV IMPORT button in the right corner, above the users’ table).

synapse-admin users page highlighted CSV Import

By default, it’s hosted on https://matrix.your-server.com/synapse-admin/#/import_users.

synapse-admin users CSV Import

On that page, you need to select the following options:

After you selected all those options, click on IMPORT

Remove old media

To free up some disk space, you sometimes need to clear old media (uploaded files) on your homeserver.

To do so, after logging in :

synapse-admin users’ media page

A new modal window will open with 2 available filters:

synapse-admin delete media modal