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
10 changes: 8 additions & 2 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -337,7 +337,7 @@ The Graywolf KISS→AX.25 session→ENiGMA shim is planned but not part of the c
| `hamstack_graywolf_install` | boolean | `true` | role | Install the supported upstream Debian package. |
| `hamstack_graywolf_version` | string | `latest` | role | Release to install, or a pinned upstream version. |
| `hamstack_graywolf_package_url` | string | `""` | role | Optional direct `.deb` URL (HTTPS), bypassing release discovery. |
| `hamstack_graywolf_package_checksum` | string | `""` | role | Optional `sha256:<digest>` verified before the package is installed. |
| `hamstack_graywolf_package_checksum` | string | `""` | role | Required reviewed `sha256:<digest>` when package installation is enabled. |
| `hamstack_graywolf_autostart` | boolean | `true` | role | Enable/start the Graywolf systemd service. |
| `hamstack_graywolf_manage_api` | boolean | `false` | role | Converge Graywolf operational state through its REST API. |
| `hamstack_graywolf_api_url` | URL | `http://127.0.0.1:8080/api` | role | Graywolf management API base. |
Expand All @@ -356,6 +356,9 @@ Graywolf API management is intentionally independent of `packet/aprs`. A host ma
Example packet-only modem configuration:

```yaml
# Replace this intentionally fake digest with the reviewed package SHA-256.
hamstack_graywolf_package_checksum: >-
sha256:0000000000000000000000000000000000000000000000000000000000000000
hamstack_graywolf_manage_api: true

hamstack_graywolf_audio_devices:
Expand Down Expand Up @@ -555,12 +558,15 @@ workflows. See `docs/variables.md` for the complete variables.
| `hamstack_gridtracker_install` | boolean | `true` | role | Install a Debian package. |
| `hamstack_gridtracker_version` | string | `2.260925.2` | role | Tested default or another pinned upstream version. |
| `hamstack_gridtracker_package_url` | URL | `""` | role | Explicit package override (HTTPS). |
| `hamstack_gridtracker_package_checksum` | string | `""` | role | Optional `sha256:<digest>` verified before the package is installed. |
| `hamstack_gridtracker_package_checksum` | string | `""` | role | Required reviewed `sha256:<digest>` when package installation is enabled. |
| `hamstack_gridtracker_wsjtx_host` | string | `127.0.0.1` | role | Reserved WSJT-X input host setting. |
| `hamstack_gridtracker_wsjtx_port` | integer | `2237` | role | Reserved WSJT-X UDP port. |
| `hamstack_gridtracker_autostart` | boolean | `false` | role | Add XDG autostart for the operator user. |

Supported packages are available for amd64 and arm64 Debian-family systems.
Package installation fails closed until the selected package has a reviewed
SHA-256 digest. Set `hamstack_gridtracker_install: false` to manage autostart
for a package installed through a separate trusted process.

<a id="role-openhamclock"></a>
#### `openhamclock`
Expand Down
4 changes: 2 additions & 2 deletions docs/variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -542,7 +542,7 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the
| `hamstack_graywolf_manage_api` | `false` | Converge Graywolf operational state through its REST API. |
| `hamstack_graywolf_manage_first_user` | `true` | Create the first Graywolf management user on an unconfigured node. |
| `hamstack_graywolf_manage_station` | `true` | Converge Graywolf's station callsign. |
| `hamstack_graywolf_package_checksum` | `` | Optional `sha256:<digest>` verified before the package is installed. |
| `hamstack_graywolf_package_checksum` | `` | Required reviewed `sha256:<digest>` when package installation is enabled. |
| `hamstack_graywolf_package_url` | `` | Optional direct `.deb` URL (HTTPS), bypassing release discovery. |
| `hamstack_graywolf_password` | `{{ vault_hamstack_graywolf_password \| default(vault_hamstack_aprs_graywolf_password \| default('')) }}` | Management password; prefer `vault_hamstack_graywolf_password`. |
| `hamstack_graywolf_username` | `hamstack` | Management account used by automation. |
Expand Down Expand Up @@ -818,7 +818,7 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the
| `hamstack_gridtracker_install` | `true` | Install a Debian package. |
| `hamstack_gridtracker_logging_backend` | `` | Configuration value for gridtracker logging backend; see the visual/gridtracker role README for operational context. |
| `hamstack_gridtracker_logging_url` | `` | Configuration value for gridtracker logging url; see the visual/gridtracker role README for operational context. |
| `hamstack_gridtracker_package_checksum` | `` | Optional `sha256:<digest>` verified before the package is installed. |
| `hamstack_gridtracker_package_checksum` | `` | Required reviewed `sha256:<digest>` when package installation is enabled. |
| `hamstack_gridtracker_package_url` | `` | Explicit package override (HTTPS). |
| `hamstack_gridtracker_version` | `2.260925.2` | Tested default or another pinned upstream version. |
| `hamstack_gridtracker_wsjtx_host` | `127.0.0.1` | Reserved WSJT-X input host setting. |
Expand Down
3 changes: 3 additions & 0 deletions inventory/example/host_vars/example-node.yml
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,9 @@ hamstack_radios:
#
# Graywolf can be used independently of packet/aprs as a modem/TNC/KISS layer.
# hamstack_graywolf_enabled: true
# Replace this intentionally fake digest with the reviewed package SHA-256.
# hamstack_graywolf_package_checksum: >-
# sha256:0000000000000000000000000000000000000000000000000000000000000000
# hamstack_graywolf_manage_api: true
# hamstack_graywolf_audio_devices:
# - name: packet_rx
Expand Down
10 changes: 8 additions & 2 deletions roles/packet/graywolf/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ Deploy Graywolf as HamStack's reusable software-modem/TNC layer between radio/au
## Responsibilities

- Install an official Graywolf Debian release over HTTPS and manage the
service. `hamstack_graywolf_package_checksum` (`sha256:<digest>`) verifies
the package when a release is pinned.
service. Installation requires a reviewed `hamstack_graywolf_package_checksum`
(`sha256:<digest>`) and verifies the package before `apt` processes it.
- Bootstrap the first Graywolf management user when explicitly enabled.
- Set station identity through the supported REST API.
- Create/update named audio devices and modem-backed or KISS-only channels.
Expand All @@ -20,6 +20,12 @@ Deploy Graywolf as HamStack's reusable software-modem/TNC layer between radio/au

Graywolf keeps its operational configuration in SQLite. HamStack does **not** edit that database directly; API-managed state is converged through Graywolf's management API.

The checksum is required for discovered releases and explicit package URLs,
including `hamstack_graywolf_version: latest`. A new release or package URL
therefore requires an independently reviewed digest. Set
`hamstack_graywolf_install: false` when managing a package installed through a
separate trusted process.

## Boundaries

This role owns Graywolf's modem/TNC plumbing. Higher-level APRS policy remains optional:
Expand Down
2 changes: 1 addition & 1 deletion roles/packet/graywolf/defaults/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ hamstack_graywolf_enabled: false
hamstack_graywolf_install: true
hamstack_graywolf_version: latest
hamstack_graywolf_package_url: ''
# Optional sha256:<digest> of the Graywolf package that will be installed.
# Required sha256:<digest> when HamStack installs the Graywolf package.
hamstack_graywolf_package_checksum: ''
hamstack_graywolf_callsign: '{{ hamstack_callsign | default(''N0CALL'') }}'
hamstack_graywolf_config_path: ''
Expand Down
21 changes: 12 additions & 9 deletions roles/packet/graywolf/tasks/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,16 @@
aarch64, armv7l, and armv6l. Set hamstack_graywolf_package_url and
extend the role for another platform.

- name: Require a verified Graywolf package checksum
ansible.builtin.assert:
that:
- hamstack_graywolf_package_checksum is match('^sha256:[0-9A-Fa-f]{64}$')
fail_msg: >-
Set hamstack_graywolf_package_checksum to a reviewed
sha256:<64-hex-digest> before HamStack downloads and installs a
Graywolf package.
when: hamstack_graywolf_install | bool

- name: Install Graywolf Debian-package prerequisite
ansible.builtin.apt:
name: xz-utils
Expand Down Expand Up @@ -88,9 +98,6 @@
that:
- _hamstack_graywolf_download_url | length > 0
- _hamstack_graywolf_download_url is match('^https://')
- >-
hamstack_graywolf_package_checksum | length == 0
or hamstack_graywolf_package_checksum is match('^sha256:[0-9A-Fa-f]{64}$')
fail_msg: >-
Could not locate an HTTPS URL for the expected Graywolf Debian package
{{ _hamstack_graywolf_asset_name | default('for this architecture') }}.
Expand All @@ -101,9 +108,7 @@
| list
| join(', ')
}}. Pin hamstack_graywolf_package_url to a compatible .deb if the
upstream asset naming changes. Optional
hamstack_graywolf_package_checksum values must use
sha256:<64-hex-digest>.
upstream asset naming changes.
when: hamstack_graywolf_install | bool

- name: Create HamStack package cache
Expand All @@ -119,9 +124,7 @@
ansible.builtin.get_url:
url: "{{ _hamstack_graywolf_download_url }}"
dest: "{{ hamstack_cache_dir | default('/var/cache/hamstack') }}/packages/graywolf.deb"
checksum: >-
{{ hamstack_graywolf_package_checksum
if hamstack_graywolf_package_checksum | length > 0 else omit }}
checksum: "{{ hamstack_graywolf_package_checksum }}"
owner: root
group: root
mode: "0644"
Expand Down
10 changes: 7 additions & 3 deletions roles/visual/gridtracker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,18 @@ operation.
- optional `latest` discovery from the official GridTracker download page;
- explicit package URL/version overrides for reproducible deployments;
- optional XDG desktop autostart for `hamstack_operator_user`;
- optional SHA-256 verification through `hamstack_gridtracker_package_checksum`.
- mandatory SHA-256 verification through `hamstack_gridtracker_package_checksum`
whenever HamStack installs the package.

Package URLs must use HTTPS. The downloaded package is cached under the
root-owned HamStack package cache using its upstream filename, so changing
`hamstack_gridtracker_version` installs the new package rather than a stale
cached copy. GridTracker does not publish signed packages; supply
`hamstack_gridtracker_package_checksum` (`sha256:<digest>`) for reproducible,
verified installs.
`hamstack_gridtracker_package_checksum` (`sha256:<digest>`) from an
independently reviewed source. The requirement applies to pinned versions,
`latest` discovery, and explicit package URLs. Set
`hamstack_gridtracker_install: false` when managing a package installed through
a separate trusted process.

GridTracker's per-user settings remain operator-owned. Its upstream first-run
configuration and WSJT-X autodetection remain in place.
2 changes: 1 addition & 1 deletion roles/visual/gridtracker/defaults/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ hamstack_gridtracker_enabled: false
hamstack_gridtracker_install: true
hamstack_gridtracker_version: '2.260925.2'
hamstack_gridtracker_package_url: ''
# Optional sha256:<digest> of the package that will be installed.
# Required sha256:<digest> when HamStack installs the GridTracker2 package.
hamstack_gridtracker_package_checksum: ''
hamstack_gridtracker_base_url: https://download2.gridtracker.org
hamstack_gridtracker_download_page: https://gridtracker.org/index.php/downloads/gridtracker-downloads
Expand Down
21 changes: 12 additions & 9 deletions roles/visual/gridtracker/tasks/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,16 @@
The first GridTracker2 implementation supports Debian-family amd64
and arm64 hosts only.

- name: Require a verified GridTracker2 package checksum
ansible.builtin.assert:
that:
- hamstack_gridtracker_package_checksum is match('^sha256:[0-9A-Fa-f]{64}$')
fail_msg: >-
Set hamstack_gridtracker_package_checksum to a reviewed
sha256:<64-hex-digest> before HamStack downloads and installs a
GridTracker2 package.
when: hamstack_gridtracker_install | bool

- name: Map host architecture to GridTracker package architecture
ansible.builtin.set_fact:
_hamstack_gridtracker_arch: "{{ {'x86_64': 'amd64', 'aarch64': 'arm64'}[ansible_facts['architecture']] }}"
Expand Down Expand Up @@ -71,15 +81,10 @@
that:
- _hamstack_gridtracker_url | default('') | length > 0
- _hamstack_gridtracker_url | default('') is match('^https://')
- >-
hamstack_gridtracker_package_checksum | length == 0
or hamstack_gridtracker_package_checksum is match('^sha256:[0-9A-Fa-f]{64}$')
fail_msg: >-
Could not discover a GridTracker2 Debian package, or the package URL
is not HTTPS. Pin hamstack_gridtracker_package_url or
hamstack_gridtracker_version. Optional
hamstack_gridtracker_package_checksum values must use
sha256:<64-hex-digest>.
hamstack_gridtracker_version.
when: hamstack_gridtracker_install | bool

- name: Remember GridTracker package cache path
Expand Down Expand Up @@ -107,9 +112,7 @@
ansible.builtin.get_url:
url: "{{ _hamstack_gridtracker_url }}"
dest: "{{ _hamstack_gridtracker_package }}"
checksum: >-
{{ hamstack_gridtracker_package_checksum
if hamstack_gridtracker_package_checksum | length > 0 else omit }}
checksum: "{{ hamstack_gridtracker_package_checksum }}"
owner: root
group: root
mode: "0644"
Expand Down
Loading