From 7b5d2de6ad769576c07e5ab1703dead319dff8a1 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Mon, 9 Mar 2026 15:44:55 -0600 Subject: [PATCH] Documentation and CHANGELOG updates and corrections Signed-off-by: Jonathon Anderson --- CHANGELOG.md | 26 +++++++++---------- userdocs/server/routes.rst | 3 +++ userdocs/server/security.rst | 48 +++++++++++++++++++----------------- 3 files changed, 41 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 601106e9..be445ea7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). -## v4.6.6, unreleased +## v4.7.0, unreleased ### Fixed @@ -16,7 +16,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- New --partwipe flag for profile and node set +- New `--partwipe` flag for profile and node set - Updated arguments for `ValidString` to match `regexp.MatchString` - New `mig` overlay to configure NVIDIA MIG devices. #2102 - Documented that booting a node twice fixes broken partition tables @@ -27,12 +27,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). if TLS is enabled is not distributed over plain http. - Documented that booting a node twice fixes broken partition tables -- Updated arguments for `ValidString` to match `regexp.MatchString` -- New `mig` overlay to configure NVIDIA MIG devices. #2102 -- TLS with the command `wwctl configure tls` for key management. - Keys can be created automtically or imported. The runtime overlay is - if TLS is enabled is not distributed over plain http. - +- TLS support for `warewulfd` and REST API +- New `wwctl configure tls` command to generate and configure TLS keys and + certificates +- New dedicated `warewulfd` server routes (`/ipxe/`, `/kernel/`, `/image/`, + `/initramfs/`, `/system/`, `/runtime/`, `/grub/`, `/efiboot/`) + +### Changed + +- Runtime overlay download failure during dracut/wwinit boot is now non-fatal; + the node continues to boot and `wwclient` retries the download at runtime. +- `hosts` overlay added to the default system overlay list ## v4.6.5, 2026-01-12 @@ -48,11 +53,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - New `range6 start` and `range6 end` in `warewulf.conf:dhcp`. #2068 - New `Gateway6` network device field. #2068 - New `systemd-networkd` overlay. #2068 -- `wwclient.aarch64` overlay always provides an aarch64 wwclient executable. -- `wwclient.x86_64` overlay always provides an x86_64 wwclient executable. -- systemd-networkd overlay with IPv6 support -- `wwctl overlay info` lists the variables used by an overlay template -- TLS ### Changed diff --git a/userdocs/server/routes.rst b/userdocs/server/routes.rst index 7cc299b8..9d75ec0f 100644 --- a/userdocs/server/routes.rst +++ b/userdocs/server/routes.rst @@ -277,6 +277,9 @@ When enabled in ``warewulf.conf``, ``warewulfd`` exposes a REST API under ``/api/``. The API provides programmatic access to nodes, profiles, images, and overlays. Interactive documentation is available at ``/api/docs``. +When TLS is enabled, access to the REST API can additionally be restricted to +HTTPS-only requests by setting ``api: tls: true`` in ``warewulf.conf``. + See :ref:`rest-api` for full details. .. _server-routes-security: diff --git a/userdocs/server/security.rst b/userdocs/server/security.rst index a2109f4b..a0aaa068 100644 --- a/userdocs/server/security.rst +++ b/userdocs/server/security.rst @@ -40,9 +40,9 @@ There are multiple ways to secure the Warewulf provisioning process: This means that the nodes only boot the kernel which is provided by the distributor and also custom complied modules can't be loaded. -* Tls (transport layer security) can be enabled for the warewulf server. However - the https is only used for runtime overlays. The kernel and system image are *always* - transfered unencrypted as iPXE and grub can't handle https. +* TLS (transport layer security) can be enabled for the Warewulf server. When + enabled, HTTPS is used when transferring runtime overlays. The kernel and + system image are *always* transferred unencrypted. SELinux ======= @@ -87,33 +87,35 @@ with the Warewulf server. nft list ruleset >/etc/nftables.conf systemctl restart nftables +TLS / HTTPS +=========== -HTTPS -===== - -The https functionality can be enabled by setting +TLS can be enabled by setting ``tls: true`` in the Warewulf server +configuration. .. code-block:: yaml -.. -.. warewulf: -.. tls: true -.. secure port: 9874 -.. -Which will enable a https server on the secure port. The certificate and key -can be created as self signed key with ``wwctl configure keys --create``. The -keys and certificate are stored if not configured otherwise as + warewulf: + tls: true + tls port: 9874 -.. code-block:: console -.. -.. /etc/warewulf/tls/warewulf.crt # PEM certificate -.. /etc/warewulf/tls/warewulf.key # PEM RSA Key +This enables an HTTPS server on the TLS port (default: ``9874``). A key and +self-signed certificate can be created with ``wwctl configure tls``. +By default, the key and certificate are stored in ``/etc/warewulf/tls/``. +You can also import your own keys with ``wwctl configure tls --import``. -For the key and certifcate generation no addiotional parameters can be set, but -you can import your own keys, with ``wwctl configure keys import``. +If HTTPS is enabled the delivery of the runtime overlay is disabled over HTTP, +and the runtime overlay is only retrieved by ``wwclient``. -If HTTPS is enabled the delivery of the runtime overlays is disabled over HTTP, so -you **must** use `wwclient` to get the runtime overlays. +To additionally require TLS for access to the REST API, set ``tls: true`` under +the ``api:`` section: +.. code-block:: yaml + + api: + enabled: true + tls: true + +When ``api: tls`` is set, the REST API rejects plain-HTTP requests.