From c3fb7ebf4c3167015df27c496764904f4b39fc64 Mon Sep 17 00:00:00 2001 From: Noah Fleischmann Date: Mon, 21 Oct 2019 20:06:57 +0200 Subject: [PATCH 1/6] Add variable for mxisd verbose logging --- roles/matrix-mxisd/defaults/main.yml | 9 +++++++-- .../templates/systemd/matrix-mxisd.service.j2 | 3 +++ 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/roles/matrix-mxisd/defaults/main.yml b/roles/matrix-mxisd/defaults/main.yml index 40eab830e..fbc378dba 100644 --- a/roles/matrix-mxisd/defaults/main.yml +++ b/roles/matrix-mxisd/defaults/main.yml @@ -13,13 +13,13 @@ matrix_mxisd_data_path: "{{ matrix_mxisd_base_path }}/data" # Controls whether the matrix-mxisd container exposes its HTTP port (tcp/8090 in the container). # # Takes an ":" or "" value (e.g. "127.0.0.1:8090"), or empty string to not expose. -matrix_mxisd_container_http_host_bind_port: '' +matrix_mxisd_container_http_host_bind_port: "" # A list of extra arguments to pass to the container matrix_mxisd_container_extra_arguments: [] # List of systemd services that matrix-mxisd.service depends on -matrix_mxisd_systemd_required_services_list: ['docker.service'] +matrix_mxisd_systemd_required_services_list: ["docker.service"] # List of systemd services that matrix-mxisd.service wants matrix_mxisd_systemd_wanted_services_list: [] @@ -68,6 +68,11 @@ matrix_mxisd_threepid_medium_email_custom_matrixid_template: "" # Controls whether the self-check feature should validate SSL certificates. matrix_mxisd_self_check_validate_certificates: true +# Controls mxisd logging verbosity for troubleshooting. +# +# According to: https://github.com/kamax-matrix/mxisd/blob/master/docs/troubleshooting.md#increase-verbosity +matrix_mxisd_verbose_logging: true + # Default mxisd configuration template which covers the generic use case. # You can customize it by controlling the various variables inside it. # diff --git a/roles/matrix-mxisd/templates/systemd/matrix-mxisd.service.j2 b/roles/matrix-mxisd/templates/systemd/matrix-mxisd.service.j2 index 09ebb05d1..d60740f52 100644 --- a/roles/matrix-mxisd/templates/systemd/matrix-mxisd.service.j2 +++ b/roles/matrix-mxisd/templates/systemd/matrix-mxisd.service.j2 @@ -26,6 +26,9 @@ ExecStart=/usr/bin/docker run --rm --name matrix-mxisd \ {% if matrix_mxisd_container_http_host_bind_port %} -p {{ matrix_mxisd_container_http_host_bind_port }}:8090 \ {% endif %} + {% if matrix_mxisd_verbose_logging %} + -e MXISD_LOG_LEVEL=debug \ + {% endif %} -v {{ matrix_mxisd_config_path }}:/etc/mxisd:ro \ -v {{ matrix_mxisd_data_path }}:/var/mxisd:rw \ {% for arg in matrix_mxisd_container_extra_arguments %} From 852fceb33f796071cea51272736a625a1f392efa Mon Sep 17 00:00:00 2001 From: Noah Fleischmann Date: Mon, 21 Oct 2019 20:11:00 +0200 Subject: [PATCH 2/6] Add documentation --- docs/configuring-playbook-mxisd.md | 21 ++++++++++++--------- docs/maintenance-and-troubleshooting.md | 8 ++++++-- roles/matrix-mxisd/defaults/main.yml | 2 +- 3 files changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/configuring-playbook-mxisd.md b/docs/configuring-playbook-mxisd.md index 3b0d5700c..957f94668 100644 --- a/docs/configuring-playbook-mxisd.md +++ b/docs/configuring-playbook-mxisd.md @@ -4,7 +4,6 @@ By default, this playbook configures an [mxisd](https://github.com/kamax-io/mxis This server is private by default, potentially at the expense of user discoverability. - ## Matrix.org lookup forwarding To ensure maximum discovery, you can make your identity server also forward lookups to the central matrix.org Identity server (at the cost of potentially leaking all your contacts information). @@ -17,25 +16,22 @@ Enabling matrix.org forwarding can happen with the following configuration: matrix_mxisd_matrixorg_forwarding_enabled: true ``` - ## Customizing email templates If you'd like to change the default email templates used by mxisd, take a look at the `matrix_mxisd_threepid_medium_email_custom_` variables (in the `roles/matrix-mxisd/defaults/main.yml` file. - ## mxisd-controlled Registration To use the [Registration](https://github.com/kamax-matrix/mxisd/blob/master/docs/features/registration.md) feature of mxisd, you can make use of the following variables: -- `matrix_synapse_enable_registration` - to enable user-initiated registration in Synapse +- `matrix_synapse_enable_registration` - to enable user-initiated registration in Synapse -- `matrix_synapse_registrations_require_3pid` - to control the types of 3pid (`'email'`, `'msisdn'`) required by the Synapse server for registering +- `matrix_synapse_registrations_require_3pid` - to control the types of 3pid (`'email'`, `'msisdn'`) required by the Synapse server for registering -- variables prefixed with `matrix_nginx_proxy_proxy_matrix_3pid_registration_` (e.g. `matrix_nginx_proxy_proxy_matrix_3pid_registration_enabled`) - to configure the integrated nginx webserver to send registration requests to mxisd (instead of Synapse), so it can apply its additional functionality - -- `matrix_mxisd_configuration_extension_yaml` - to configure mxisd as required. See the [Registration feature's docs](https://github.com/kamax-matrix/mxisd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_mxisd_configuration_extension_yaml`. +- variables prefixed with `matrix_nginx_proxy_proxy_matrix_3pid_registration_` (e.g. `matrix_nginx_proxy_proxy_matrix_3pid_registration_enabled`) - to configure the integrated nginx webserver to send registration requests to mxisd (instead of Synapse), so it can apply its additional functionality +- `matrix_mxisd_configuration_extension_yaml` - to configure mxisd as required. See the [Registration feature's docs](https://github.com/kamax-matrix/mxisd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_mxisd_configuration_extension_yaml`. ## Additional features @@ -50,7 +46,14 @@ To use a more custom configuration, you can define a `matrix_mxisd_configuration and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_mxisd_configuration_extension_yaml` in the [default variables file](../roles/matrix-mxisd/defaults/main.yml) of the mxisd component. - ## Troubleshooting If email address validation emails sent by mxisd are not reaching you, you should look into [Adjusting email-sending settings](configuring-playbook-email.md). + +If you'd like additional logging information, temporarily enable verbose logging for mxisd. + +Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`): + +```yaml +matrix_mxisd_verbose_logging: true +``` diff --git a/docs/maintenance-and-troubleshooting.md b/docs/maintenance-and-troubleshooting.md index 18bfdd837..ef3a10de9 100644 --- a/docs/maintenance-and-troubleshooting.md +++ b/docs/maintenance-and-troubleshooting.md @@ -3,6 +3,7 @@ ## How to see the current status of your services You can check the status of your services by using `systemctl status`. Example: + ``` sudo systemctl status matrix-nginx-proxy @@ -12,11 +13,11 @@ sudo systemctl status matrix-nginx-proxy ``` You can see the logs by using journalctl. Example: + ``` sudo journalctl -fu matrix-synapse ``` - ## Increasing Synapse logging Because the [Synapse](https://github.com/matrix-org/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`. @@ -33,7 +34,10 @@ matrix_synapse_root_log_level: "INFO" Re-run the playbook after making these configuration changes. - ## Postgres See the dedicated [PostgreSQL Maintenance](maintenance-postgres.md) documentation page. + +## Mxisd + +See the dedicated [Adjusting mxisd Identity Server configuration](configuring-playbook-mxisd.md) documentation page diff --git a/roles/matrix-mxisd/defaults/main.yml b/roles/matrix-mxisd/defaults/main.yml index fbc378dba..342497c80 100644 --- a/roles/matrix-mxisd/defaults/main.yml +++ b/roles/matrix-mxisd/defaults/main.yml @@ -71,7 +71,7 @@ matrix_mxisd_self_check_validate_certificates: true # Controls mxisd logging verbosity for troubleshooting. # # According to: https://github.com/kamax-matrix/mxisd/blob/master/docs/troubleshooting.md#increase-verbosity -matrix_mxisd_verbose_logging: true +matrix_mxisd_verbose_logging: false # Default mxisd configuration template which covers the generic use case. # You can customize it by controlling the various variables inside it. From 9728bdffee4840160bb70bb40c249d316d27f5b4 Mon Sep 17 00:00:00 2001 From: Noah Fleischmann Date: Mon, 21 Oct 2019 20:41:45 +0200 Subject: [PATCH 3/6] Undo auto formatting --- roles/matrix-mxisd/defaults/main.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/roles/matrix-mxisd/defaults/main.yml b/roles/matrix-mxisd/defaults/main.yml index 342497c80..57371d279 100644 --- a/roles/matrix-mxisd/defaults/main.yml +++ b/roles/matrix-mxisd/defaults/main.yml @@ -13,13 +13,13 @@ matrix_mxisd_data_path: "{{ matrix_mxisd_base_path }}/data" # Controls whether the matrix-mxisd container exposes its HTTP port (tcp/8090 in the container). # # Takes an ":" or "" value (e.g. "127.0.0.1:8090"), or empty string to not expose. -matrix_mxisd_container_http_host_bind_port: "" +matrix_mxisd_container_http_host_bind_port: '' # A list of extra arguments to pass to the container matrix_mxisd_container_extra_arguments: [] # List of systemd services that matrix-mxisd.service depends on -matrix_mxisd_systemd_required_services_list: ["docker.service"] +matrix_mxisd_systemd_required_services_list: ['docker.service'] # List of systemd services that matrix-mxisd.service wants matrix_mxisd_systemd_wanted_services_list: [] @@ -71,7 +71,7 @@ matrix_mxisd_self_check_validate_certificates: true # Controls mxisd logging verbosity for troubleshooting. # # According to: https://github.com/kamax-matrix/mxisd/blob/master/docs/troubleshooting.md#increase-verbosity -matrix_mxisd_verbose_logging: false +matrix_mxisd_verbose_logging: true # Default mxisd configuration template which covers the generic use case. # You can customize it by controlling the various variables inside it. From 1df3d5324329d36c9b49f468b41c5bc5212b225c Mon Sep 17 00:00:00 2001 From: Noah Fleischmann Date: Mon, 21 Oct 2019 20:47:23 +0200 Subject: [PATCH 4/6] Verbose logging should be off per default --- roles/matrix-mxisd/defaults/main.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/roles/matrix-mxisd/defaults/main.yml b/roles/matrix-mxisd/defaults/main.yml index 57371d279..342497c80 100644 --- a/roles/matrix-mxisd/defaults/main.yml +++ b/roles/matrix-mxisd/defaults/main.yml @@ -13,13 +13,13 @@ matrix_mxisd_data_path: "{{ matrix_mxisd_base_path }}/data" # Controls whether the matrix-mxisd container exposes its HTTP port (tcp/8090 in the container). # # Takes an ":" or "" value (e.g. "127.0.0.1:8090"), or empty string to not expose. -matrix_mxisd_container_http_host_bind_port: '' +matrix_mxisd_container_http_host_bind_port: "" # A list of extra arguments to pass to the container matrix_mxisd_container_extra_arguments: [] # List of systemd services that matrix-mxisd.service depends on -matrix_mxisd_systemd_required_services_list: ['docker.service'] +matrix_mxisd_systemd_required_services_list: ["docker.service"] # List of systemd services that matrix-mxisd.service wants matrix_mxisd_systemd_wanted_services_list: [] @@ -71,7 +71,7 @@ matrix_mxisd_self_check_validate_certificates: true # Controls mxisd logging verbosity for troubleshooting. # # According to: https://github.com/kamax-matrix/mxisd/blob/master/docs/troubleshooting.md#increase-verbosity -matrix_mxisd_verbose_logging: true +matrix_mxisd_verbose_logging: false # Default mxisd configuration template which covers the generic use case. # You can customize it by controlling the various variables inside it. From 64370cb58b13294d8bd544266153e1e6930ef7ea Mon Sep 17 00:00:00 2001 From: fnoah Date: Tue, 22 Oct 2019 09:54:13 +0200 Subject: [PATCH 5/6] Fix formatting issues --- docs/configuring-playbook-mxisd.md | 15 ++++++++++----- docs/maintenance-and-troubleshooting.md | 6 +++--- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/configuring-playbook-mxisd.md b/docs/configuring-playbook-mxisd.md index 957f94668..2f5806bb3 100644 --- a/docs/configuring-playbook-mxisd.md +++ b/docs/configuring-playbook-mxisd.md @@ -4,6 +4,7 @@ By default, this playbook configures an [mxisd](https://github.com/kamax-io/mxis This server is private by default, potentially at the expense of user discoverability. + ## Matrix.org lookup forwarding To ensure maximum discovery, you can make your identity server also forward lookups to the central matrix.org Identity server (at the cost of potentially leaking all your contacts information). @@ -16,22 +17,25 @@ Enabling matrix.org forwarding can happen with the following configuration: matrix_mxisd_matrixorg_forwarding_enabled: true ``` + ## Customizing email templates If you'd like to change the default email templates used by mxisd, take a look at the `matrix_mxisd_threepid_medium_email_custom_` variables (in the `roles/matrix-mxisd/defaults/main.yml` file. + ## mxisd-controlled Registration To use the [Registration](https://github.com/kamax-matrix/mxisd/blob/master/docs/features/registration.md) feature of mxisd, you can make use of the following variables: -- `matrix_synapse_enable_registration` - to enable user-initiated registration in Synapse +- `matrix_synapse_enable_registration` - to enable user-initiated registration in Synapse -- `matrix_synapse_registrations_require_3pid` - to control the types of 3pid (`'email'`, `'msisdn'`) required by the Synapse server for registering +- `matrix_synapse_registrations_require_3pid` - to control the types of 3pid (`'email'`, `'msisdn'`) required by the Synapse server for registering -- variables prefixed with `matrix_nginx_proxy_proxy_matrix_3pid_registration_` (e.g. `matrix_nginx_proxy_proxy_matrix_3pid_registration_enabled`) - to configure the integrated nginx webserver to send registration requests to mxisd (instead of Synapse), so it can apply its additional functionality +- variables prefixed with `matrix_nginx_proxy_proxy_matrix_3pid_registration_` (e.g. `matrix_nginx_proxy_proxy_matrix_3pid_registration_enabled`) - to configure the integrated nginx webserver to send registration requests to mxisd (instead of Synapse), so it can apply its additional functionality + +- `matrix_mxisd_configuration_extension_yaml` - to configure mxisd as required. See the [Registration feature's docs](https://github.com/kamax-matrix/mxisd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_mxisd_configuration_extension_yaml`. -- `matrix_mxisd_configuration_extension_yaml` - to configure mxisd as required. See the [Registration feature's docs](https://github.com/kamax-matrix/mxisd/blob/master/docs/features/registration.md) for inspiration. Also see the [Additional features](#additional-features) section below to learn more about how to use `matrix_mxisd_configuration_extension_yaml`. ## Additional features @@ -46,6 +50,7 @@ To use a more custom configuration, you can define a `matrix_mxisd_configuration and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_mxisd_configuration_extension_yaml` in the [default variables file](../roles/matrix-mxisd/defaults/main.yml) of the mxisd component. + ## Troubleshooting If email address validation emails sent by mxisd are not reaching you, you should look into [Adjusting email-sending settings](configuring-playbook-email.md). @@ -56,4 +61,4 @@ Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`): ```yaml matrix_mxisd_verbose_logging: true -``` +``` \ No newline at end of file diff --git a/docs/maintenance-and-troubleshooting.md b/docs/maintenance-and-troubleshooting.md index ef3a10de9..5dd1ee3f5 100644 --- a/docs/maintenance-and-troubleshooting.md +++ b/docs/maintenance-and-troubleshooting.md @@ -3,7 +3,6 @@ ## How to see the current status of your services You can check the status of your services by using `systemctl status`. Example: - ``` sudo systemctl status matrix-nginx-proxy @@ -13,11 +12,11 @@ sudo systemctl status matrix-nginx-proxy ``` You can see the logs by using journalctl. Example: - ``` sudo journalctl -fu matrix-synapse ``` + ## Increasing Synapse logging Because the [Synapse](https://github.com/matrix-org/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`. @@ -34,10 +33,11 @@ matrix_synapse_root_log_level: "INFO" Re-run the playbook after making these configuration changes. + ## Postgres See the dedicated [PostgreSQL Maintenance](maintenance-postgres.md) documentation page. ## Mxisd -See the dedicated [Adjusting mxisd Identity Server configuration](configuring-playbook-mxisd.md) documentation page +See the dedicated [Adjusting mxisd Identity Server configuration](configuring-playbook-mxisd.md) documentation page. \ No newline at end of file From e81837a5863f670bcbddbe6e1f49e244921e2bbb Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Tue, 22 Oct 2019 10:57:16 +0300 Subject: [PATCH 6/6] Undo some formatting changes --- roles/matrix-mxisd/defaults/main.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/roles/matrix-mxisd/defaults/main.yml b/roles/matrix-mxisd/defaults/main.yml index 342497c80..286839dab 100644 --- a/roles/matrix-mxisd/defaults/main.yml +++ b/roles/matrix-mxisd/defaults/main.yml @@ -13,13 +13,13 @@ matrix_mxisd_data_path: "{{ matrix_mxisd_base_path }}/data" # Controls whether the matrix-mxisd container exposes its HTTP port (tcp/8090 in the container). # # Takes an ":" or "" value (e.g. "127.0.0.1:8090"), or empty string to not expose. -matrix_mxisd_container_http_host_bind_port: "" +matrix_mxisd_container_http_host_bind_port: '' # A list of extra arguments to pass to the container matrix_mxisd_container_extra_arguments: [] # List of systemd services that matrix-mxisd.service depends on -matrix_mxisd_systemd_required_services_list: ["docker.service"] +matrix_mxisd_systemd_required_services_list: ['docker.service'] # List of systemd services that matrix-mxisd.service wants matrix_mxisd_systemd_wanted_services_list: []