Synapse Admin service
Synapse Admin: Streamlined Synapse Homeserver Management
Synapse Admin is a valuable tool for efficiently managing your (Matrix) Synapse homeserver. Whether you’re looking to oversee user accounts, clear media, or handle various administrative tasks, Synapse Admin simplifies the process. Explore this guide to discover how to harness its potential.
By default, Synapse Admin is accessible at
https://matrix.your-server.com/synapse-admin. To log in, you’ll find the following fields:
- Username: Input your Matrix ID (
@username:your-server.com), similar to the screenshot below.
- Password: Enter your Matrix user’s password.
- Homeserver URL: This field should auto-populate after you input the correct Matrix ID in the
Usernamefield. If not, you can manually fill it with the value
https://matrix.your-server.com, as shown in the screenshot.
A label displaying the homeserver’s implementation and version (e.g.,
Synapse version 1.62.0) remains hidden initially and becomes visible when the correct value is set in the
Homeserver URL field.
Incorrect or Empty
Typically, this issue arises when you enter only the local part of your Matrix ID in the
Username field. Ensure you enter the full Matrix ID (
@username:your-server.com) instead of just
@username. In specific cases, such as when using a CDN without CORS headers, Synapse Admin may not set the correct value automatically, necessitating manual adjustment.
No Label with Homeserver Version
If you don’t see something like
Synapse version x.xx.x below the
Homeserver URL field, you’ve likely entered an incorrect value in the
Homeserver URL field, or your homeserver might be offline. In most cases, the problem is due to an incorrectly specified
Homeserver URL value.
Network errors may produce different messages, but they typically fall into the following categories:
Homeserver URL: If your
Homeserver URLfield does not contain a value like
https://matrix.your-server.com, this is often the root of the problem.
Username Instead of Matrix ID: Using a username (the local part of your Matrix ID) in the
Usernamefield won’t work. You must input the full Matrix ID (
@username:your-server.com) rather than just
Insufficient Homeserver Admin Permissions: Logging into Synapse Admin and utilizing the Synapse Admin API is only possible with Matrix users who possess homeserver admin permissions.
For registering multiple users simultaneously, Synapse Admin provides a convenient CSV Import feature.
First, prepare a
.csv file with user data for import. The file should have 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 local part of the Matrix ID (e.g.,
- displayname: The user’s human-readable name.
- password: The user’s password in plaintext.
- is_guest: Should this be a guest account?
- admin: Should this be a server admin account?
- deactivated: Should this be a deactivated account?
Next, access the CSV Import page (click on the
CSV IMPORT button in the top right corner, above the users’ table).
By default, this page is hosted at
On this page, configure the following options:
- Conflict strategy: Optional, with the default setting as
Stop on conflict.
- IDs: Mandatory, with the option
Update existing records.
- Simulate only (bottom left corner): Mandatory, with the option unchecked.
After selecting these options, click on
Clearing Old Media
To free up valuable disk space, occasionally, you’ll need to remove old media (uploaded files) from your homeserver. Here’s how:
- Log in to Synapse Admin (see Login ).
- Click on the
Users' Mediabutton in the sidebar.
- Select the
DELETE MEDIAbutton in the top right corner, above the table.
A new modal window opens with two available filters:
- Last access before: A commonly used filter. It removes any media that hasn’t been accessed (uploaded, viewed, or downloaded) since the specified date. For instance, if you want to clear media untouched for the last 7 days, select a date 7 days prior to today (as shown in the screenshot).
- Larger than (in bytes) (Please note that this is not a typo; it’s the actual field name in Synapse Admin v0.8.5). This field is usually not used. However, if specified, it removes media larger than the specified size, including newly uploaded media.