diff --git a/FEATURES.md b/FEATURES.md index b0fe516..67fa537 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -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. diff --git a/docs/configuration.md b/docs/configuration.md index babfd62..fcd1c37 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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. diff --git a/docs/role-status.md b/docs/role-status.md index 1e4463c..0d79cef 100644 --- a/docs/role-status.md +++ b/docs/role-status.md @@ -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. @@ -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. diff --git a/docs/variables.md b/docs/variables.md index e1ebb2d..464995e 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -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` diff --git a/inventory/example/host_vars/example-node.yml b/inventory/example/host_vars/example-node.yml index ee87fc6..309255a 100644 --- a/inventory/example/host_vars/example-node.yml +++ b/inventory/example/host_vars/example-node.yml @@ -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 diff --git a/roles/infrastructure/netboot/README.md b/roles/infrastructure/netboot/README.md index 0a31c89..349dcb9 100644 --- a/roles/infrastructure/netboot/README.md +++ b/roles/infrastructure/netboot/README.md @@ -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. diff --git a/roles/infrastructure/netboot/defaults/main.yml b/roles/infrastructure/netboot/defaults/main.yml index d8873e4..43b3f9f 100644 --- a/roles/infrastructure/netboot/defaults/main.yml +++ b/roles/infrastructure/netboot/defaults/main.yml @@ -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 diff --git a/roles/infrastructure/netboot/tasks/main.yml b/roles/infrastructure/netboot/tasks/main.yml index a74761b..711eb92 100644 --- a/roles/infrastructure/netboot/tasks/main.yml +++ b/roles/infrastructure/netboot/tasks/main.yml @@ -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: @@ -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" diff --git a/roles/infrastructure/netboot/templates/boot.ipxe.j2 b/roles/infrastructure/netboot/templates/boot.ipxe.j2 index 74adc86..34c967e 100644 --- a/roles/infrastructure/netboot/templates/boot.ipxe.j2 +++ b/roles/infrastructure/netboot/templates/boot.ipxe.j2 @@ -1,6 +1,7 @@ #!ipxe set menu-timeout 8000 set submenu-timeout ${menu-timeout} +imgtrust --permanent || goto failed :start menu {{ hamstack_netboot_menu_title }} @@ -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 %} diff --git a/roles/infrastructure/netboot/templates/nginx.conf.j2 b/roles/infrastructure/netboot/templates/nginx.conf.j2 new file mode 100644 index 0000000..3da190d --- /dev/null +++ b/roles/infrastructure/netboot/templates/nginx.conf.j2 @@ -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; + } +}