Add matrix-registration-bot (#1771)

* Add matrix-registration-bot

This adds an install and uninstall task plus helpers. The bot is disabled by default.
This commit does not include documentation, yet. In short, the bot can be enabled by adding
matrix_bot_matrix_registration_bot_enabled: true
matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret"
matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret"
to the host_vars

* Change bot username to bot.matrix-registration-bot following convention

* Address smaller remarks, fix local docker build

* Switch to an env file

* Add environment variables extension for additional config

* Add documentation for the matrix-registration-bot

* Add screenshot on how to obtain admin access token

* Use bot as admin to only have one access token (bot and admin api)

* Use cleaner setting of matrix_synapse_registration_requires_token

* Use config file for cleaner more secure usage

* Delete unneeded env

* Rename vars to make usage clear

* Fix typos/wording and add notice about logging out

* Convert configuration to use |to_json

* Reorder role includes

Nothing should be after `matrix-common-after`.

`matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles.

* Minor group_vars/matrix_servers touchups

Co-authored-by: Slavi Pantaleev <slavi@devture.com>
This commit is contained in:
Julian-Samuel Gebühr 2022-04-21 10:07:47 +02:00 committed by GitHub
parent acaebfbf67
commit 90a142439a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 349 additions and 0 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 205 KiB

View File

@ -0,0 +1,72 @@
# Setting up matrix-registration-bot (optional)
The playbook can install and configure [matrix-registration-bot](https://github.com/moanos/matrix-registration-bot) for you.
The bot allows you to easily **create and manage registration tokens**. It can be used for an invitation-based server,
where you invite someone by sending them a registration token. They can register as normal but have to provide a valid
registration token in a final step of the registration.
See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it
does and why it might be useful to you.
## Registering the bot user
By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:DOMAIN`.
(to use a different username, adjust the `matrix_bot_matrix_registration_bot_matrix_user_id_localpart` variable).
You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md):
```
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-registration-bot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user
```
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
## Obtaining an admin access token
In order to use the bot you need to add an admin user's access token token to the configuration. As you created an admin user for the
bot, it is recommended to obtain an access token by logging into Element/Schildichat with the bot account
(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
You can expand "Access token" to copy it.
![Obatining an admin access token with Element](assets/obtain_admin_access_token_element.png)
**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.
## Adjusting the playbook configuration
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
```yaml
matrix_bot_matrix_registration_bot_enabled: true
# Token obtained via logging into the bot account (see above)
matrix_bot_matrix_registration_bot_bot_access_token: "syt_bW9hbm9z_XXXXXXXXXXXXXr_2kuzbE"
# Enables registration
matrix_synapse_enable_registration: true
# Restrict registration to users with a token
matrix_synapse_registration_requires_token: true
```
## Installing
After configuring the playbook, run the [installation](installing.md) command again:
```
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
To use the bot, create a **non-encrypted** room and invite `@bot.matrix-reminder-bot:DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
In this room send `help` and the bot will reply with all options.
You can also refer to the upstream [Usage documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands).
If you have any questions, or if you need help setting it up, read the [troublshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md)
or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).

View File

