plugins/modules/synapse_signing_key.md

@@ -8,7 +8,7 @@ Module to generate and manage synapse signing keys.
 ## Requirements
 
 - `python >= 3.9`
-- `signed_json >= 1.1.4`
+- (pip) `signed_json >= 1.1.4`
 
 
 ## Usage examples

roles/synapse/README.md

@@ -20,10 +20,21 @@ The following variables need to be populated:
 
 - `docker`
 - `podman`
+- `virtualenv` - Python virtual env supervised with `systemd`
 
 Set `synapse_deployment_method` to one of the supported deployment methods.
 The current default is `docker`.
 
-### Planned deployment methods
+### `virtualenv` deployment method
 
-- `venv` - Python virtual env supervised with `systemd`
+This deployment method installs a `systemd` service called `synapse.service` to
+control the homeserver process. The service depends on the `network.target` by
+default (see [`synapse_systemd_unit_after`](synapse/main/systemd.yml)), and
+uses the `default.target` as it's `WantedBy`
+(see [`synapse_systemd_install_wanted_by`](synapse/main/systemd.yml)).
+
+To only start synapse after, for example, services for redis and postgresql are up,
+set `synapse_systemd_unit_wants: [ "postgresql.service", "redis.service" ]`.
+
+> [!NOTE]
+> Requires `systemd >= 245` on the target machine

roles/synapse/defaults/main/main.yml

@@ -1,16 +1,17 @@
 ---
-
 synapse_user: synapse
+synapse_group: synapse
 synapse_version: "1.115.0"
 synapse_state: "present"
 synapse_deployment_method: "docker"
 
 synapse_base_path: /opt/synapse
-synapse_config_path: "{{ synapse_base_path }}/config"
+synapse_config_path: "/etc/synapse"
 synapse_data_path: "{{ synapse_base_path }}/data"
 synapse_media_store_path: "{{ synapse_data_path }}/media_store"
 synapse_log_path: "/var/log/synapse"
 synapse_homeserver_log_path: "{{ synapse_log_path }}/homeserver.log"
+synapse_venv_path: "{{ synapse_base_path }}/venv"
 
 synapse_signing_key: ~
 synapse_signing_key_file: >-

roles/synapse/defaults/main/systemd.yml

@@ -0,0 +1,53 @@
+---
+synapse_systemd_name: "synapse.service"
+synapse_systemd_service_directory: /etc/systemd/system
+synapse_systemd_service_file: >-2
+  {{ synapse_systemd_service_directory }}/{{ synapse_systemd_name }}
+
+synapse_systemd_state: >-2
+  {{ (synapse_state == 'present') | ternary('started', 'stopped') }}
+synapse_systemd_enabled: >-2
+  {{ (synapse_state == 'present') | bool }}
+
+synapse_systemd_unit_description: "Synapse matrix homeserver"
+synapse_systemd_service_type: notify
+synapse_systemd_service_exec_start: >-2
+  {{ synapse_venv_path }}/bin/synapse_homeserver \
+    --config-path={{ synapse_homeserver_config_file }}
+synapse_systemd_service_exec_stop: >-2
+  {{ synapse_venv_path }}/bin/synctl \
+    stop {{ synapse_homeserver_config_file }}
+synapse_systemd_service_exec_reload: >-2
+  /usr/bin/env kill -HUP $MAINPID
+synapse_systemd_service_restart: on-failure
+
+synapse_systemd_unit_after:
+  - "network.target"
+synapse_systemd_unit_wants: []
+synapse_systemd_install_wanted_by: "default.target"
+
+# Hardening
+synapse_systemd_service_read_write_paths:
+  - "{{ synapse_base_path }}"
+  - "{{ synapse_data_path }}"
+  - "{{ synapse_media_store_path }}"
+  - "{{ synapse_log_path }}"
+synapse_systemd_service_restrict_address_families:
+  - "AF_INET"
+  - "AF_INET6"
+  - "AF_UNIX"
+synapse_systemd_service_protect_system: strict
+synapse_systemd_service_protect_home: true
+synapse_systemd_service_protect_clock: true
+synapse_systemd_service_protect_hostname: true
+synapse_systemd_service_protect_protect_kernel_logs: true
+synapse_systemd_service_protect_protect_kernel_modules: true
+synapse_systemd_service_protect_protect_kernel_tunables: true
+synapse_systemd_service_protect_protect_control_groups: true
+
+synapse_systemd_service_restrict_namespaces: true
+synapse_systemd_service_restrict_suid_sgid: true
+
+synapse_systemd_service_remove_ipc: true
+synapse_systemd_service_lock_personality: true
+synapse_systemd_service_no_new_privileges: true

