synapse-admin service

🌐 This page is also available in: Deutsch
Non-English support is best-effort. The English version is more complete.

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.

Login

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

• Username: asks for your MXID (@username:your-server.com), like on the screenshot below
• Password: asks for your matrix user’s password
• Homeserver URL: should be filled automatically after you type in the correct MXID into the Username field, if that didn’t happen, you might fill it yourself with the value https://matrix.your-server.com, like on the screenshot below

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.

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

• id - the localpart of the would-be Matrix ID (username from @username:your-server.com)
• displayname - the human-friendly name of the user
• password - user’s password in plaintext
• is_guest - should it be a guest account?
• admin - should it be a server admin account?
• deactivated - should it be a deactivated account?

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

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

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

• Conflict strategy: Stop on conflict (optional, default)
• IDs: Update existing records (mandatory)
• Simulate only (bottom left corner): unchecked (mandatory)

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 :

• Click on the Users' Media button in the sidebar
• Click on the DELETE MEDIA button in the right corner, above the table

A new modal window will open with 2 available filters:

• last access before - the common filter. Any media that was last accessed (uploaded/viewed/downloaded) before the specified date will be removed. For example, if you want to remove media that was not touched at all in the last 7 days, select the date 7 days before today (like on the screenshot below)
• Larger then (in bytes) - (this is not a typo, that’s the actual field name in the synapse-admin v0.8.5) it’s a field that is usually not used. If specified, any media larger than the specified size that size will be removed, including just uploaded media