Config File

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

This config file contains four sections:

  • ansible

  • synapse

  • api

  • ssh

In the ansible section fill in the absolute path to your fully configured Playbook. Make sure ansible is configured correctly on your system. To get started, follow the Synapse Playbook guide. You need this section, if you want to:

  • matrixctl adduser --ansible

  • matrixctl deploy

  • matrixctl start

  • matrixctl restart

  • matrixctl maintenance

  • matrixctl check

Note

If you want to run (multiple) playbooks you can create a file which contains import_playbook lines like: - import_playbook: /PathTo/matrix-docker-ansible-deploy/setup.yml and configure it as playbook in the matrixctl config file.

The synapse section is used for update (git pull) the synapse playbook You need this section, if you want to:

  • matrixctl update

The api section is used to communicate with the synapse API directly. This is faster and has more additional functionality then the Synapse playbook. To get started, follow the Access Token guide. It is used for:

  • matrixctl adduser

  • matrixctl deluser

  • matrixctl users

  • matrixctl user

  • matrixctl users

  • matrixctl upload

  • matrixctl rooms

  • matrixctl delroom

  • matrixctl server-notice

  • matrixctl purge-history

  • matrixctl version

With the ssh section you can use additional functionality, if you like. It is used for:

  • matrixctl adduser-jisi

  • matrixctl deluser-jisi

  • matrixctl get-event

Note

If you are not sure, what to fill in that config file, read the rest of the “Getting Started” section of this documentation.

Warning

Make sure, that other accounts of your local machine are not able to read or edit your config file. I contains sensitive data.

 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 cerate 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 maintainance tasks
55    maintenance:
56      tasks:
57        - compress-state  # Compress synapses state table
58        - vacuum          # VACUUM the synapse database (garbage-collection)
59
60  # Another server.
61  foo:
62    # ...