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
2 changes: 1 addition & 1 deletion FEATURES.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ it owns.
| MikroTik RouterOS | `network/routeros` | Conservative backend; validate on target hardware before cutover |
| AREDN integration | `network/aredn` | Read-only monitoring/integration |
| Local DNS | `infrastructure/technitium-dns` | Implemented Technitium DNS deployment |
| Basic netboot/iPXE content | `infrastructure/netboot` | HTTP/iPXE service implemented; DHCP/TFTP intentionally out of scope |
| Basic netboot/iPXE content | `infrastructure/netboot` | TLS and signed-artifact enforcement implemented; DHCP/TFTP intentionally out of scope |

Network appliances are managed through their own inventory and playbook rather
than being treated like ordinary Debian nodes.
Expand Down
13 changes: 12 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -872,7 +872,18 @@ and network appliances.

- `infrastructure/technitium-dns` deploys Technitium DNS with the default local
namespace `hamstack.home.arpa`, configurable forwarding, and no DHCP.
- `infrastructure/netboot` serves an HTTP/iPXE menu without running DHCP or TFTP.
- `infrastructure/netboot` serves a TLS-only iPXE menu without running DHCP or
TFTP. Boot clients must trust the HTTPS certificate and the artifact-signing
certificate; every chain, kernel, and initrd entry requires an HTTPS URL and
detached signature URL.

| Variable | Type | Default | Scope | Purpose |
| --- | --- | --- | --- | --- |
| `hamstack_netboot_entries` | list[dictionary] | `[]` | role | Signed chain or kernel/initrd entries; each executable URL has a matching detached-signature URL. |
| `hamstack_netboot_http_port` | integer | `8089` | role | Legacy-named compatibility value used by the default HTTPS port; it does not enable plaintext HTTP. |
| `hamstack_netboot_https_port` | integer | `hamstack_netboot_http_port` | role | Host port publishing the TLS-only netboot service. |
| `hamstack_netboot_tls_certificate_path` | path | `""` | role | Absolute managed-host path to the operator-owned HTTPS certificate source. |
| `hamstack_netboot_tls_private_key_path` | path | `""` | role | Absolute managed-host path to the operator-owned HTTPS private-key source. |

See [profiles.md](profiles.md) for deployment compositions and
[variables.md](variables.md) for the exhaustive generated variable index.
Expand Down
4 changes: 2 additions & 2 deletions docs/role-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ validation.
- `digital/js8call` — current upstream x86-64/ARM64 AppImage install + desktop integration.
- `digital/ft8web` — transactional local mirror of OK1CDJ FT8Web behind HTTPS.
- `infrastructure/technitium-dns` — official Technitium DNS container, persistent state, secure bootstrap, forwarding, optional local primary zone.
- `infrastructure/netboot` — minimal HTTP/iPXE content/menu service; no DHCP/TFTP yet.
- `infrastructure/netboot` — TLS-only iPXE content/menu service with mandatory detached artifact signatures; no DHCP/TFTP.
- `network/44connect` — 44Net Connect WireGuard client; split tunnel to 44Net prefixes by default.
- `network/openwrt` — rudimentary OpenWrt/GL.iNet UCI backend for hostname, LAN/DHCP, Wi-Fi, routes, DNS, and simple firewall zones.
- `network/routeros` — rudimentary RouterOS API backend for identity, IP addresses, routes, DNS, plus native structured API-path escape hatches.
Expand Down Expand Up @@ -58,7 +58,7 @@ validation.
- `digital/ft8web` mirrors the deployed site rather than consuming a formal upstream self-host artifact.
- `digital/unipager` installs/configures service lifecycle but leaves pager RF/network/hardware settings to UniPager.
- `infrastructure/technitium-dns` does not automate DHCP, split-horizon apps/views, or complete DNS record management.
- `infrastructure/netboot` deliberately omits DHCP, proxy-DHCP, and TFTP; its supported scope is HTTP/iPXE content.
- `infrastructure/netboot` deliberately omits DHCP, proxy-DHCP, and TFTP; its supported scope is authenticated HTTPS/iPXE content and signature enforcement.
- `network/openwrt` does not discover/redesign switch/DSA topology, multi-WAN, or GL.iNet vendor UI behavior.
- `network/routeros` translates only a small safe common subset; DHCP/Wi-Fi/firewall can use native-path data until broader cross-version modeling is validated.
- `network/aredn` is monitoring-only; HamStack does not own AREDN firmware or RF/mesh configuration.
Expand Down
7 changes: 5 additions & 2 deletions docs/variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -344,10 +344,13 @@ This is the exhaustive index of `hamstack_*` variables currently declared by the
| `hamstack_netboot_container_name` | `hamstack-netboot` | Container name managed by this role. |
| `hamstack_netboot_data_dir` | `{{ (hamstack_data_dir \| default('/var/lib/hamstack')) ~ '/netboot' }}` | Persistent data directory used by this role. |
| `hamstack_netboot_enabled` | `false` | Enable the infrastructure/netboot role/capability. |
| `hamstack_netboot_entries` | `[]` | Configuration value for netboot entries; see the infrastructure/netboot role README for operational context. |
| `hamstack_netboot_http_port` | `8089` | Network port used by this setting. |
| `hamstack_netboot_entries` | `[]` | Signed chain or kernel/initrd entries; each executable URL has a matching detached-signature URL. |
| `hamstack_netboot_http_port` | `8089` | Legacy-named compatibility value used by the default HTTPS port; it does not enable plaintext HTTP. |
| `hamstack_netboot_https_port` | `{{ hamstack_netboot_http_port }}` | Host port publishing the TLS-only netboot service. |
| `hamstack_netboot_image` | `nginx:alpine` | Container image used by this role. |
| `hamstack_netboot_menu_title` | `HamStack Netboot` | Configuration value for netboot menu title; see the infrastructure/netboot role README for operational context. |
| `hamstack_netboot_tls_certificate_path` | `` | Absolute managed-host path to the operator-owned HTTPS certificate source. |
| `hamstack_netboot_tls_private_key_path` | `` | Absolute managed-host path to the operator-owned HTTPS private-key source. |

