the only FOSS-based service offering Matrix chat server hosting
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.
Getting Started
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
Username
field. If not, you can manually fill it with the valuehttps://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.
Common Issues
Incorrect or Empty Homeserver URL
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
or @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 Error
Network errors may produce different messages, but they typically fall into the following categories:
Invalid
Homeserver URL
: If yourHomeserver URL
field does not contain a value likehttps://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
Username
field won’t work. You must input the full Matrix ID (@username:your-server.com
) rather than justusername
or@username
.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.
Bulk Registration
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.,
username
from@username:your-server.com
). - 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 https://matrix.your-server.com/synapse-admin/#/import_users
.
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 IMPORT
.
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' Media
button in the sidebar. - Select the
DELETE MEDIA
button 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.