diff --git a/docs/configuring-playbook-bot-maubot.md b/docs/configuring-playbook-bot-maubot.md index be267b326..e45ca87db 100644 --- a/docs/configuring-playbook-bot-maubot.md +++ b/docs/configuring-playbook-bot-maubot.md @@ -47,6 +47,15 @@ If you've changed the default hostname, you may need to create a CNAME record fo When setting, replace `example.com` with your own. +### Extending the configuration + +There are some additional things you may wish to configure about the bot. + +Take a look at: + +- `roles/custom/matrix-bot-maubot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file +- `roles/custom/matrix-bot-maubot/templates/config.yaml.j2` for the bot's default configuration + ## Customizing the maubot container image Certain [maubot plugins](https://plugins.mau.bot/) require additional dependencies to be installed. @@ -102,3 +111,16 @@ Alternatively, you can refer to the documentation on [how to obtain an access to > [!WARNING] > Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bot-maubot`. + +### Increase logging verbosity + +The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook: + +```yaml +# Valid values: CRITICAL, ERROR, WARNING, INFO, DEBUG +matrix_bot_maubot_logging_level: DEBUG +``` diff --git a/docs/configuring-playbook-bridge-appservice-irc.md b/docs/configuring-playbook-bridge-appservice-irc.md index af4003f6d..da655a77b 100644 --- a/docs/configuring-playbook-bridge-appservice-irc.md +++ b/docs/configuring-playbook-bridge-appservice-irc.md @@ -60,6 +60,15 @@ matrix_appservice_irc_ircService_servers: lineLimit: 3 ``` +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + +Take a look at: + +- `roles/custom/matrix-bridge-appservice-irc/defaults/main.yml` for some variables that you can customize via your `vars.yml` file +- `roles/custom/matrix-bridge-appservice-irc/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_irc_configuration_extension_yaml` variable + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: @@ -80,3 +89,23 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage To use the bridge, you need to start a chat with `@irc_bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-appservice-irc`. + +### Configuring for logging + +The default logging level for this component is `debug`, and the log is output to the console only. If you want to change the verbosity or enable logging to a file, add the following configuration to your `vars.yml` file (adapt to your needs) and re-run the playbook: + +```yaml +matrix_appservice_irc_configuration_extension_yaml: | + logging: + # Level to log on console/logfile. + # Valid values: error, warn, info, debug + level: "debug" + # The file location to log to. This is relative to the project directory. + logfile: "debug.log" + # The file location to log errors to. This is relative to the project directory. + errfile: "errors.log" +``` diff --git a/docs/configuring-playbook-bridge-appservice-webhooks.md b/docs/configuring-playbook-bridge-appservice-webhooks.md index e4d212f46..c57e1239f 100644 --- a/docs/configuring-playbook-bridge-appservice-webhooks.md +++ b/docs/configuring-playbook-bridge-appservice-webhooks.md @@ -24,6 +24,15 @@ matrix_appservice_webhooks_api_secret: '' # use_appservice_legacy_authorization: true ``` +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + +Take a look at: + +- `roles/custom/matrix-bridge-appservice-webhooks/defaults/main.yml` for some variables that you can customize via your `vars.yml` file +- `roles/custom/matrix-bridge-appservice-webhooks/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_webhooks_configuration_extension_yaml` variable + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: @@ -85,3 +94,16 @@ If you're using the [Dimension integration manager](configuring-playbook-dimensi To configure it, open the Dimension integration manager, and go to "Settings" and "Bridges", then select edit action for "Webhook Bridge". On the UI, press "Add self-hosted Bridge" button and populate "Provisioning URL" and "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively. + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-appservice-webhooks`. + +### Increase logging verbosity + +The default logging level for this component is `info`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook: + +```yaml +# Valid values: info, verbose +matrix_appservice_webhooks_log_level: 'verbose' +``` diff --git a/docs/configuring-playbook-bridge-go-skype-bridge.md b/docs/configuring-playbook-bridge-go-skype-bridge.md index 62d1eb77b..22ec97905 100644 --- a/docs/configuring-playbook-bridge-go-skype-bridge.md +++ b/docs/configuring-playbook-bridge-go-skype-bridge.md @@ -50,3 +50,16 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage To use the bridge, you need to start a chat with `@skypebridgebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-go-skype-bridge`. + +### Increase logging verbosity + +The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook: + +```yaml +# Valid values: fatal, error, warn, info, debug +matrix_go_skype_bridge_log_level: 'info' +``` diff --git a/docs/configuring-playbook-bridge-heisenbridge.md b/docs/configuring-playbook-bridge-heisenbridge.md index d3a08fb82..d8f0dcde6 100644 --- a/docs/configuring-playbook-bridge-heisenbridge.md +++ b/docs/configuring-playbook-bridge-heisenbridge.md @@ -43,6 +43,14 @@ If you've changed the default hostname, you may need to create a CNAME record fo When setting, replace `example.com` with your own. +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + +Take a look at: + +- `roles/custom/matrix-bridge-heisenbridge/defaults/main.yml` for some variables that you can customize via your `vars.yml` file + ## Installing After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below: @@ -69,3 +77,7 @@ Help is available for all commands with the `-h` switch. You can also learn the basics by watching [this demonstration video](https://www.youtube.com/watch?v=nQk1Bp4tk4I). If you encounter issues or feel lost you can join the project room at [#heisenbridge:vi.fi](https://matrix.to/#/#heisenbridge:vi.fi) for help. + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-heisenbridge`. diff --git a/docs/configuring-playbook-bridge-matrix-bridge-sms.md b/docs/configuring-playbook-bridge-matrix-bridge-sms.md index 7f58a74cd..5ea15577d 100644 --- a/docs/configuring-playbook-bridge-matrix-bridge-sms.md +++ b/docs/configuring-playbook-bridge-matrix-bridge-sms.md @@ -33,6 +33,14 @@ matrix_sms_bridge_provider_android_truststore_password: 123 ``` +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + +Take a look at: + +- `roles/custom/matrix-bridge-sms/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_sms_bridge_configuration_extension_yaml` variable + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: @@ -53,3 +61,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage Read the [user guide](https://github.com/benkuly/matrix-sms-bridge/blob/master/README.md#user-guide) to see how this bridge works. + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-sms-bridge`. diff --git a/docs/configuring-playbook-dynamic-dns.md b/docs/configuring-playbook-dynamic-dns.md index 7108e8b65..6db0e941d 100644 --- a/docs/configuring-playbook-dynamic-dns.md +++ b/docs/configuring-playbook-dynamic-dns.md @@ -23,6 +23,14 @@ matrix_dynamic_dns_domain_configurations: domain: "{{ matrix_domain }}" ``` +### Extending the configuration + +There are some additional things you may wish to configure about the component. + +Take a look at: + +- `roles/custom/matrix-dynamic-dns/defaults/main.yml` for some variables that you can customize via your `vars.yml` file + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: @@ -41,3 +49,7 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju Additional resources: - https://matrix.org/docs/guides/free-small-matrix-server + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-dynamic-dns`. diff --git a/docs/configuring-playbook-matrix-authentication-service.md b/docs/configuring-playbook-matrix-authentication-service.md index ee8960352..ad2fb8b7f 100644 --- a/docs/configuring-playbook-matrix-authentication-service.md +++ b/docs/configuring-playbook-matrix-authentication-service.md @@ -276,6 +276,15 @@ matrix_authentication_service_config_upstream_oauth2_providers: - go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process - remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration +### Extending the configuration + +There are some additional things you may wish to configure about the component. + +Take a look at: + +- `roles/custom/matrix-authentication-service/defaults/main.yml` for some variables that you can customize via your `vars.yml` file +- `roles/custom/matrix-authentication-service/templates/config.yaml.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_authentication_service_configuration_extension_yaml` variable + ## Installing Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below: @@ -428,7 +437,9 @@ If successful, you should see some output that looks like this: ✅ The legacy login API at "https://matrix.example.com/_matrix/client/v3/login" is reachable and is handled by MAS. ``` -## Management +## Usage + +### Management You can use the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) (exposed via the `/matrix/matrix-authentication-service/bin/mas-cli` script) to perform administrative tasks against MAS. @@ -440,13 +451,13 @@ This documentation page already mentions: There are other sub-commands available. Run `/matrix/matrix-authentication-service/bin/mas-cli` to get an overview. -## User registration +### User registration After Matrix Authentication Service is [installed](#installing), users need to be managed there (unless you're managing them in an [upstream OAuth2 provider](#upstream-oauth2-configuration)). You can register users new users as described in the [Registering users](./registering-users.md) documentation (via `mas-cli manage register-user` or the Ansible playbook's `register-user` tag). -## Working around email deliverability issues +### Working around email deliverability issues Because Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user, you may need to work around email deliverability issues if [your email-sending configuration](./configuring-playbook-email.md) is not working. @@ -455,3 +466,7 @@ Matrix Authentication Service attempts to verify email addresses by sending a ve If email delivery is not working, **you can retrieve the email configuration code from the Matrix Authentication Service's logs** (`journalctl -fu matrix-authentication-service`). Alternatively, you can use the [`mas-cli` management tool](#management) to manually verify email addresses for users. Example: `/matrix/matrix-authentication-service/bin/mas-cli manage verify-email some.username email@example.com` + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-authentication-service`. diff --git a/docs/configuring-playbook-matrix-corporal.md b/docs/configuring-playbook-matrix-corporal.md index 03bf7b22f..1e387e046 100644 --- a/docs/configuring-playbook-matrix-corporal.md +++ b/docs/configuring-playbook-matrix-corporal.md @@ -116,6 +116,15 @@ aux_file_definitions: To learn more about what the policy configuration, see the matrix-corporal documentation on [policy](https://github.com/devture/matrix-corporal/blob/master/docs/policy.md). +### Extending the configuration + +There are some additional things you may wish to configure about the component. + +Take a look at: + +- `roles/custom/matrix-corporal/defaults/main.yml` for some variables that you can customize via your `vars.yml` file +- `roles/custom/matrix-corporal/templates/config.json.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_corporal_configuration_extension_json` variable + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: @@ -140,3 +149,15 @@ The following local filesystem paths are mounted in the `matrix-corporal` contai - `/matrix/corporal/cache` is mounted at `/var/cache/matrix-corporal` (read and write) As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config`) needs to refer to these files via the local container paths — `/etc/matrix-corporal` (read-only), `/var/matrix-corporal` (read and write), `/var/cache/matrix-corporal` (read and write). + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-corporal`. + +### Increase logging verbosity + +If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook: + +```yaml +matrix_corporal_debug: true +``` diff --git a/docs/configuring-playbook-matrix-registration.md b/docs/configuring-playbook-matrix-registration.md index 311be8fb7..e46fbc652 100644 --- a/docs/configuring-playbook-matrix-registration.md +++ b/docs/configuring-playbook-matrix-registration.md @@ -47,6 +47,15 @@ If you've changed the default hostname, you may need to create a CNAME record fo When setting, replace `example.com` with your own. +### Extending the configuration + +There are some additional things you may wish to configure about the component. + +Take a look at: + +- `roles/custom/matrix-registration/defaults/main.yml` for some variables that you can customize via your `vars.yml` file +- `roles/custom/matrix-registration/templates/config.yaml.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_registration_configuration_extension_yaml` variable + ## Installing After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below: @@ -92,3 +101,7 @@ ansible-playbook -i inventory/hosts setup.yml \ ``` The shortcut command with `just` program is also available: `just run-tags list-matrix-registration-tokens` + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-registration`. diff --git a/roles/custom/matrix-bridge-appservice-irc/templates/config.yaml.j2 b/roles/custom/matrix-bridge-appservice-irc/templates/config.yaml.j2 index 0f9d491d6..8b7aca5b8 100644 --- a/roles/custom/matrix-bridge-appservice-irc/templates/config.yaml.j2 +++ b/roles/custom/matrix-bridge-appservice-irc/templates/config.yaml.j2 @@ -74,12 +74,12 @@ ircService: # Configuration for logging. Optional. Default: console debug level logging # only. logging: - # Level to log on console/logfile. One of error|warn|info|debug + # Level to log on console/logfile. + # Valid values: error, warn, info, debug level: "debug" # The file location to log to. This is relative to the project directory. #logfile: "debug.log" - # The file location to log errors to. This is relative to the project - # directory. + # The file location to log errors to. This is relative to the project directory. #errfile: "errors.log" # Whether to log to the console or not. toConsole: true diff --git a/roles/custom/matrix-bridge-appservice-webhooks/defaults/main.yml b/roles/custom/matrix-bridge-appservice-webhooks/defaults/main.yml index 840c0b214..aaa8d564f 100644 --- a/roles/custom/matrix-bridge-appservice-webhooks/defaults/main.yml +++ b/roles/custom/matrix-bridge-appservice-webhooks/defaults/main.yml @@ -94,7 +94,7 @@ matrix_appservice_webhooks_homeserver_token: '' matrix_appservice_webhooks_id_token: '' matrix_appservice_webhooks_api_secret: '' -# Logging information (info and verbose is available) default is: info +# Valid values: info, verbose matrix_appservice_webhooks_log_level: 'info' matrix_appservice_webhooks_configuration_yaml: "{{ lookup('template', 'templates/config.yaml.j2') }}" diff --git a/roles/custom/matrix-bridge-go-skype-bridge/defaults/main.yml b/roles/custom/matrix-bridge-go-skype-bridge/defaults/main.yml index d0cead0e3..a8e29d547 100644 --- a/roles/custom/matrix-bridge-go-skype-bridge/defaults/main.yml +++ b/roles/custom/matrix-bridge-go-skype-bridge/defaults/main.yml @@ -101,7 +101,7 @@ matrix_go_skype_bridge_bridge_encryption_allow: "{{ matrix_bridges_encryption_en matrix_go_skype_bridge_bridge_encryption_default: "{{ matrix_bridges_encryption_default }}" # Minimum severity of journal log messages. -# Options: debug, info, warn, error, fatal +# Valid values: fatal, error, warn, info, debug matrix_go_skype_bridge_log_level: 'warn' matrix_go_skype_bridge_bridge_permissions: |