## `infrastructure/technitium-dns`

Expand Down
14 changes: 14 additions & 0 deletions inventory/example/host_vars/example-node.yml
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,20 @@ hamstack_radios:
# Role-specific settings belong in host_vars when they vary by node.
# Uncomment and edit only the roles this node will use.
#
# Signed iPXE menu over operator-provisioned TLS. Boot clients must trust the
# HTTPS certificate and the certificate used for detached image signatures.
# hamstack_netboot_enabled: true
# hamstack_netboot_tls_certificate_path: /etc/hamstack/netboot/server.crt
# hamstack_netboot_tls_private_key_path: /etc/hamstack/netboot/server.key
# hamstack_netboot_entries:
# - id: rescue
# label: Signed rescue environment
# kernel: https://netboot.example.invalid:8089/rescue/vmlinuz
# kernel_signature: https://netboot.example.invalid:8089/rescue/vmlinuz.sig
# initrd: https://netboot.example.invalid:8089/rescue/initrd.img
# initrd_signature: https://netboot.example.invalid:8089/rescue/initrd.img.sig
# args: ip=dhcp
#
# Graywolf can be used independently of packet/aprs as a modem/TNC/KISS layer.
# hamstack_graywolf_enabled: true
# hamstack_graywolf_manage_api: true
Expand Down
44 changes: 40 additions & 4 deletions roles/infrastructure/netboot/README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,50 @@
# `infrastructure/netboot`

Provides a deliberately small **HTTP/iPXE content service** for HamStack.
Provides a deliberately small **authenticated HTTPS/iPXE content service** for
HamStack.

The role serves a generated `boot.ipxe` menu and an operator-managed web root.
It is useful once a machine is already capable of executing an iPXE script.
The container exposes TLS only: `hamstack_netboot_tls_certificate_path` and
`hamstack_netboot_tls_private_key_path` identify certificate and key source files
that already exist on the managed host. HamStack copies them into the role's
root-owned `tls` directory on each run and authoritatively manages those copies.
The source files and certificate lifecycle remain operator-owned.

The supported scope intentionally does **not** run DHCP, proxy-DHCP, or TFTP. Those
features can be added after the basic workflow is exercised on real conference
networks. Avoiding an accidental second DHCP server is a feature.

Entries may either chain another iPXE URL or specify kernel/initrd/arguments.
Operators can copy ISO-derived kernels, rescue environments, Debian installer
assets, or custom material into the persistent web root as needed.
Boot clients must retrieve the initial menu through its `https://` endpoint,
trust the server certificate, support iPXE image signatures, and contain the
certificate that signs boot artifacts in their iPXE trust store. The generated
menu permanently enables image trust before displaying entries. It fetches and
verifies every detached signature before executing a chained script or booting a
kernel/initrd pair. Plain HTTP and unsigned entry URLs are rejected during the
Ansible run.

Entries may either chain another signed iPXE script or specify signed
kernel/initrd/arguments:

