synapse-admin

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.yourserver.com/synapse-admin and has the following fields:

  • Username: asks for your MXID (@username:yourserver.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.yourserver.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.

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:yourserver.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.yourserver.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:yourserver.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.

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

synapse-admin users’ media page

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) - (it’s not a typo, that’s the actual field name in the synapse-admin v0.8.5) is 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

synapse-admin delete media modal