Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -661,7 +661,10 @@ The role seeds GQRX/QSSTV configuration only when it does not already exist, so
normal operator tuning changes survive later convergence. The internal
`digital/qsstv-runtime` support role builds the HamRadioVillage QSSTV source and
exposes it as `/usr/local/bin/qsstv`; it is not enabled directly from
`site.yml`.
`site.yml`. That helper checks out and builds as a locked system account rather
than root. Mutable refs are not refreshed by default; automatic source updates
require a reviewed full commit ID, and promoted artifacts are checksum-checked
before entering root-owned install locations.

<a id="role-sstv-workstation"></a>
#### `sstv-workstation`
Expand Down
4 changes: 3 additions & 1 deletion docs/variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -218,14 +218,16 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the
| --- | --- | --- |
| `hamstack_qsstv_binary` | `/opt/hamstack/qsstv/bin/qsstv` | Configuration value for qsstv binary; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_build_dir` | `/var/cache/hamstack/qsstv-build` | Configuration value for qsstv build dir; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_build_group` | `hamstack-qsstv-build` | Configuration value for qsstv build group; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_build_jobs` | `2` | Configuration value for qsstv build jobs; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_build_user` | `hamstack-qsstv-build` | Configuration value for qsstv build user; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_install_prefix` | `/opt/hamstack/qsstv` | Configuration value for qsstv install prefix; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_launcher` | `/usr/local/bin/qsstv` | Configuration value for qsstv launcher; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_remove_distro_package` | `true` | Configuration value for qsstv remove distro package; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_source_dir` | `/opt/hamstack/qsstv-source` | Configuration value for qsstv source dir; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_source_ref` | `main` | Configuration value for qsstv source ref; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_source_repo` | `https://github.com/HamRadioVillage/QSSTV.git` | Configuration value for qsstv source repo; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_update_source` | `true` | Configuration value for qsstv update source; see the digital/qsstv-runtime role README for operational context. |
| `hamstack_qsstv_update_source` | `false` | Configuration value for qsstv update source; see the digital/qsstv-runtime role README for operational context. |

## `digital/selfie_station`

Expand Down
16 changes: 13 additions & 3 deletions roles/digital/qsstv-runtime/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,16 @@ the binary under `/opt/hamstack/qsstv`, and exposes it as
`/usr/local/bin/qsstv`. The distro package is removed by default so the broken
or incompatible `/usr/bin/qsstv` cannot accidentally win path selection.

The default ref is `main` because the HRV repository currently has no HamStack-
validated release tag. Sites requiring immutable rebuilds should pin
`hamstack_qsstv_source_ref` to a tested commit hash.
Source checkout, qmake, make, and runtime-library inspection run as the locked
`hamstack_qsstv_build_user` account. HamStack accepts only regular artifacts
owned by that account, stages them without following source symlinks, verifies
their SHA-256 digests, and then atomically moves them into root-owned install
locations. Upstream build logic therefore does not receive root authority.

The default ref remains `main` because the HRV repository currently has no
HamStack-validated release tag, but `hamstack_qsstv_update_source` defaults to
`false`: the branch is resolved for an initial checkout and later convergence
does not follow it. To update an existing checkout, first review and set
`hamstack_qsstv_source_ref` to the full 40-character commit ID, then set
`hamstack_qsstv_update_source: true`. The role verifies that exact commit before
building it and rejects automatic updates from branches, tags, or short IDs.
6 changes: 5 additions & 1 deletion roles/digital/qsstv-runtime/defaults/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,13 @@ hamstack_qsstv_source_repo: https://github.com/HamRadioVillage/QSSTV.git
hamstack_qsstv_source_ref: main
hamstack_qsstv_source_dir: /opt/hamstack/qsstv-source
hamstack_qsstv_build_dir: /var/cache/hamstack/qsstv-build
hamstack_qsstv_build_user: hamstack-qsstv-build
hamstack_qsstv_build_group: hamstack-qsstv-build
hamstack_qsstv_install_prefix: /opt/hamstack/qsstv
hamstack_qsstv_binary: /opt/hamstack/qsstv/bin/qsstv
hamstack_qsstv_launcher: /usr/local/bin/qsstv
hamstack_qsstv_build_jobs: 2
hamstack_qsstv_update_source: true
# Mutable refs are resolved only for the initial checkout. Automatic updates
# require a full commit ID so later convergence cannot follow a moving branch.
hamstack_qsstv_update_source: false
hamstack_qsstv_remove_distro_package: true
180 changes: 136 additions & 44 deletions roles/digital/qsstv-runtime/tasks/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,20 @@
- ansible_facts['os_family'] == 'Debian'
- hamstack_qsstv_source_repo | length > 0
- hamstack_qsstv_source_ref | length > 0
- hamstack_qsstv_build_user | length > 0
- hamstack_qsstv_build_group | length > 0
- hamstack_qsstv_build_user != 'root'
- hamstack_qsstv_build_group != 'root'
- (hamstack_qsstv_build_jobs | int) > 0
- >-
not (hamstack_qsstv_update_source | bool) or
hamstack_qsstv_source_ref is match('^[0-9a-fA-F]{40}$')
fail_msg: >-
The HamStack QSSTV runtime currently builds the HamRadioVillage QSSTV
source tree on Debian-family systems. Configure a non-empty source repo
and ref and a positive build job count.
source tree on Debian-family systems. Configure non-empty source, build
account, and group values and a positive build job count. Source updates
require hamstack_qsstv_source_ref to be a full 40-character commit ID;
mutable refs are allowed only when updates are disabled.

- name: Install HRV QSSTV build dependencies
ansible.builtin.apt:
Expand Down Expand Up @@ -40,7 +49,33 @@
state: absent
when: hamstack_qsstv_remove_distro_package | bool

- name: Create HRV QSSTV source, build, and install directories
- name: Create HRV QSSTV build group
ansible.builtin.group:
name: "{{ hamstack_qsstv_build_group }}"
system: true

- name: Create HRV QSSTV build account
ansible.builtin.user:
name: "{{ hamstack_qsstv_build_user }}"
group: "{{ hamstack_qsstv_build_group }}"
system: true
create_home: false
home: "{{ hamstack_qsstv_build_dir }}"
shell: /usr/sbin/nologin

- name: Read HRV QSSTV build account
ansible.builtin.getent:
database: passwd
key: "{{ hamstack_qsstv_build_user }}"

- name: Require a non-root HRV QSSTV build account
ansible.builtin.assert:
that:
- (ansible_facts.getent_passwd[hamstack_qsstv_build_user][1] | int) != 0
fail_msg: >-
hamstack_qsstv_build_user must resolve to a dedicated non-root account.

- name: Create root-owned HRV QSSTV parent and install directories
ansible.builtin.file:
path: "{{ item }}"
state: directory
Expand All @@ -49,11 +84,33 @@
mode: '0755'
loop:
- "{{ hamstack_qsstv_source_dir | dirname }}"
- "{{ hamstack_qsstv_build_dir }}"
- "{{ hamstack_qsstv_build_dir | dirname }}"
- "{{ hamstack_qsstv_install_prefix }}/bin"
- /usr/local/share/applications
- /usr/local/share/icons/hicolor/128x128/apps

- name: Create unprivileged HRV QSSTV source and build directories
ansible.builtin.file:
path: "{{ item }}"
state: directory
owner: "{{ hamstack_qsstv_build_user }}"
group: "{{ hamstack_qsstv_build_group }}"
mode: '0750'
loop:
- "{{ hamstack_qsstv_source_dir }}"
- "{{ hamstack_qsstv_build_dir }}"

- name: Migrate existing HRV QSSTV work trees to the build account
ansible.builtin.file:
path: "{{ item }}"
state: directory
owner: "{{ hamstack_qsstv_build_user }}"
group: "{{ hamstack_qsstv_build_group }}"
recurse: true
loop:
- "{{ hamstack_qsstv_source_dir }}"
- "{{ hamstack_qsstv_build_dir }}"

- name: Check out HamRadioVillage QSSTV source
ansible.builtin.git:
repo: "{{ hamstack_qsstv_source_repo }}"
Expand All @@ -62,6 +119,36 @@
update: "{{ hamstack_qsstv_update_source | bool }}"
force: false
register: _hamstack_qsstv_source
become: true
become_user: "{{ hamstack_qsstv_build_user }}"
environment:
HOME: "{{ hamstack_qsstv_build_dir }}"

- name: Read checked-out HRV QSSTV commit
ansible.builtin.command:
argv:
- git
- rev-parse
- --verify
- 'HEAD^{commit}'
chdir: "{{ hamstack_qsstv_source_dir }}"
register: _hamstack_qsstv_source_head
changed_when: false
become: true
become_user: "{{ hamstack_qsstv_build_user }}"
environment:
HOME: "{{ hamstack_qsstv_build_dir }}"

- name: Verify pinned HRV QSSTV commit was checked out
ansible.builtin.assert:
that:
- >-
(_hamstack_qsstv_source_head.stdout | lower) ==
(hamstack_qsstv_source_ref | lower)
fail_msg: >-
The checked-out QSSTV commit does not match the configured immutable
hamstack_qsstv_source_ref.
when: hamstack_qsstv_source_ref is match('^[0-9a-fA-F]{40}$')

- name: Check installed HRV QSSTV binary
ansible.builtin.stat:
Expand All @@ -73,63 +160,64 @@
path: "{{ hamstack_qsstv_build_dir }}/Makefile"
register: _hamstack_qsstv_makefile_stat

- name: Determine whether HRV QSSTV must be rebuilt
ansible.builtin.set_fact:
_hamstack_qsstv_rebuild_required: >-
{{
_hamstack_qsstv_source.changed or
not _hamstack_qsstv_binary_stat.stat.exists or
not _hamstack_qsstv_makefile_stat.stat.exists
}}

- name: Configure HRV QSSTV build with qmake
ansible.builtin.command:
argv:
- qmake
- "PREFIX={{ hamstack_qsstv_install_prefix }}"
- "{{ hamstack_qsstv_source_dir }}/src"
chdir: "{{ hamstack_qsstv_build_dir }}"
register: _hamstack_qsstv_qmake
changed_when: true
when: >-
_hamstack_qsstv_source.changed or
not _hamstack_qsstv_binary_stat.stat.exists or
not _hamstack_qsstv_makefile_stat.stat.exists
when: _hamstack_qsstv_rebuild_required | bool
become: true
become_user: "{{ hamstack_qsstv_build_user }}"
environment:
HOME: "{{ hamstack_qsstv_build_dir }}"

- name: Build HRV QSSTV
ansible.builtin.command:
argv:
- make
- "-j{{ hamstack_qsstv_build_jobs | int }}"
chdir: "{{ hamstack_qsstv_build_dir }}"
register: _hamstack_qsstv_make
changed_when: true
when: >-
_hamstack_qsstv_source.changed or
not _hamstack_qsstv_binary_stat.stat.exists or
(_hamstack_qsstv_qmake is defined and _hamstack_qsstv_qmake.changed)

- name: Install HRV QSSTV binary
ansible.builtin.copy:
src: "{{ hamstack_qsstv_build_dir }}/qsstv"
dest: "{{ hamstack_qsstv_binary }}"
remote_src: true
owner: root
group: root
mode: '0755'
when: >-
_hamstack_qsstv_source.changed or
not _hamstack_qsstv_binary_stat.stat.exists or
(_hamstack_qsstv_make is defined and _hamstack_qsstv_make.changed)

- name: Install HRV QSSTV desktop entry
ansible.builtin.copy:
src: "{{ hamstack_qsstv_source_dir }}/qsstv.desktop"
dest: /usr/local/share/applications/qsstv.desktop
remote_src: true
owner: root
group: root
mode: '0644'
when: _hamstack_qsstv_rebuild_required | bool
become: true
become_user: "{{ hamstack_qsstv_build_user }}"
environment:
HOME: "{{ hamstack_qsstv_build_dir }}"

- name: Install HRV QSSTV icon
ansible.builtin.copy:
src: "{{ hamstack_qsstv_source_dir }}/src/icons/qsstv.png"
dest: /usr/local/share/icons/hicolor/128x128/apps/qsstv.png
remote_src: true
owner: root
group: root
mode: '0644'
- name: Promote verified HRV QSSTV binary
ansible.builtin.include_tasks: promote-artifact.yml
vars:
_hamstack_qsstv_artifact_source: "{{ hamstack_qsstv_build_dir }}/qsstv"
_hamstack_qsstv_artifact_destination: "{{ hamstack_qsstv_binary }}"
_hamstack_qsstv_artifact_mode: '0755'
when: _hamstack_qsstv_rebuild_required | bool

- name: Promote verified HRV QSSTV shared data
ansible.builtin.include_tasks: promote-artifact.yml
vars:
_hamstack_qsstv_artifact_source: "{{ _hamstack_qsstv_shared_artifact.source }}"
_hamstack_qsstv_artifact_destination: "{{ _hamstack_qsstv_shared_artifact.destination }}"
_hamstack_qsstv_artifact_mode: '0644'
loop:
- source: "{{ hamstack_qsstv_source_dir }}/qsstv.desktop"
destination: /usr/local/share/applications/qsstv.desktop
- source: "{{ hamstack_qsstv_source_dir }}/src/icons/qsstv.png"
destination: /usr/local/share/icons/hicolor/128x128/apps/qsstv.png
loop_control:
loop_var: _hamstack_qsstv_shared_artifact
label: "{{ _hamstack_qsstv_shared_artifact.destination }}"

- name: Expose HRV QSSTV on the system path
ansible.builtin.file:
Expand All @@ -148,3 +236,7 @@
failed_when: >-
_hamstack_qsstv_ldd.rc != 0 or
'not found' in _hamstack_qsstv_ldd.stdout
become: true
become_user: "{{ hamstack_qsstv_build_user }}"
environment:
HOME: "{{ hamstack_qsstv_build_dir }}"
86 changes: 86 additions & 0 deletions roles/digital/qsstv-runtime/tasks/promote-artifact.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
---
- name: Inspect unprivileged HRV QSSTV artifact
ansible.builtin.stat:
path: "{{ _hamstack_qsstv_artifact_source }}"
follow: false
get_checksum: true
checksum_algorithm: sha256
register: _hamstack_qsstv_artifact_source_stat

- name: Require a regular build-account-owned HRV QSSTV artifact
ansible.builtin.assert:
that:
- _hamstack_qsstv_artifact_source_stat.stat.exists
- _hamstack_qsstv_artifact_source_stat.stat.isreg
- not _hamstack_qsstv_artifact_source_stat.stat.islnk
- _hamstack_qsstv_artifact_source_stat.stat.pw_name == hamstack_qsstv_build_user
fail_msg: >-
QSSTV promotion requires a regular artifact owned by the dedicated build
account: {{ _hamstack_qsstv_artifact_source }}.

- name: Inspect installed HRV QSSTV artifact
ansible.builtin.stat:
path: "{{ _hamstack_qsstv_artifact_destination }}"
follow: false
get_checksum: true
checksum_algorithm: sha256
register: _hamstack_qsstv_artifact_destination_stat

- name: Promote changed HRV QSSTV artifact
when: >-
not _hamstack_qsstv_artifact_destination_stat.stat.exists or
(_hamstack_qsstv_artifact_destination_stat.stat.checksum | default('')) !=
_hamstack_qsstv_artifact_source_stat.stat.checksum
block:
- name: Remove stale staged HRV QSSTV artifact
ansible.builtin.file:
path: "{{ _hamstack_qsstv_artifact_destination }}.hamstack-new"
state: absent

- name: Stage HRV QSSTV artifact without following source symlinks
ansible.builtin.command:
argv:
- dd
- "if={{ _hamstack_qsstv_artifact_source }}"
- "of={{ _hamstack_qsstv_artifact_destination }}.hamstack-new"
- bs=1M
- conv=fsync
- iflag=nofollow
- status=none

- name: Inspect staged HRV QSSTV artifact
ansible.builtin.stat:
path: "{{ _hamstack_qsstv_artifact_destination }}.hamstack-new"
follow: false
get_checksum: true
checksum_algorithm: sha256
register: _hamstack_qsstv_artifact_staged_stat

- name: Verify staged HRV QSSTV artifact matches its source
ansible.builtin.assert:
that:
- _hamstack_qsstv_artifact_staged_stat.stat.exists
- _hamstack_qsstv_artifact_staged_stat.stat.isreg
- not _hamstack_qsstv_artifact_staged_stat.stat.islnk
- >-
_hamstack_qsstv_artifact_staged_stat.stat.checksum ==
_hamstack_qsstv_artifact_source_stat.stat.checksum
fail_msg: >-
Staged QSSTV artifact differs from its inspected source:
{{ _hamstack_qsstv_artifact_source }}.

- name: Set staged HRV QSSTV artifact ownership and mode
ansible.builtin.file:
path: "{{ _hamstack_qsstv_artifact_destination }}.hamstack-new"
owner: root
group: root
mode: "{{ _hamstack_qsstv_artifact_mode }}"

- name: Install verified HRV QSSTV artifact atomically
ansible.builtin.command:
argv:
- mv
- -f
- --
- "{{ _hamstack_qsstv_artifact_destination }}.hamstack-new"
- "{{ _hamstack_qsstv_artifact_destination }}"
Loading
Loading