```yaml
hamstack_netboot_tls_certificate_path: /etc/hamstack/netboot/server.crt
hamstack_netboot_tls_private_key_path: /etc/hamstack/netboot/server.key
hamstack_netboot_entries:
- id: rescue
label: Signed rescue environment
kernel: https://netboot.example.invalid:8089/rescue/vmlinuz
kernel_signature: https://netboot.example.invalid:8089/rescue/vmlinuz.sig
initrd: https://netboot.example.invalid:8089/rescue/initrd.img
initrd_signature: https://netboot.example.invalid:8089/rescue/initrd.img.sig
args: ip=dhcp
- id: installer
label: Signed installer menu
chain: https://boot.example.invalid/installer.ipxe
chain_signature: https://boot.example.invalid/installer.ipxe.sig
```

`hamstack_netboot_https_port` is the published TLS port. It defaults to the
legacy-named `hamstack_netboot_http_port` value so existing port overrides remain
effective; no plaintext listener is created. Operators can copy ISO-derived
kernels, rescue environments, Debian installer assets, or custom material into
the persistent web root as needed, together with their detached signatures.
3 changes: 3 additions & 0 deletions roles/infrastructure/netboot/defaults/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ hamstack_netboot_container_name: hamstack-netboot
hamstack_netboot_data_dir: "{{ (hamstack_data_dir | default('/var/lib/hamstack')) ~ '/netboot' }}"
hamstack_netboot_bind_address: 0.0.0.0
hamstack_netboot_http_port: 8089
hamstack_netboot_https_port: "{{ hamstack_netboot_http_port }}"
hamstack_netboot_tls_certificate_path: ""
hamstack_netboot_tls_private_key_path: ""
hamstack_netboot_menu_title: HamStack Netboot
hamstack_netboot_entries: []
hamstack_netboot_autostart: true
126 changes: 120 additions & 6 deletions roles/infrastructure/netboot/tasks/main.yml
Original file line number Diff line number Diff line change
@@ -1,19 +1,125 @@
---
- name: Deploy HamStack minimal HTTP netboot service
- name: Deploy HamStack authenticated netboot service
when: hamstack_netboot_enabled | bool
block:
- name: Validate netboot TLS source paths
ansible.builtin.assert:
that:
- (hamstack_netboot_tls_certificate_path | default('')) is match('^/')
- (hamstack_netboot_tls_private_key_path | default('')) is match('^/')
fail_msg: >-
Netboot requires absolute paths to an operator-provided TLS certificate
and private key on the managed host.

- name: Inspect netboot TLS certificate source
ansible.builtin.stat:
path: "{{ hamstack_netboot_tls_certificate_path }}"
follow: true
register: _hamstack_netboot_tls_certificate_source

- name: Inspect netboot TLS private key source
ansible.builtin.stat:
path: "{{ hamstack_netboot_tls_private_key_path }}"
follow: true
register: _hamstack_netboot_tls_private_key_source

- name: Validate netboot TLS source files
ansible.builtin.assert:
that:
- _hamstack_netboot_tls_certificate_source.stat.isreg | default(false)
- _hamstack_netboot_tls_private_key_source.stat.isreg | default(false)
fail_msg: >-
The configured netboot TLS certificate and private key must exist as
regular files on the managed host.

- name: Validate signed netboot entries
ansible.builtin.assert:
that:
- (item.id | default('')) is match('^[A-Za-z0-9][A-Za-z0-9._-]*$')
- >-
(
item.chain is defined
and item.kernel is not defined
and item.initrd is not defined
and (item.chain | string) is match('^https://[^\s]+$')
and (item.chain_signature | default('') | string) is match('^https://[^\s]+$')
)
or
(
item.kernel is defined
and item.chain is not defined
and (item.kernel | string) is match('^https://[^\s]+$')
and (item.kernel_signature | default('') | string) is match('^https://[^\s]+$')
and (
item.initrd is not defined
or
(
(item.initrd | string) is match('^https://[^\s]+$')
and (item.initrd_signature | default('') | string) is match('^https://[^\s]+$')
)
)
)
fail_msg: >-
Each netboot entry requires a safe id and exactly one signed boot
mode: an HTTPS chain plus chain_signature, or an HTTPS kernel plus
kernel_signature and, when present, an HTTPS initrd plus
initrd_signature.
loop: "{{ hamstack_netboot_entries }}"
loop_control:
label: "{{ item.id | default('invalid entry') }}"

- name: Install HamStack container runtime for netboot
ansible.builtin.include_role:
name: common
tasks_from: container-runtime

- name: Create netboot content directory
- name: Create netboot content directories
ansible.builtin.file:
path: "{{ hamstack_netboot_data_dir }}/www"
path: "{{ item }}"
state: directory
owner: root
group: root
mode: '0755'
loop:
- "{{ hamstack_netboot_data_dir }}/www"
- "{{ hamstack_netboot_data_dir }}/config"