@ -151,6 +151,7 @@ When you're done with all the configuration you'd like to do, continue with [Ins
- [Setting up Mjolnir](configuring-playbook-bot-mjolnir.md) - a moderation tool/bot (optional)
- [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) - a bot to create and manage registration tokens to invite users (optional)
### Backups

View File

@ -987,6 +987,35 @@ matrix_bot_matrix_reminder_bot_container_image_self_build: "{{ matrix_architectu
#
######################################################################
######################################################################
#
# matrix-bot-matrix-registration-bot
#
######################################################################
# We don't enable bots by default.
matrix_bot_matrix_registration_bot_enabled: false
matrix_bot_matrix_registration_bot_container_image_self_build: "{{ matrix_architecture not in ['amd64'] }}"
matrix_bot_matrix_registration_bot_systemd_required_services_list: |
{{
['docker.service']
+
['matrix-' + matrix_homeserver_implementation + '.service']
+
(['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
}}
######################################################################
#
# /matrix-bot-matrix-registration-bot
#
######################################################################
######################################################################
#
# matrix-bot-honoroit

View File

@ -0,0 +1,49 @@
---
# matrix-registration-bot creates and manages registration tokens for a matrix server
# See: https://github.com/moan0s/matrix-registration-bot
matrix_bot_matrix_registration_bot_enabled: true
matrix_bot_matrix_registration_bot_container_image_self_build: false
matrix_bot_matrix_registration_bot_docker_repo: "https://github.com/moan0s/matrix-registration-bot.git"
matrix_bot_matrix_registration_bot_docker_src_files_path: "{{ matrix_bot_matrix_registration_bot_base_path }}/docker-src"
matrix_bot_matrix_registration_bot_version: latest
matrix_bot_matrix_registration_bot_docker_image: "{{ matrix_container_global_registry_prefix }}moanos/matrix-registration-bot:{{ matrix_bot_matrix_registration_bot_version }}"
matrix_bot_matrix_registration_bot_docker_image_force_pull: "{{ matrix_bot_matrix_registration_bot_docker_image.endswith(':latest') }}"
matrix_bot_matrix_registration_bot_base_path: "{{ matrix_base_data_path }}/matrix-registration-bot"
matrix_bot_matrix_registration_bot_config_path: "{{ matrix_bot_matrix_registration_bot_base_path }}/config"
matrix_bot_matrix_registration_bot_data_path: "{{ matrix_bot_matrix_registration_bot_base_path }}/data"
matrix_bot_matrix_registration_bot_bot_server: "https://{{ matrix_server_fqn_matrix }}"
matrix_bot_matrix_registration_bot_api_base_url: "https://{{ matrix_server_fqn_matrix }}"
# The access token that the bot uses to communicate in Matrix chats
# This does not necessarily need to be a privileged (admin) access token.
matrix_bot_matrix_registration_bot_bot_access_token: ''
# The access token that the bot uses to call the Matrix API for creating registration tokens.
# This needs to be a privileged (admin) access token.
# By default, we assume `matrix_bot_matrix_registration_bot_bot_access_token` is such a privileged token and we use it as is.
# If necessary, you can define your own other access token here, which might even be for a different Matrix user.
matrix_bot_matrix_registration_bot_api_token: "{{ matrix_bot_matrix_registration_bot_bot_access_token }}"
matrix_bot_matrix_registration_bot_logging_level: info
matrix_bot_matrix_registration_environment_variables_extension: ''
# A list of extra arguments to pass to the container
matrix_bot_matrix_registration_bot_container_extra_arguments: []
# List of systemd services that matrix-bot-matrix-registration-bot.service depends on
matrix_bot_matrix_registration_bot_systemd_required_services_list: ['docker.service']
# List of systemd services that matrix-bot-matrix-registration-bot.service wants
matrix_bot_matrix_registration_bot_systemd_wanted_services_list: []
# The bot's username. This user needs to be created manually beforehand.
# Also see `matrix_bot_matrix_registration_bot_user_password`.
matrix_bot_matrix_registration_bot_matrix_user_id_localpart: "bot.matrix-registration-bot"
matrix_bot_matrix_registration_bot_matrix_user_id: '@{{ matrix_bot_matrix_registration_bot_matrix_user_id_localpart }}:{{ matrix_domain }}'
matrix_bot_matrix_registration_bot_matrix_homeserver_url: "{{ matrix_homeserver_container_url }}"

View File

@ -0,0 +1,5 @@
---
- set_fact:
matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-matrix-registration-bot.service'] }}"
when: matrix_bot_matrix_registration_bot_enabled|bool

View File

@ -0,0 +1,23 @@
---
- import_tasks: "{{ role_path }}/tasks/init.yml"
tags:
- always
- import_tasks: "{{ role_path }}/tasks/validate_config.yml"
when: "run_setup|bool and matrix_bot_matrix_registration_bot_enabled|bool"
tags:
- setup-all
- setup-bot-matrix-registration-bot
- import_tasks: "{{ role_path }}/tasks/setup_install.yml"
when: "run_setup|bool and matrix_bot_matrix_registration_bot_enabled|bool"
tags:
- setup-all
- setup-bot-matrix-registration-bot
- import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
when: "run_setup|bool and not matrix_bot_matrix_registration_bot_enabled|bool"
tags:
- setup-all
- setup-bot-matrix-registration-bot

View File

@ -0,0 +1,73 @@
---
- name: Ensure matrix-registration-bot paths exist
file:
path: "{{ item.path }}"
state: directory
mode: 0750
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
with_items:
- {path: "{{ matrix_bot_matrix_registration_bot_config_path }}", when: true}
- - {path: "{{ matrix_bot_matrix_registration_bot_data_path }}", when: true}
- {path: "{{ matrix_bot_matrix_registration_bot_docker_src_files_path }}", when: true}
when: "item.when|bool"
- name: Ensure matrix-registration-bot configuration file created
template:
src: "{{ role_path }}/templates/config/config.yml.j2"
dest: "{{ matrix_bot_matrix_registration_bot_config_path }}/config.yml"
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
mode: 0640
- name: Ensure matrix-registration-bot image is pulled
docker_image:
name: "{{ matrix_bot_matrix_registration_bot_docker_image }}"
source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
force_source: "{{ matrix_bot_matrix_registration_bot_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_bot_matrix_registration_bot_docker_image_force_pull }}"
when: "not matrix_bot_matrix_registration_bot_container_image_self_build|bool"
register: result
retries: "{{ matrix_container_retries_count }}"
delay: "{{ matrix_container_retries_delay }}"
until: result is not failed
- name: Ensure matrix-registration-bot repository is present on self-build
git:
repo: "{{ matrix_bot_matrix_registration_bot_docker_repo }}"
dest: "{{ matrix_bot_matrix_registration_bot_docker_src_files_path }}"
force: "yes"
become: true
become_user: "{{ matrix_user_username }}"
register: matrix_bot_matrix_registration_bot_git_pull_results
when: "matrix_bot_matrix_registration_bot_container_image_self_build|bool"
- name: Ensure matrix-registration-bot image is built
docker_image:
name: "{{ matrix_bot_matrix_registration_bot_docker_image }}"
source: build
force_source: "{{ matrix_bot_matrix_registration_bot_git_pull_results.changed if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_mailer_git_pull_results.changed }}"
build:
dockerfile: Dockerfile
path: "{{ matrix_bot_matrix_registration_bot_docker_src_files_path }}"
pull: true
when: "matrix_bot_matrix_registration_bot_container_image_self_build|bool"
- name: Ensure matrix-bot-matrix-registration-bot.service installed
template:
src: "{{ role_path }}/templates/systemd/matrix-bot-matrix-registration-bot.service.j2"
dest: "{{ matrix_systemd_path }}/matrix-bot-matrix-registration-bot.service"
mode: 0644
register: matrix_bot_matrix_registration_bot_systemd_service_result
- name: Ensure systemd reloaded after matrix-bot-matrix-registration-bot.service installation
service:
daemon_reload: true
when: "matrix_bot_matrix_registration_bot_systemd_service_result.changed|bool"
- name: Ensure matrix-bot-matrix-registration-bot.service restarted, if necessary
service:
name: "matrix-bot-matrix-registration-bot.service"
state: restarted

View File

@ -0,0 +1,36 @@
---
- name: Check existence of matrix-matrix-registration-bot service
stat:
path: "{{ matrix_systemd_path }}/matrix-bot-matrix-registration-bot.service"
register: matrix_bot_matrix_registration_bot_service_stat
- name: Ensure matrix-matrix-registration-bot is stopped
service:
name: matrix-bot-matrix-registration-bot
state: stopped
enabled: false
daemon_reload: true
register: stopping_result
when: "matrix_bot_matrix_registration_bot_service_stat.stat.exists|bool"
- name: Ensure matrix-bot-matrix-registration-bot.service doesn't exist
file:
path: "{{ matrix_systemd_path }}/matrix-bot-matrix-registration-bot.service"
state: absent
when: "matrix_bot_matrix_registration_bot_service_stat.stat.exists|bool"
- name: Ensure systemd reloaded after matrix-bot-matrix-registration-bot.service removal
service:
daemon_reload: true
when: "matrix_bot_matrix_registration_bot_service_stat.stat.exists|bool"
- name: Ensure Matrix matrix-registration-bot paths don't exist
file:
path: "{{ matrix_bot_matrix_registration_bot_base_path }}"
state: absent
- name: Ensure matrix-registration-bot Docker image doesn't exist
docker_image:
name: "{{ matrix_bot_matrix_registration_bot_docker_image }}"
state: absent

View File

@ -0,0 +1,10 @@
---
- name: Fail if required settings not defined
fail:
msg: >-
You need to define a required configuration setting (`{{ item }}`).
when: "vars[item] == ''"
with_items:
- "matrix_bot_matrix_registration_bot_bot_access_token"
- "matrix_bot_matrix_registration_bot_api_token"

View File

@ -0,0 +1,12 @@
bot:
server: {{ matrix_bot_matrix_registration_bot_bot_server|to_json }}
username: {{ matrix_bot_matrix_registration_bot_matrix_user_id_localpart|to_json }}
access_token: {{ matrix_bot_matrix_registration_bot_bot_access_token|to_json }}
api:
# API endpoint of the registration tokens
base_url: {{ matrix_bot_matrix_registration_bot_api_base_url|to_json }}
# Access token of an administrator on the server
token: {{ matrix_bot_matrix_registration_bot_api_token|to_json }}
logging:
level: {{ matrix_bot_matrix_registration_bot_logging_level|to_json }}

View File

@ -0,0 +1,38 @@
#jinja2: lstrip_blocks: "True"
[Unit]
Description=Matrix registration bot
{% for service in matrix_bot_matrix_registration_bot_systemd_required_services_list %}
Requires={{ service }}
After={{ service }}
{% endfor %}
{% for service in matrix_bot_matrix_registration_bot_systemd_wanted_services_list %}
Wants={{ service }}
{% endfor %}
DefaultDependencies=no
[Service]
Type=simple
Environment="HOME={{ matrix_systemd_unit_home_path }}"
ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-bot-matrix-registration-bot 2>/dev/null || true'
ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-bot-matrix-registration-bot 2>/dev/null || true'
ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-bot-matrix-registration-bot \
--log-driver=none \
--cap-drop=ALL \
-e "CONFIG_PATH=/config/config.yml" \
--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
--read-only \
--mount type=bind,src={{ matrix_bot_matrix_registration_bot_config_path }},dst=/config,ro \
--mount type=bind,src={{ matrix_bot_matrix_registration_bot_data_path }},dst=/data \
--network={{ matrix_docker_network }} \
--env-file={{ matrix_bot_matrix_registration_bot_config_path }}/env \
{{ matrix_bot_matrix_registration_bot_docker_image }}
ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-bot-matrix-registration-bot 2>/dev/null || true'
ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-bot-matrix-registration-bot 2>/dev/null || true'
Restart=always
RestartSec=30
SyslogIdentifier=matrix-bot-matrix-registration-bot
[Install]
WantedBy=multi-user.target

View File

@ -37,6 +37,7 @@
- matrix-bridge-heisenbridge
- matrix-bridge-hookshot
- matrix-bot-matrix-reminder-bot
- matrix-bot-matrix-registration-bot
- matrix-bot-honoroit
- matrix-bot-go-neb
- matrix-bot-mjolnir