Add support for matrix-corporal

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

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)

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)
+- [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)

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 * *"
+matrix_nginx_proxy_reload_cron_time_definition: "20 4 */5 * *"

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

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"

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

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' }}
+	}
+}

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;

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

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 %}