# MatrixCtl
MatrixCtl is a simple, but feature-rich tool to remotely control, manage,
provision and deploy your Matrix homeservers and users from your virtual
terminal.
```console
$ matrixctl
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.
optional arguments:
-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 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 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
```
## Installation
MatrixCtl is written in Python. The installation is straight forward. Just run
`pip install matrixctl`. It will be installed from the
[Python Package Index (PyPi)](https://pypi.org/project/matrixctl/).
Upgrade MatrixCtl with `pip install --upgrade matrixctl`.
You will find more information in the
[documentation](https://matrixctl.readthedocs.io/en/latest/installation.html).
## Documentation
The [documentation](https://matrixctl.readthedocs.io/en/latest/index.html) is
waiting for you, to check out.
## Configuration File
To use this tool you need to have a configuration file in
"~/.config/matrixctl/config.yaml" or in "/etc/matrixctl/config.yaml".
```yaml
# Define your homeservers in "servers" here.
servers:
# Your default server. You can specify muliple servers here with arbitrary
# Names
default:
ansible:
# The absolute path to your playbook
playbook: /path/to/ansible/playbook
synapse:
# The absolute path to the synapse playbook.
# This is only used for updating the playbook.
playbook: /path/to/synapse/playbook
# If your matrix server is deployed, you may want to fill out the API section.
# It enables matrixctl to run more and faster commands. You can deploy and
# provision your Server without this section. You also can create a user with
# "matrixctl adduser --ansible YourUsername" and add your privileges after
# that.
api:
# Your domain should be something like "michaelsasser.org" without the
# "matrix." in the front. MatrixCtl will add that, if needed. An IP-Address
# is not enough.
domain: example.com
# The username your admin user
username: johndoe
# To use the API you need to have an administrator account. Enter your Token
# here. If you use the element client you will find it your user settings
# (click on your username on the upper left corner on your browser) in the
# "Help & About" tab. If you scroll down click next to "Access-Token:" on
# "<click to reveal>". It will be marked for you. Copy it in here.
token: "MyMatrixToken"
# In some cases, MatrixCtl does need to make many requests. To speed those
# requests a notch, you can set a concurrent_limit which is greater than
# one. This sets a limit to how many asynchronous workers can be spawned
# by MatrixCtl. If you set the number to high, MatrixCtl needs more time
# to spawn the workers, then a synchronous request would take.
concurrent_limit: 10
# Here you can add your SSH configuration.
ssh:
address: matrix.example.com
# The default port is 22
port: 22
# The default username is your current login name.
user: john
# Define your maintenance tasks
maintenance:
tasks:
- compress-state # Compress synapses state table
- vacuum # VACUUM the synapse database (garbage-collection)
# Add connection parameters to the Database
# Synapse does only read (SELECT) information from the database.
# The user needs to be able to login to the synapse database
# and SELECT from the events and event_json tables.
database:
synapse_database: synapse # this is the playbooks default table name
synapse_user: matrixctl # the username (role) for the database
synapse_password: "RolePassword"
tunnel: true # true if an ssh tunnel should be used to connect
# The port that was used in the playbook (e.g.
# matrix_postgres_container_postgres_bind_port: 5432)
# or for your external database. For security reasons the port
# should be blocked by your firewall. Iy you enable the tunnel
# by setting tunnel: true, MatrixCtl activates a SSH tunnel.
port: 5432 # the remote port
# Another server.
foo:
# ...
```
Predefined Jinja2 placeholders (all placeholders can be overwritten):
- `"{{ home }}"` -- The current users home path e.g. `/home/michael`,
- `"{{ user }}"` -- The current users username e.g. `michael`,
- `"{{ default_ssh_port }}"` -- The default ssh port `22`,
- `"{{ default_api_concurrent_limit }}"` -- The default concurrent limit `4`.
Check out the
[documentation](https://matrixctl.readthedocs.io/en/latest/getting_started/config_file.html)
for more information.
## Discussions & Chat
If you have any thoughts or questions, you can ask them in the
[discusions](https://github.com/MichaelSasser/matrixctl/discussions) or in the
projects matrix room `#matrixctl:matrix.org`.
## Semantic Versioning and Branching Model
This Python package uses [SemVer](https://semver.org/) for its release cycle
and the
[git-flow](https://danielkummer.github.io/git-flow-cheatsheet/index.html)
branching model (by [Vincent Driessen](https://nvie.com/about/)).
It has two branches with infinite lifetime. The:
- [develop](https://github.com/MichaelSasser/matrixctl/tree/develop) branch is
the merging branch,
- [master](https://github.com/MichaelSasser/matrixctl/tree/master) branch gets
updated on every release.
## Contributing
Please check our
[Contributer Documentation](https://matrixctl.readthedocs.io/en/latest/contributer_documentation/index.html#contributer-documentation).
## License
Copyright © 2020-2001 Michael Sasser <Info@MichaelSasser.org>. Released
under the GPLv3 license.
Raw data
{
"_id": null,
"home_page": "https://michaelsasser.github.io/matrixctl/index.html",
"name": "matrixctl",
"maintainer": "Michael Sasser",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "Michael@MichaelSasser.org",
"keywords": "Matrix, Synapse, Docker",
"author": "Michael Sasser",
"author_email": "Michael@MichaelSasser.org",
"download_url": "https://files.pythonhosted.org/packages/b4/cb/c867b3e8098b4f500e606a4b7aa22e6e386fb3d5c9291b5b7a1ebaacf22c/matrixctl-0.12.0.tar.gz",
"platform": null,
"description": "\n\n\n\n\n\n# MatrixCtl\n\nMatrixCtl is a simple, but feature-rich tool to remotely control, manage,\nprovision and deploy your Matrix homeservers and users from your virtual\nterminal.\n\n```console\n$ matrixctl\nusage: matrixctl [-h] [--version] [-d] [-s SERVER] [-c CONFIG] Command ...\n\nMatrixCtl is a simple, but feature-rich tool to remotely control, manage, provision and deploy Matrix homeservers.\n\noptional arguments:\n -h, --help show this help message and exit\n --version show program's version number and exit\n -d, --debug Enables debugging mode.\n -s SERVER, --server SERVER\n Select the server. (default: \"default\")\n -c CONFIG, --config CONFIG\n A path to an alternative config file.\n\nCommands:\n The following are commands, you can use to accomplish various tasks.\n\n Command\n adduser Add users to the homeserver\n adduser-jitsi Add users to a jitsi server\n check Checks the deployment with Ansible\n delete-local-media Delete cached (local) media that was last accessed before a\n specific point in time\n delroom Shutdown a room\n deluser Deactivate users\n deluser-jitsi Delete jitsi users\n deploy Provision and deploy the Ansible playbook\n get-event Get an event from the database\n get-event-context Get the context of an event\n get-events Get events from the database\n is-admin Check, if a user is a homeserver administrator\n joinroom Join a user to a room\n maintenance Run maintenance tasks\n make-room-admin Grant a user the highest power level available to a local user\n in this room\n purge-history Purge historic events from the database\n purge-remote-media Purge cached, remote media\n report Get a report event by report identifier\n reports Lists reported events\n rooms List rooms\n server-notice Send a server notice to a user\n set-admin Change whether a user is a homeserver admin or not\n start Starts all OCI containers\n restart Restarts all OCI containers (alias for start)\n stop Stop and disable all OCI containers\n update Updates the ansible playbook repository\n upload Upload a media file.\n user Get information about a specific user\n users Lists all users of the homeserver\n version Get the version information of the Synapse instance\n\nThank you for using MatrixCtl!\nCheck out the docs: https://matrixctl.rtfd.io\nReport bugs to: https://github.com/MichaelSasser/matrixctl/issues/new/choose\n```\n\n## Installation\n\nMatrixCtl is written in Python. The installation is straight forward. Just run\n`pip install matrixctl`. It will be installed from the\n[Python Package Index (PyPi)](https://pypi.org/project/matrixctl/).\n\nUpgrade MatrixCtl with `pip install --upgrade matrixctl`.\n\nYou will find more information in the\n[documentation](https://matrixctl.readthedocs.io/en/latest/installation.html).\n\n## Documentation\n\nThe [documentation](https://matrixctl.readthedocs.io/en/latest/index.html) is\nwaiting for you, to check out.\n\n## Configuration File\n\nTo use this tool you need to have a configuration file in\n\"~/.config/matrixctl/config.yaml\" or in \"/etc/matrixctl/config.yaml\".\n\n```yaml\n# Define your homeservers in \"servers\" here.\nservers:\n # Your default server. You can specify muliple servers here with arbitrary\n # Names\n default:\n ansible:\n # The absolute path to your playbook\n playbook: /path/to/ansible/playbook\n\n synapse:\n # The absolute path to the synapse playbook.\n # This is only used for updating the playbook.\n playbook: /path/to/synapse/playbook\n\n # If your matrix server is deployed, you may want to fill out the API section.\n # It enables matrixctl to run more and faster commands. You can deploy and\n # provision your Server without this section. You also can create a user with\n # \"matrixctl adduser --ansible YourUsername\" and add your privileges after\n # that.\n api:\n # Your domain should be something like \"michaelsasser.org\" without the\n # \"matrix.\" in the front. MatrixCtl will add that, if needed. An IP-Address\n # is not enough.\n domain: example.com\n\n # The username your admin user\n username: johndoe\n\n # To use the API you need to have an administrator account. Enter your Token\n # here. If you use the element client you will find it your user settings\n # (click on your username on the upper left corner on your browser) in the\n # \"Help & About\" tab. If you scroll down click next to \"Access-Token:\" on\n # \"<click to reveal>\". It will be marked for you. Copy it in here.\n token: \"MyMatrixToken\"\n\n # In some cases, MatrixCtl does need to make many requests. To speed those\n # requests a notch, you can set a concurrent_limit which is greater than\n # one. This sets a limit to how many asynchronous workers can be spawned\n # by MatrixCtl. If you set the number to high, MatrixCtl needs more time\n # to spawn the workers, then a synchronous request would take.\n concurrent_limit: 10\n\n # Here you can add your SSH configuration.\n ssh:\n address: matrix.example.com\n\n # The default port is 22\n port: 22\n\n # The default username is your current login name.\n user: john\n\n # Define your maintenance tasks\n maintenance:\n tasks:\n - compress-state # Compress synapses state table\n - vacuum # VACUUM the synapse database (garbage-collection)\n\n # Add connection parameters to the Database\n # Synapse does only read (SELECT) information from the database.\n # The user needs to be able to login to the synapse database\n # and SELECT from the events and event_json tables.\n database:\n synapse_database: synapse # this is the playbooks default table name\n synapse_user: matrixctl # the username (role) for the database\n synapse_password: \"RolePassword\"\n tunnel: true # true if an ssh tunnel should be used to connect\n\n # The port that was used in the playbook (e.g.\n # matrix_postgres_container_postgres_bind_port: 5432)\n # or for your external database. For security reasons the port\n # should be blocked by your firewall. Iy you enable the tunnel\n # by setting tunnel: true, MatrixCtl activates a SSH tunnel.\n port: 5432 # the remote port\n\n # Another server.\n foo:\n # ...\n```\n\nPredefined Jinja2 placeholders (all placeholders can be overwritten):\n\n- `\"{{ home }}\"` -- The current users home path e.g. `/home/michael`,\n- `\"{{ user }}\"` -- The current users username e.g. `michael`,\n- `\"{{ default_ssh_port }}\"` -- The default ssh port `22`,\n- `\"{{ default_api_concurrent_limit }}\"` -- The default concurrent limit `4`.\n\nCheck out the\n[documentation](https://matrixctl.readthedocs.io/en/latest/getting_started/config_file.html)\nfor more information.\n\n## Discussions & Chat\n\nIf you have any thoughts or questions, you can ask them in the\n[discusions](https://github.com/MichaelSasser/matrixctl/discussions) or in the\nprojects matrix room `#matrixctl:matrix.org`.\n\n## Semantic Versioning and Branching Model\n\nThis Python package uses [SemVer](https://semver.org/) for its release cycle\nand the\n[git-flow](https://danielkummer.github.io/git-flow-cheatsheet/index.html)\nbranching model (by [Vincent Driessen](https://nvie.com/about/)).\n\nIt has two branches with infinite lifetime. The:\n\n- [develop](https://github.com/MichaelSasser/matrixctl/tree/develop) branch is\n the merging branch,\n- [master](https://github.com/MichaelSasser/matrixctl/tree/master) branch gets\n updated on every release.\n\n## Contributing\n\nPlease check our\n[Contributer Documentation](https://matrixctl.readthedocs.io/en/latest/contributer_documentation/index.html#contributer-documentation).\n\n## License\n\nCopyright © 2020-2001 Michael Sasser <Info@MichaelSasser.org>. Released\nunder the GPLv3 license.\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Control, manage, provision and deploy matrix homeservers.",
"version": "0.12.0",
"project_urls": {
"Documentation": "https://michaelsasser.github.io/matrixctl/index.html",
"Homepage": "https://michaelsasser.github.io/matrixctl/index.html",
"Repository": "https://github.com/MichaelSasser/matrixctl"
},
"split_keywords": [
"matrix",
" synapse",
" docker"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "04c975ecca473a1977bcdb907243325989e9c27c54dcfc20a14c297e10deef8b",
"md5": "9ce3456e94eb8201e96858628cf17993",
"sha256": "364258e75d8960dcc96236376987b4e0b2611d77c37fa18baf6113ac0e162181"
},
"downloads": -1,
"filename": "matrixctl-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ce3456e94eb8201e96858628cf17993",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 163578,
"upload_time": "2024-06-05T21:26:25",
"upload_time_iso_8601": "2024-06-05T21:26:25.676605Z",
"url": "https://files.pythonhosted.org/packages/04/c9/75ecca473a1977bcdb907243325989e9c27c54dcfc20a14c297e10deef8b/matrixctl-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b4cbc867b3e8098b4f500e606a4b7aa22e6e386fb3d5c9291b5b7a1ebaacf22c",
"md5": "abe8b3ca1e223b0b5394c7a8edc2b85f",
"sha256": "503555e81b0e7ddce0aab9ee5666ed06172d75c17573da93ff33b0775d2a8157"
},
"downloads": -1,
"filename": "matrixctl-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "abe8b3ca1e223b0b5394c7a8edc2b85f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 68680,
"upload_time": "2024-06-05T21:26:27",
"upload_time_iso_8601": "2024-06-05T21:26:27.316609Z",
"url": "https://files.pythonhosted.org/packages/b4/cb/c867b3e8098b4f500e606a4b7aa22e6e386fb3d5c9291b5b7a1ebaacf22c/matrixctl-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-05 21:26:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MichaelSasser",
"github_project": "matrixctl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "matrixctl"
}
JSON
