MatrixCtl documentation

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.

Contents:

Branching Model

This repository uses the GitHub Flow.

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   Select the server. (default: "default")
  -c, --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
    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
    deploy              Provision and deploy the Ansible playbook
    download            Download a media file.
    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
    largest-rooms       List an approximation of the 10 largest rooms in the
                        database
    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

Configuration File

To use this program you need to have this config file in /etc/matrixctl/config or in ~/.config/matrixctl/config.

 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    # ...

Semantic Versioning

After release “1.0.0” this repository will use SemVer for its release cycle.

Note

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

License

Copyright © 2020 Michael Sasser <Info@MichaelSasser.org>. Released under the GPLv3 license.