- About
- Prerequisites
- Installation
- Configuration
- Usage
- Update
- Implementation Status / Commands List
- Get in Touch
- Contributing
A CLI tool to help admins of Matrix-Synapse homeservers conveniently issue commands available via its Admin API.
- Python 3.6+
- a running Synapse instance
- an admin-enabled user on the instance
- the admin user's access token
synadm
is designed to run either directly on the host running the Synapse instance or on a remote machine able to access Synapse's API port. Synapse's default Admin API endpoint address usually is http://localhost:8008/_synapse/admin or https://localhost:8448/_synapse/admin.
pip3 install synadm
python3 --version
should show at least v3.6.x
git clone https://github.com/joj0/synadm
This will install synadm
and all dependent Python packages to your system's global Python site-packages directory:
cd synadm
sudo pip install .
Note: If you get an import error for setuptools, make sure the package is installed. Debian based systems: sudo apt install python3-setuptools
, RedHat based: sudo yum install python3-setuptools
synadm
should now run fine without having to add a path in front of it:
synadm -h
Note: Usually setuptools installs a command wrapper to /usr/local/bin/synadm
, but that depends on your system.
Note: In case you don't want synadm
to be installed to a global system directory, you can find an alternative way of installing in the contribution docs.
Note: synadm is multi-user aware - it stores its configuration inside the executing user's home directory. See chapter configuration.
To find out your admin user's token in Element-Web: Login as this user - "Click User Avatar" - "All Settings" - "Help & About" - Scroll down - "Advanced" - "Access Token"
Or use synadm to fetch a token already. Use the fully qualified Matrix ID of the admin user:
synadm matrix login @admin_username:yourdomain.org
Password:
If you issue this command in a fresh synadm
installation, the configurator will launch anyway.
- Answer the questions.
- Set token to "invalid" at first, to convience
synadm
to launch thematrix login
command (otherwise you'd get a "Configuration incomplete" error). - After successfully entering your admin password you will be presented a token which you can finally set by re-launching the configurator as described below.
synadm
asks for necessary configuration items on first launch automatically. Also whenever new mandatory configuration items where added (eg after an update), the user will be prompted for missing items automatically.
Configuration can be changed any time by launching the configurator directly:
synadm config
Configuration will be saved in ~/.config/synadm.yaml
Note: Be aware that once you configured synadm
, your admin user's token is saved in the configuration file. On Posix compatible systems permissions are set to mode 0600, on other OS's it is your responsibilty to change permissions accordingly.
To use synadm
with Synapse homeservers that were installed using matrix-docker-ansible-deploy you have two options.
Access the Synapse Admin API's "via the public endpoint" similar to a Matrix client.
- In vars.yaml set
matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true
. - The API's are accessible on the Client-Server API port, at
https://matrix.DOMAIN
. - Install
synadm
on your Docker host or on a separate machine. - Configure
synadm
to access athttps://matrix.DOMAIN:443/_synapse/admin
Alternatively, you can access the API's on the container network matrix
.
- Synapse is accessible via the hostname
matrix-synapse
resolved by the internal Docker DNS server. - The containers are connected internally via a network named
matrix
by default. - Start a container on that same network and install
synadm
into it. - Configure
synadm
to access athttp://matrix-synapse:8008/_synapse/admin
(http here, not https).
Find some more details about the topic in this issue post on the matrix-docker-ansible-deploy repo.
Note that currently synadm
is using a part of the Server-Server (Federation) API (keys/v2/server
) to retrieve "its own homeserver name". This affects some of the media
management commands. By default and also as the Matrix spec recommends, this API is not accessible via the Client-Server API port. We are working on a better solution to retrieve the own servername but as a workaround the key
API's can be exposed by setting matrix_synapse_http_listener_resource_names: ["client","keys"]
in vars.yaml.
Find more details about the topic here.
Use the online help of the main command:
synadm -h
and of the available subcommands:
synadm version -h
synadm user -h
synadm room -h
You even can spare the -h
option, synadm
will show some abbreviated help for the executed subcommand anyway. For example:
synadm user
or
synadm user details
will show essential help for the particular subcommand right away.
Note: A list of currently available commands is found in chapter implementation status / commands list as well as in the following chapter.
A detailed Command Line Reference can be found in synadm's
readthedocs documentation.
Examples of how synadm
can be used in shell scripts and oneliners is
provided in the
Scripting Examples
docs chapter.
pip3 install synadm --upgrade
To update synadm
to the latest development state, just update your git repo and reinstall:
cd synadm
git pull
pip install .
Note: If you installed it to a Python venv, activate it.
Note: If you installed it in editable mode (or for development), you can spare the pip install .
command - just git pull
and you're done.
Follow this link to the official Synapse Admin API docs - direct links to the specific API documentation pages are provided in the list below.
Note: Most commands have several optional arguments available. Put -h after any of the below listed commands to view them or have a look at the Command Line Reference.
- Account Validity
- Delete Group (delete community)
- Event Reports
- Media Admin
-
media list -r <room id>
-
media list -u <user id>
(alias ofuser media <user id>
) -
media quarantine -s <server name> -i <media id>
-
media quarantine -r <room id>
-
media quarantine -u <room id>
-
media protect <media id>
-
media delete -s <server name> -i <media id>
-
media delete -s <server name> --before <date> --size 1024
-
media purge --before <date>
(purge remote media API)
-
- Purge History
-
history purge <room id>
-
history purge-status <purge id>
-
-
Purge Rooms(DEPRECATED, covered byroom delete
) - Register Users
- Manipulate Room Membership
-
room join
-
- Rooms
-
room list
-
room details <room id>
-
room members <room id>
-
room delete <room id>
-
room make-admin <room id> <user id>
-
room state <room id>
- Additional commands and aliases around room management
-
room search <search-term>
(alias ofroom list -n <search-term>
) -
room resolve <room alias>
-
room power-levels
-
room block
-
room block-status
-
-
- Server Notices
-
Shutdown Room(DEPRECATED, covered byroom delete
) - Statistics
-
synadm media user-stats
-
synadm room largest
-
- Users
-
user details <user id>
-
user modify <user id>
(also used for user creation) -
user list
-
user deactivate <user id>
(including GDPR erase) -
user password <user id>
-
user membership <user id>
-
user whois <user id>
-
user shadow-ban <user id>
-
user media -u <user id>
(also available asmedia list -u <user id>
) -
user login <user id>
- Additional commands and aliases around user management
-
user search <search-term>
(shortcut touser list -d -g -n <search-term>
) -
user create <user id>
(alias ofuser modify ...
) -
user prune-devices <user id>
-
-
- Server Version
-
version
-
- Registration Tokens
-
regtok list
-
regtok details <registration token>
-
regtok new
-
regtok update <registration token>
-
regtok delete <registration token>
-
If you need advice on using synadm, have a feature idea or would like to discuss anything else around synadm
, get in touch via Matrix!
We are hanging around in the official support room for Synapse, #synapse:matrix.org. Usually you'll find synadm
users there that might answer your questions already. If not, mentioning synadm
will ping us with the help of Element's keyword notify feature and we'll try to get in touch.
The most direct way to reach synadm maintainers as well as seasoned users and Synapse admins is by joining #synadm:peek-a-boo.at.
If you are sure you've found a bug that was not already reported, certainly directly opening an issue on GitHub is a valid option too. If unsure, ask in #synadm:peek-a-boo.at first.
First of all, thanks for your interest in contributing to synadm
! We appreciate any help, no matter if you are a programmer or a user. Both groups can do valuable things for the synadm
project. We love providing a useful tool to fellow Synapse sysadmins but rely on contribution from the Synapse and Matrix community to keep synadm
useful, current and stable.
Please review the contributing docs for guidelines and help around the topic!