- name: Create private netboot TLS directory
ansible.builtin.file:
path: "{{ hamstack_netboot_data_dir }}/tls"
state: directory
owner: root
group: root
mode: '0700'

- name: Copy netboot TLS certificate into managed state
ansible.builtin.copy:
src: "{{ hamstack_netboot_tls_certificate_path }}"
remote_src: true
dest: "{{ hamstack_netboot_data_dir }}/tls/server.crt"
owner: root
group: root
mode: '0644'
register: _hamstack_netboot_tls_certificate

- name: Copy netboot TLS private key into managed state
ansible.builtin.copy:
src: "{{ hamstack_netboot_tls_private_key_path }}"
remote_src: true
dest: "{{ hamstack_netboot_data_dir }}/tls/server.key"
owner: root
group: root
mode: '0600'
register: _hamstack_netboot_tls_private_key

- name: Render HamStack netboot HTTPS configuration
ansible.builtin.template:
src: nginx.conf.j2
dest: "{{ hamstack_netboot_data_dir }}/config/default.conf"
owner: root
group: root
mode: '0644'
register: _hamstack_netboot_nginx

- name: Render HamStack iPXE menu
ansible.builtin.template:
Expand All @@ -24,14 +130,22 @@
mode: '0644'
register: _hamstack_netboot_menu

- name: Run HamStack netboot HTTP container
- name: Run HamStack netboot HTTPS container
community.docker.docker_container:
name: "{{ hamstack_netboot_container_name }}"
image: "{{ hamstack_netboot_image }}"
state: started
restart_policy: "{{ 'unless-stopped' if hamstack_netboot_autostart | bool else 'no' }}"
recreate: "{{ _hamstack_netboot_menu.changed }}"
recreate: >-
{{
_hamstack_netboot_menu.changed
or _hamstack_netboot_nginx.changed
or _hamstack_netboot_tls_certificate.changed
or _hamstack_netboot_tls_private_key.changed
}}
published_ports:
- "{{ hamstack_netboot_bind_address }}:{{ hamstack_netboot_http_port }}:80/tcp"
- "{{ hamstack_netboot_bind_address }}:{{ hamstack_netboot_https_port }}:443/tcp"
volumes:
- "{{ hamstack_netboot_data_dir }}/www:/usr/share/nginx/html:ro"
- "{{ hamstack_netboot_data_dir }}/config/default.conf:/etc/nginx/conf.d/default.conf:ro"
- "{{ hamstack_netboot_data_dir }}/tls:/etc/nginx/tls:ro"
11 changes: 8 additions & 3 deletions roles/infrastructure/netboot/templates/boot.ipxe.j2
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#!ipxe
set menu-timeout 8000
set submenu-timeout ${menu-timeout}
imgtrust --permanent || goto failed

:start
menu {{ hamstack_netboot_menu_title }}
Expand All @@ -15,11 +16,15 @@ goto ${selected}
{% for entry in hamstack_netboot_entries %}
:{{ entry.id }}
{% if entry.chain is defined %}
chain {{ entry.chain }} || goto failed
imgfetch --name chain-{{ entry.id }} {{ entry.chain }} || goto failed
imgverify chain-{{ entry.id }} {{ entry.chain_signature }} || goto failed
imgexec chain-{{ entry.id }} || goto failed
{% else %}
kernel {{ entry.kernel }}{% if entry.args is defined and entry.args | length > 0 %} {{ entry.args }}{% endif %}
kernel --name kernel-{{ entry.id }} {{ entry.kernel }}{% if entry.args is defined and entry.args | length > 0 %} {{ entry.args }}{% endif %} || goto failed
imgverify kernel-{{ entry.id }} {{ entry.kernel_signature }} || goto failed
{% if entry.initrd is defined and entry.initrd | length > 0 %}
initrd {{ entry.initrd }}
initrd --name initrd-{{ entry.id }} {{ entry.initrd }} || goto failed
imgverify initrd-{{ entry.id }} {{ entry.initrd_signature }} || goto failed
{% endif %}
boot || goto failed
{% endif %}
Expand Down
16 changes: 16 additions & 0 deletions roles/infrastructure/netboot/templates/nginx.conf.j2
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
server {
listen 443 ssl;
server_name _;

ssl_certificate /etc/nginx/tls/server.crt;
ssl_certificate_key /etc/nginx/tls/server.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_session_tickets off;

root /usr/share/nginx/html;
autoindex off;

location / {
try_files $uri =404;
}
}
Loading