roles/synapse/defaults/main/user.yml

@@ -0,0 +1,21 @@
+---
+synapse_user_base_groups:
+  - "{{ synapse_run_group }}"
+synapse_user_groups: ~
+synapse_user_all_groups: >-2
+  {{ synapse_user_base_groups | default([], true)
+    + synapse_user_groups | default([], true) }}
+synapse_user_groups_append: "{{ synapse_user_all_groups | length > 0 }}"
+synapse_run_user: >-2
+  {{ synapse_user_info.name | default(synapse_user) }}
+synapse_run_group: >-2
+  {{ (synapse_user_info is defined and ('groups' in synapse_user_info))
+    | ternary(
+      (synapse_user_info.groups | default("") | split(",") | first),
+      synapse_group
+    )
+  }}
+synapse_run_user_id: >-2
+  {{ synapse_user_info.uid | default(synapse_user) }}
+synapse_run_group_id: >-2
+  {{ synapse_user_info.group | default(synapse_user) }}

roles/synapse/defaults/main/virtualenv.yml

@@ -0,0 +1,11 @@
+---
+synapse_venv_package: "matrix-synapse[all]"
+synapse_venv_pip_dependencies:
+  - pip
+  - setuptools
+synapse_venv_package_full: >-2
+  {{ synapse_venv_package }}@{{ synapse_version }}
+
+synapse_venv_python_binary: >-2
+  {{ ansible_python_interpreter | default(omit, true) }}
+synapse_venv_extra_args: ~

roles/synapse/handlers/main.yml

@@ -14,3 +14,18 @@
     state: "{{ synapse_container_state }}"
     force_restart: true
   when: synapse_deployment_method == 'podman'
+
+- name: Ensure synapse is restarted
+  listen: synapse-restart
+  ansible.builtin.systemd_service:
+    name: "{{ synapse_systemd_service_name }}"
+    state: restarted
+  when:
+    - synapse_deployment_method == 'virtualenv'
+    - ansible_facts['service_mgr'] == systemd
+    - synapse_systemd_state == 'started'
+
+- name: Ensure systemd units are reloaded
+  listen: systemd-daemon-reload
+  ansible.builtin.systemd:
+    daemon_reload: true

roles/synapse/tasks/configure.yml

@@ -1,12 +1,19 @@
 ---
+- name: Ensure synapse group '{{ synapse_group }}' is {{ synapse_state }}
+  ansible.builtin.group:
+    name: "{{ synapse_group }}"
+    system: "{{ synapse_group_system | default(true, true) }}"
+    state: "{{ synapse_state }}"
+  register: synapse_group_info
+
 - name: Ensure synapse user '{{ synapse_user }}' is {{ synapse_state }}
   ansible.builtin.user:
     name: "{{ synapse_user }}"
     state: "{{ synapse_state }}"
     system: "{{ synapse_user_system | default(true, true) }}"
     create_home: "{{ synapse_user_create_home | default(false, true) }}"
-    groups: "{{ synapse_user_groups | default(omit, true) }}"
+    groups: "{{ synapse_user_all_groups | default(omit, true) }}"
-    append: "{{ (synapse_user_groups is defined) | ternary(true, omit) }}"
+    append: "{{ synapse_user_groups_append | default(omit, true) }}"
   register: synapse_user_info
 
 - name: Ensure directories for synapse are {{ synapse_state }}
@@ -64,3 +71,4 @@
         mode: "0640"
   notify:
     - synapse-restart
+  when: synapse_state != 'absent'

roles/synapse/tasks/deploy-virtualenv.yml

