Command line admin tool for Synapse (Matrix reference homeserver)
Project description
synadm - Matrix Synapse admin CLI
- About
- Prerequisites
- Installation
- Configuration
- Usage
- Update
- Implementation status / commands list
- Get in touch / feedback / support
- Contribution
About
A CLI tool to help admins of Matrix Synapse homeservers conveniently issue commands available via its admin API's (https://github.com/matrix-org/synapse/tree/master/docs/admin_api)
Prerequisites
- 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.
Installation
The installation process is tested on an Ubuntu Bionic (18.04) machine but should work an any more or less current Linux machine:
1. Check Python version
python3 --version
should show at least v3.6.x
2. Clone repo:
git clone https://github.com/joj0/synadm
3. Install package globally
This will install synadm
and all dependent Python packages to your system's global Python site-packages directory:
cd synadm
sudo python3 setup.py 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
4. Run
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 see chapter install to virtual environment.
Note: synadm is mutli-user aware - it stores it's configuration inside the executing user's home directory. See chapter configuration.
Configuration
synadm
asks for necessary configuration items on first launch automatically. Also whenever new 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: 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"
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.
Usage
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 help for the executed subcommand anyway. For example:
synadm user
or
synadm user details
will show help for the particular subcommand right away.
Note: A complete list of currently available commands is found in in chapter implementation status / commands list
Update
To update synadm
to the latest development state, just update your git repo and reinstall:
cd synadm
git pull
python3 setup.py install
Note: If you installed to a Python venv, first load it as described in install to virtual environment.
Note: If you installed in development mode you can spare the python3 setup.py install
command - just git pull
any you're done.
Implementation status / commands list
Synapse Admin API docs main page - 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.
- Account validity API
- Delete group API (delete community)
- Event reports API
- Media admin API
-
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 API
-
history purge <room id>
-
history purge-status <purge id>
-
-
Purge room API(DEPRECATED, covered byroom delete
) - Register API
- Room membership API
-
room join
-
- Rooms API
-
room list
-
room search <search-term>
(shortcut toroom list -n <search-term>
) -
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 derived from rooms API's
-
room count
-
room top-complexity
-
room top-members
-
-
- Server notices API
-
Shutdown room API(DEPRECATED, covered byroom delete
) - Statistics API
- User admin API
-
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>
) - Additional commands and aliases derived from user API's
-
user search <search-term>
(shortcut touser list -d -g -n <search-term>
) -
user query <user id>
(alias ofuser details
) -
user create <user id>
(alias ofuser modify ...
)
-
-
- Version API
-
version
-
Get in touch / feedback / support
If you need help with installing, usage or contribution or have anything else on your mind, just join public matrix room #synadm:peek-a-boo.at and get in touch. I am also hanging around on #matrix-dev:matrix.org and #synapse:matrix.org regularily. Just ask for a jojo ;-)
Contribution
How can I help?
- Install
synadm
and report back whether or not the installation process worked on the OS you're running. - Read the Synapse admin API docs, pick a feature, implement it and send a pull-request - see implementation examples chapter, it really isn't hard, take a look!
- If you don't code, you can still help me prioritize what to code next: Pick a feature from the docs just mentioned, open a github issue in this repo and tell me what it is. Alternatively just catch me on #synadm:peek-a-boo.at or #matrix-dev:matrix.org.
Thanks in advance for any help! I can't do this without you!
Install to virtual environment
If you'd rather prefer to install synadm
into its own private virtual Python environment or even would like to help code it, this is a much cleaner approach compared to the steps descibed in the main installation chapter
1. Check Python version
python3 --version
should show at least v3.6.x
2. Clone repo:
git clone https://github.com/joj0/synadm
3. Setup and load a new Python3 virtual environment
Create and activate a virtual environment using the python3 venv module:
python3 -m venv ~/.venvs/synadm
source ~/.venvs/synadm/bin/activate
Once your Python virtual environment is loaded and your prompt looks similar to (synadm) .... $
, install directly into the environment:
4. Install
cd synadm
python3 setup.py install
Note: Don't forget to activate the venv when coming back to using synadm
after a fresh login: source ~/.venvs/synadm/bin/activate
5. Run
As long as your venv is loaded synadm
should run fine without having to add a path in front of it
synadm -h
Install in development mode
If you'd like to contribute to synadm's development, it's recommended to use a venv as described above, and also use a slightly different installation command:
cd synadm
python3 setup.py develop
Note: When installed like this, code-changes inside the repo dir will immediately be available when executing synadm
. This could also be used as a quick way to just stay on top of synadm's development.
Implementation examples
Without much talk, have a look at this method: https://github.com/JOJ0/synadm/blob/107d34b38de71d6d21d78141e78a1b19d3dd5379/synadm/cli/user.py#L185
and this one: https://github.com/JOJ0/synadm/blob/107d34b38de71d6d21d78141e78a1b19d3dd5379/synadm/api.py#L80
That's all it needs to implement command synadm user details <user_id>
.
And another example, this time using a POST based API endpoint. It implements command synadm user password <user_id>
. This is the CLI-level method: https://github.com/JOJ0/synadm/blob/0af918fdeee40bc1d3df7b734a46e76bb31148b9/synadm/cli/user.py#L114
and again it needs a backend method in api.py: https://github.com/JOJ0/synadm/blob/107d34b38de71d6d21d78141e78a1b19d3dd5379/synadm/api.py#L72
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.