MatrixCtl is a python program to control, manage, provision and deploy our matrix homeserver. I had a bunch of shell scripts doing that. Two weeks after using them I couldn’t remember the order in which I have to use the arguments or which arguments where needed. It was a pain. So I decided I hack something together fast.
It’s not the most elegant piece of software I wrote, but it should do the trick. I will continue to port the rest of the scripts and add new features.
This repository uses the git-flow branching model by Vincent Driessen. It has two branches with infinite lifetime:
The master branch gets updated on every release. The develop branch is the merging branch.
Command line tool
MatrixCtl as a pure commandline tool. You can use it as package, if you like, but breaking changes may introduced, even in a minor change.
usage: matrixctl [-h] [--version] [-d] [-s SERVER] [-c CONFIG] Command ... MatrixCtl is a simple, but feature-rich tool to remotely control, manage, provision and deploy Matrix homeservers. options: -h, --help show this help message and exit --version show program's version number and exit -d, --debug Enables debugging mode. -s SERVER, --server SERVER Select the server. (default: "default") -c CONFIG, --config CONFIG A path to an alternative config file. Commands: The following are commands, you can use to accomplish various tasks. Command adduser Add users to the homeserver adduser-jitsi [DEPRECATED] Add users to a jitsi server check Checks the deployment with Ansible delete-local-media Delete cached (local) media that was last accessed before a specific point in time delroom Shutdown a room deluser Deactivate users deluser-jitsi [DEPRECATED] Delete jitsi users deploy Provision and deploy the Ansible playbook get-event Get an event from the database get-event-context Get the context of an event get-events Get events from the database is-admin Check, if a user is a homeserver administrator joinroom Join a user to a room maintenance Run maintenance tasks make-room-admin Grant a user the highest power level available to a local user in this room purge-history Purge historic events from the database purge-remote-media Purge cached, remote media report Get a report event by report identifier reports Lists reported events rooms List rooms server-notice Send a server notice to a user set-admin Change whether a user is a homeserver admin or not start Starts all OCI containers restart Restarts all OCI containers (alias for start) stop Stop and disable all OCI containers update Updates the ansible playbook repository upload Upload a media file. user Get information about a specific user users Lists all users of the homeserver version Get the version information of the Synapse instance Thank you for using MatrixCtl! Check out the docs: https://matrixctl.rtfd.io Report bugs to: https://github.com/MichaelSasser/matrixctl/issues/new/choose
To use this program you need to have this config file in
/etc/matrixctl/config or in
1# Define your homeservers in "servers" here. 2servers: 3 # Your default server. You can specify muliple servers here with arbitrary 4 # Names 5 default: 6 7 ansible: 8 # The absolute path to your playbook 9 playbook: /path/to/ansible/playbook 10 11 synapse: 12 # The absolute path to the synapse playbook. 13 # This is only used for updating the playbook. 14 playbook: /path/to/synapse/playbook 15 16 # If your matrix server is deployed, you may want to fill out the API section. 17 # It enables matrixctl to run more and faster commands. You can deploy and 18 # provision your Server without this section. You also can create a user with 19 # "matrixctl adduser --ansible YourUsername" and add your privileges after 20 # that. 21 api: 22 # Your domain should be something like "michaelsasser.org" without the 23 # "matrix." in the front. MatrixCtl will add that, if needed. An IP-Address 24 # is not enough. 25 domain: example.com 26 27 # The username your admin user 28 username: johndoe 29 30 # To use the API you need to have an administrator account. Enter your Token 31 # here. If you use the element client you will find it your user settings 32 # (click on your username on the upper left corner on your browser) in the 33 # "Help & About" tab. If you scroll down click next to "Access-Token:" on 34 # "<click to reveal>". It will be marked for you. Copy it in here. 35 token: "MyMatrixToken" 36 37 # In some cases, MatrixCtl does need to make many requests. To speed those 38 # requests a notch, you can set a concurrent_limit which is greater than 39 # one. This sets a limit to how many asynchronous workers can be spawned 40 # by MatrixCtl. If you set the number to high, MatrixCtl needs more time 41 # to spawn the workers, then a synchronous request would take. 42 concurrent_limit: 10 43 44 # Here you can add your SSH configuration. 45 ssh: 46 address: matrix.example.com 47 48 # The default port is 22 49 port: 22 50 51 # The default username is your current login name. 52 user: john 53 54 # Define your maintenance tasks 55 maintenance: 56 tasks: 57 - compress-state # Compress synapses state table 58 - vacuum # VACUUM the synapse database (garbage-collection) 59 60 # Add connection parameters to the Database 61 # Synapse does only read (SELECT) information from the database. 62 # The user needs to be able to login to the synapse database 63 # and SELECT from the events and event_json tables. 64 database: 65 synapse_database: synapse # this is the playbooks default table name 66 synapse_user: matrixctl # the username (role) for the database 67 synapse_password: "RolePassword" 68 tunnel: true # true if an ssh tunnel should be used to connect 69 70 # The port that was used in the playbook (e.g. 71 # matrix_postgres_container_postgres_bind_port: 5432) 72 # or for your external database. For security reasons the port 73 # should be blocked by your firewall. Iy you enable the tunnel 74 # by setting tunnel: true, MatrixCtl activates a SSH tunnel. 75 port: 5432 # the remote port 76 77 # Another server. 78 foo: 79 # ...
After release “1.0.0” this repository will use SemVer for its release cycle.
Before release “1.0.0” it uses “0.y.z” as recommended by SemVer. This means that breaking changes result in a version change at “y” position (e.g. “0.1.0” -> “0.2.0”). Non breaking changes result in a “z” change (e.g. “0.1.1” -> “0.1.2”).
Indices and tables
Copyright © 2020 Michael Sasser <Info@MichaelSasser.org>. Released under the GPLv3 license.