@@ -0,0 +1,67 @@
+---
+- name: Ensure directory for virtualenv is {{ synapse_state }}
+  ansible.builtin.file:
+    path: "{{ synapse_venv_path }}"
+    owner: >-2
+      {{ synapse_user_info.uid | default(synapse_user) }}
+    group: >-2
+      {{ synapse_user_info.group | default(synapse_user) }}
+    mode: "{{ synapse_venv_path_mode | default('0755') }}"
+    state: >-
+      {{ (synapse_state == 'present')
+        | ternary('directory', 'absent') }}
+
+- name: Ensure virtual environment is {{ synapse_state }}
+  ansible.builtin.pip:
+    name: "{{ synapse_venv_pip_dependencies }}"
+    virtualenv: "{{ synapse_venv_path }}"
+    virtualenv_python: "{{ synapse_venv_python_binary }}"
+    extra_args: "{{ synapse_venv_extra_args | default(omit, true) }}"
+    state: "{{ synapse_state }}"
+
+- name: Ensure synapse pip package is {{ synapse_state }}
+  ansible.builtin.pip:
+    name: "{{ synapse_venv_package }}"
+    version: "{{ synapse_version }}"
+    state: "{{ synapse_state }}"
+    virtualenv: "{{ synapse_venv_path }}"
+  notify:
+    - synapse-restart
+  when: synapse_state != 'absent'
+
+- name: Ensure synapse virtualenv is {{ synapse_state }}
+  ansible.builtin.file:
+    path: "{{ synapse_venv_path }}"
+    state: "{{ synapse_state }}"
+  when: synapse_state == 'absent'
+
+- name: Ensure systemd unit is {{ synapse_state }}
+  ansible.builtin.template:
+    src: "synapse.service.j2"
+    dest: "{{ synapse_systemd_service_file }}"
+  notify:
+    - systemd-daemon-reload
+  when: synapse_state != 'absent'
+
+- name: Ensure systemd unit is {{ synapse_state }}
+  ansible.builtin.file:
+    path: "{{ synapse_systemd_service_file }}"
+    state: "{{ synapse_state }}"
+  when: synapse_state == 'absent'
+  notify:
+    - systemd-daemon-reload
+
+- name: Ensure handlers are flushed for systemd daemon reload and synapse service state propagation
+  meta: flush_handlers
+
+- name: Ensure systemd service is {{ synapse_systemd_state }}
+  ansible.builtin.systemd_service:
+    name: "{{ synapse_systemd_name }}"
+    state: "{{ synapse_systemd_state }}"
+  when: synapse_state != 'absent'
+
+- name: Ensure systemd service is {{ synapse_systemd_enabled | ternary('enabled', 'disabled') }}
+  ansible.builtin.systemd_service:
+    name: "{{ synapse_systemd_name }}"
+    enabled: "{{ synapse_systemd_enabled }}"
+  when: synapse_state != 'absent'

roles/synapse/templates/synapse.service.j2

@@ -0,0 +1,44 @@
+[Unit]
+Description={{ synapse_systemd_unit_description }}
+
+{% if synapse_systemd_unit_after | default([]) | length > 0 %}
+After={{ synapse_systemd_unit_after | join(' ') }}
+{% endif %}
+{% if synapse_systemd_unit_wants | default([]) | length > 0 %}
+Wants={{ synapse_systemd_unit_wants | join(' ') }}
+{% endif %}
+
+[Service]
+Type={{ synapse_systemd_service_type }}
+WorkingDirectory={{ synapse_venv_path }}
+ExecStart={{ synapse_systemd_service_exec_start }}
+ExecStop={{ synapse_systemd_service_exec_stop }}
+ExecReload={{ synapse_systemd_service_exec_reload }}
+
+User={{ synapse_run_user }}
+Group={{ synapse_run_group }}
+
+Restart={{ synapse_systemd_service_restart }}
+
+ProtectSystem={{ synapse_systemd_service_protect_system }}
+ProtectHome={{ synapse_systemd_service_protect_home }}
+ProtectClock={{ synapse_systemd_service_protect_clock }}
+ProtectHostname={{ synapse_systemd_service_protect_hostname }}
+ProtectKernelLogs={{ synapse_systemd_service_protect_protect_kernel_logs }}
+ProtectKernelModules={{ synapse_systemd_service_protect_protect_kernel_modules }}
+ProtectKernelTunables={{ synapse_systemd_service_protect_protect_control_groups }}
+ProtectControlGroups={{ synapse_systemd_service_protect_protect_control_groups }}
+
+RestrictNamespaces={{ synapse_systemd_service_restrict_namespaces }}
+RestrictSUIDSGID={{ synapse_systemd_service_restrict_suid_sgid }}
+{% for path in synapse_systemd_service_read_write_paths | default([]) %}
+ReadWritePaths={{ path }}
+{% endfor %}
+RestrictAddressFamilies={{ synapse_systemd_service_restrict_address_families | join(' ') }}
+
+RemoveIPC={{ synapse_systemd_service_remove_ipc }}
+LockPersonality={{ synapse_systemd_service_lock_personality }}
+NoNewPrivileges={{ synapse_systemd_service_no_new_privileges }}
+
+[Install]
+WantedBy={{ synapse_systemd_install_wanted_by }}

roles/synapse/vars/main.yml

@@ -6,6 +6,7 @@ synapse_states:
 synapse_deployment_methods:
   - docker
   - podman
+  - virtualenv
 
 synapse_required_variables:
   - synapse_domain