diff --git a/CHANGELOG.md b/CHANGELOG.md index c4ed7684f..76e304903 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,12 @@ +# 2018-08-21 + +## Matrix Corporal support + +The playbook can now install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you. + +Additional details are available in [Setting up Matrix Corporal](docs/configuring-playbook-matrix-corporal.md). + + # 2018-08-20 ## Matrix Synapse rate limit control variables diff --git a/docs/configuring-playbook-matrix-corporal.md b/docs/configuring-playbook-matrix-corporal.md new file mode 100644 index 000000000..f38725d8e --- /dev/null +++ b/docs/configuring-playbook-matrix-corporal.md @@ -0,0 +1,37 @@ +# Setting up Matrix Corporal + +The playbook can install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you. + +See that project's documentation to learn what it does and why it might be useful to you. + +If you decide that you'd like to let this playbook install it for you, you'd need to also [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md). + +You would then need some configuration like this: + +```yaml +matrix_corporal_enabled: true + +matrix_corporal_policy_provider_config: | + { + "Type": "http", + "Uri": "https://intranet.example.com/matrix/policy", + "AuthorizationBearerToken": "SOME_SECRET", + "CachePath": "/var/cache/matrix-corporal/last-policy.json", + "ReloadIntervalSeconds": 1800 + } + +# If you also want to enable Matrix Corporal's HTTP API.. +matrix_corporal_http_api_enabled: true +matrix_corporal_http_api_auth_token: "AUTH_TOKEN_HERE" + +# If you need to change the reconciliator user's id from the default (matrix-corporal).. +matrix_corporal_reconciliation_user_id_local_part: "matrix-corporal" +``` + +The following local filesystem paths are mounted in the `matrix-corporal` container and can be used in your configuration (or policy): + +- `/matrix/corporal/config` is mounted at `/etc/matrix-corporal` (read-only) + +- `/matrix/corporal/var` is mounted at `/var/matrix-corporal` (read and write) + +- `/matrix/corporal/cache` is mounted at `/var/cache/matrix-corporal` (read and write) diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 0f7f0e510..fe71eeb64 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -35,4 +35,6 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional) -- [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional) \ No newline at end of file +- [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional) + +- [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional) \ No newline at end of file diff --git a/roles/matrix-server/defaults/main.yml b/roles/matrix-server/defaults/main.yml index de0307044..02c6051e9 100644 --- a/roles/matrix-server/defaults/main.yml +++ b/roles/matrix-server/defaults/main.yml @@ -174,6 +174,29 @@ matrix_mxisd_matrixorg_forwarding_enabled: false matrix_mxisd_template_config: "{{ role_path }}/templates/mxisd/mxisd.yaml.j2" +# Enable this to add support for matrix-corporal. +# See: https://github.com/devture/matrix-corporal +matrix_corporal_enabled: false + +matrix_corporal_docker_image: "devture/matrix-corporal:1.0" +matrix_corporal_base_path: "{{ matrix_base_data_path }}/corporal" +matrix_corporal_config_dir_path: "{{ matrix_corporal_base_path }}/config" +matrix_corporal_cache_dir_path: "{{ matrix_corporal_base_path }}/cache" +matrix_corporal_var_dir_path: "{{ matrix_corporal_base_path }}/var" + +matrix_corporal_matrix_timeout_milliseconds: 30000 + +matrix_corporal_reconciliation_retry_interval_milliseconds: 30000 +matrix_corporal_reconciliation_user_id_local_part: "matrix-corporal" + +matrix_corporal_http_api_enabled: false +matrix_corporal_http_api_auth_token: "" + +# Matrix Corporal policy provider configuration (goes directly into the configuration's `PolicyProvider` value) +matrix_corporal_policy_provider_config: "" + +matrix_corporal_debug: false + # By default, this playbook installs the Riot.IM web UI on the `hostname_riot` domain. # If you wish to connect to your Matrix server by other means, # you may wish to disable this. @@ -188,9 +211,15 @@ matrix_riot_web_default_identity_server_url: "https://{{ matrix_synapse_trusted_ # and take care of proxying by yourself. matrix_nginx_proxy_enabled: true +# The addresses where the Matrix Client API is. +# Certain extensions (like matrix-corporal) may override this in order to capture all traffic. +matrix_nginx_proxy_matrix_client_api_addr_with_proxy_container: "matrix-synapse:8008" +matrix_nginx_proxy_matrix_client_api_addr_sans_proxy_container: "localhost:8008" + + # Specifies when to attempt to retrieve new SSL certificates from Let's Encrypt. matrix_ssl_renew_cron_time_definition: "15 4 */5 * *" # Specifies when to reload the matrix-nginx-proxy service so that # a new SSL certificate could go into effect. -matrix_nginx_proxy_reload_cron_time_definition: "20 4 */5 * *" \ No newline at end of file +matrix_nginx_proxy_reload_cron_time_definition: "20 4 */5 * *" diff --git a/roles/matrix-server/tasks/main.yml b/roles/matrix-server/tasks/main.yml index c1447b237..726f58fb0 100644 --- a/roles/matrix-server/tasks/main.yml +++ b/roles/matrix-server/tasks/main.yml @@ -47,6 +47,11 @@ - setup-all - setup-mxisd +- include: tasks/setup_corporal.yml + tags: + - setup-all + - setup-corporal + - include: tasks/setup_synapse.yml tags: - setup-all diff --git a/roles/matrix-server/tasks/setup_corporal.yml b/roles/matrix-server/tasks/setup_corporal.yml new file mode 100644 index 000000000..d9446efb7 --- /dev/null +++ b/roles/matrix-server/tasks/setup_corporal.yml @@ -0,0 +1,68 @@ +--- + +# +# Tasks related to setting up matrix-corporal +# + +- name: Fail if Shared Secret Auth extension not enabled + fail: + msg: "To use matrix-corporal, you need to enable the Shared Secret Auth module for Synapse (see matrix_synapse_ext_password_provider_shared_secret_auth_enabled)" + when: "matrix_corporal_enabled and not matrix_synapse_ext_password_provider_shared_secret_auth_enabled" + +- name: Fail if HTTP API enabled, but no token set + fail: + msg: "The Matrix Corporal HTTP API is enabled, but no auth token has been set in matrix_corporal_http_api_auth_token" + when: "matrix_corporal_enabled and matrix_corporal_http_api_enabled and matrix_corporal_http_api_auth_token == ''" + +- name: Fail if policy provider configuration not set + fail: + msg: "The Matrix Corporal policy provider configuration has not been set in matrix_corporal_policy_provider_config" + when: "matrix_corporal_enabled and matrix_corporal_policy_provider_config == ''" + +- name: Override configuration specifying where the Matrix Client API is + set_fact: + matrix_nginx_proxy_matrix_client_api_addr_with_proxy_container: "matrix-corporal:41080" + matrix_nginx_proxy_matrix_client_api_addr_sans_proxy_container: "localhost:41080" + when: "matrix_corporal_enabled" + +- name: Ensure Matrix Corporal paths exist + file: + path: "{{ item }}" + state: directory + mode: 0750 + owner: "{{ matrix_user_username }}" + group: "{{ matrix_user_username }}" + with_items: + - "{{ matrix_corporal_config_dir_path }}" + - "{{ matrix_corporal_cache_dir_path }}" + - "{{ matrix_corporal_var_dir_path }}" + when: "matrix_corporal_enabled" + +- name: Ensure Matrix Corporal Docker image is pulled + docker_image: + name: "{{ matrix_corporal_docker_image }}" + when: "matrix_corporal_enabled" + +- name: Ensure Matrix Corporal config installed + template: + src: "{{ role_path }}/templates/corporal/config.json.j2" + dest: "{{ matrix_corporal_config_dir_path }}/config.json" + mode: 0644 + when: "matrix_corporal_enabled" + +- name: Ensure matrix-corporal.service installed + template: + src: "{{ role_path }}/templates/systemd/matrix-corporal.service.j2" + dest: "/etc/systemd/system/matrix-corporal.service" + mode: 0644 + when: "matrix_corporal_enabled" + +# +# Tasks related to getting rid of matrix-corporal (if it was previously enabled) +# + +- name: Ensure matrix-corporal.service doesn't exist + file: + path: "{{ role_path }}/templates/systemd/matrix-corporal.service.j2" + state: absent + when: "not matrix_corporal_enabled" diff --git a/roles/matrix-server/tasks/start.yml b/roles/matrix-server/tasks/start.yml index c2cedca43..5982ea642 100644 --- a/roles/matrix-server/tasks/start.yml +++ b/roles/matrix-server/tasks/start.yml @@ -28,4 +28,8 @@ - name: Ensure matrix-nginx-proxy autoruns and is restarted service: name=matrix-nginx-proxy enabled=yes state=restarted daemon_reload=yes - when: matrix_nginx_proxy_enabled + when: + +- name: Ensure matrix-corporal autoruns and is restarted + service: name=matrix-corporal enabled=yes state=restarted daemon_reload=yes + when: matrix_corporal_enabled diff --git a/roles/matrix-server/templates/corporal/config.json.j2 b/roles/matrix-server/templates/corporal/config.json.j2 new file mode 100644 index 000000000..f86560ba7 --- /dev/null +++ b/roles/matrix-server/templates/corporal/config.json.j2 @@ -0,0 +1,30 @@ +{ + "Matrix": { + "HomeserverDomainName": "{{ hostname_identity }}", + "HomeserverApiEndpoint": "http://matrix-synapse:8008", + "AuthSharedSecret": "{{ matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret }}", + "RegistrationSharedSecret": "{{ matrix_synapse_registration_shared_secret }}", + "TimeoutMilliseconds": {{ matrix_corporal_matrix_timeout_milliseconds }} + }, + + "Reconciliation": { + "UserId": "@{{ matrix_corporal_reconciliation_user_id_local_part }}:{{ hostname_identity }}", + "RetryIntervalMilliseconds": {{ matrix_corporal_reconciliation_retry_interval_milliseconds }} + }, + + "HttpGateway": { + "ListenAddress": "0.0.0.0:41080" + }, + + "HttpApi": { + "Enabled": {{ 'true' if matrix_corporal_http_api_enabled else 'false' }}, + "ListenAddress": "0.0.0.0:41081", + "AuthorizationBearerToken": "{{ matrix_corporal_http_api_auth_token }}" + }, + + "PolicyProvider": {{ matrix_corporal_policy_provider_config }}, + + "Misc": { + "Debug": {{ 'true' if matrix_corporal_debug else 'false' }} + } +} diff --git a/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2 b/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2 index b636080a0..74c692558 100644 --- a/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2 +++ b/roles/matrix-server/templates/nginx-conf.d/matrix-synapse.conf.j2 @@ -42,6 +42,20 @@ server { ssl_prefer_server_ciphers on; ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH"; + {% if matrix_corporal_enabled and matrix_corporal_http_api_enabled %} + location /_matrix/corporal { + {% if matrix_nginx_proxy_enabled %} + {# Use the embedded DNS resolver in Docker containers to discover the service #} + resolver 127.0.0.11 valid=5s; + set $backend "matrix-corporal:41081"; + proxy_pass http://$backend; + {% else %} + {# Generic configuration for use outside of our container setup #} + proxy_pass http://localhost:41081; + {% endif %} + } + {% endif %} + {% if matrix_mxisd_enabled %} location /_matrix/identity { {% if matrix_nginx_proxy_enabled %} @@ -60,11 +74,11 @@ server { {% if matrix_nginx_proxy_enabled %} {# Use the embedded DNS resolver in Docker containers to discover the service #} resolver 127.0.0.11 valid=5s; - set $backend "matrix-synapse:8008"; + set $backend "{{ matrix_nginx_proxy_matrix_client_api_addr_with_proxy_container }}"; proxy_pass http://$backend; {% else %} {# Generic configuration for use outside of our container setup #} - proxy_pass http://localhost:8008; + proxy_pass http://{{ matrix_nginx_proxy_matrix_client_api_addr_sans_proxy_container }}; {% endif %} proxy_set_header X-Forwarded-For $remote_addr; diff --git a/roles/matrix-server/templates/systemd/matrix-corporal.service.j2 b/roles/matrix-server/templates/systemd/matrix-corporal.service.j2 new file mode 100644 index 000000000..2038bc983 --- /dev/null +++ b/roles/matrix-server/templates/systemd/matrix-corporal.service.j2 @@ -0,0 +1,30 @@ +[Unit] +Description=Matrix Corporal +After=docker.service +Requires=docker.service +Requires=matrix-synapse.service +After=matrix-synapse.service + +[Service] +Type=simple +ExecStartPre=-/usr/bin/docker kill matrix-corporal +ExecStartPre=-/usr/bin/docker rm matrix-corporal +ExecStart=/usr/bin/docker run --rm --name matrix-corporal \ + --user={{ matrix_user_uid }}:{{ matrix_user_gid }} \ + --network={{ matrix_docker_network }} \ + {% if not matrix_nginx_proxy_enabled %} + -p 127.0.0.1:41080:41080 \ + -p 127.0.0.1:41081:41081 \ + {% endif %} + -v {{ matrix_corporal_config_dir_path }}:/etc/matrix-corporal:ro \ + -v {{ matrix_corporal_cache_dir_path }}:/var/cache/matrix-corporal:rw \ + -v {{ matrix_corporal_var_dir_path }}:/var/matrix-corporal:rw \ + {{ matrix_corporal_docker_image }} \ + /matrix-corporal -config=/etc/matrix-corporal/config.json +ExecStop=-/usr/bin/docker kill matrix-corporal +ExecStop=-/usr/bin/docker rm matrix-corporal +Restart=always +RestartSec=30 + +[Install] +WantedBy=multi-user.target diff --git a/roles/matrix-server/templates/systemd/matrix-nginx-proxy.service.j2 b/roles/matrix-server/templates/systemd/matrix-nginx-proxy.service.j2 index dc096d517..c4c06f200 100644 --- a/roles/matrix-server/templates/systemd/matrix-nginx-proxy.service.j2 +++ b/roles/matrix-server/templates/systemd/matrix-nginx-proxy.service.j2 @@ -3,6 +3,9 @@ Description=Matrix nginx proxy server After=docker.service Requires=docker.service Wants=matrix-synapse.service +{% if matrix_corporal_enabled %} +Wants=matrix-corporal.service +{% endif %} {% if matrix_riot_web_enabled %} Wants=matrix-riot-web.service {% endif %}