kelvin/warewulf
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Documentation reorg for v4.6.0

Browse Source 
Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2025-02-18 16:26:05 -07:00
parent 98695cbbff
commit 9e41378e1c
65 changed files with 3493 additions and 4654 deletions
Download Patch File Download Diff File Expand all files Collapse all files

393
userdocs/server/bootloaders.rst Normal file
View File

@@ -0,0 +1,393 @@
===========
Bootloaders
===========
Warewulf uses iPXE as its default network bootloader. As a tech preview, support
for GRUB is also available, which adds support for secure boot.
Also as a tech preview, Warewulf may also use iPXE or GRUB to boot a dracut
initramfs as an initial stage before loading the image. This is called a
two-stage boot.
Booting with iPXE
=================
The ``/etc/warewulf/ipxe/`` directory contains *text/templates* that are used by
the Warewulf configuration process to configure the ``ipxe`` service.
.. graphviz::
digraph G{
node [shape=box];
compound=true;
edge [label2node=true]
bios [shape=record label="{BIOS | boots from DHCP/next-server via TFTP}"]
subgraph cluster0 {
label="iPXE boot"
iPXE;
ipxe_cfg [shape=record label="{ipxe.cfg|generated for each node}"];
iPXE -> ipxe_cfg [label="http"];
}
bios->iPXE [lhead=cluster0,label="iPXE.efi"];
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"];
ipxe_cfg->kernel[ltail=cluster0,label="http"];
}
Starting in v4.5.0, Warewulf no longer includes an iPXE binary. In stead, by
default Warewulf uses the iPXE that comes with the host OS.
Unfortunately, we’ve encountered a few instances where bugs in the OS-provided
iPXE that sometimes make booting a full OS image as an "initrd" unreliable.
:ref:`Building iPXE locally`, using a more recent "version" of the iPXE source
code, can alleviate some of these issues.
Another alternative is :ref:`booting with dracut`, which uses the Linux kernel
to load the full OS image, avoiding the issue entirely.
.. _Building iPXE locally:
Building iPXE locally
---------------------
By default (as of v4.5.0) Warewulf packages use iPXE from the host operating
system rather than bundling iPXE binaries with Warewulf. However, sometimes the
specific build included in the host OS has bugs or missing features, and a local
build of iPXE is necessary.
The Warewulf project provides a `build-ipxe.sh`_ script to simplify the process
of building iPXE locally.
.. _build-ipxe.sh: https://github.com/warewulf/warewulf/blob/main/scripts/build-ipxe.sh
.. code-block:: console
# curl -LO https://raw.githubusercontent.com/warewulf/warewulf/main/scripts/build-ipxe.sh
# bash build-ipxe.sh -h
Usage: build-ipxe.sh
[-h] (help)
TARGETS: bin-x86_64-pcbios/undionly.kpxe bin-x86_64-efi/snponly.efi bin-arm64-efi/snponly.efi
IPXE_BRANCH: master
DESTDIR: /usr/local/share/ipxe
Running build-ipxe.sh
^^^^^^^^^^^^^^^^^^^^^
The script, by default, builds iPXE for x86_64 BIOS, x86_64 EFI, and arm64 EFI
from the master branch on the iPXE project GitHub and stores the resultant
builds in ``/usr/local/share/ipxe/``. (These parameters can be adjusted by
setting ``TARGETS``, ``IPXE_BRANCH``, and ``DESTDIR`` environment variables,
with the current values shown in the ``-h`` output for reference.)
.. code-block:: console
# mkdir -p /usr/local/share/ipxe
# bash build-ipxe.sh
[...]
# ls -1 /usr/local/share/ipxe/
bin-arm64-efi-snponly.efi
bin-x86_64-efi-snponly.efi
bin-x86_64-pcbios-undionly.kpxe
.. note::
Building for aarch64 requires the package ``gcc-aarch64-linux-gnu``.
Build options
^^^^^^^^^^^^^
By default, ``build-ipxe.sh`` enables support for `ZLIB`_ and `GZIP`_ images, as
well as commands for managing `VLANs`_ and the `framebuffer console`_. The
x86_64 build also enables support for the `serial console`_.
.. _ZLIB: https://ipxe.org/buildcfg/image_zlib
.. _GZIP: https://ipxe.org/buildcfg/image_gzip
.. _VLANs: https://ipxe.org/buildcfg/vlan_cmd
.. _framebuffer console: https://ipxe.org/buildcfg/console_framebuffer
.. _serial console: https://ipxe.org/buildcfg/console_serial
Additional `build options`_ can be configured by editing the ``build-ipxe.sh`` script.
For example, the x86_64 build is configured in the ``configure_x86_64`` function.
.. _build options: https://ipxe.org/buildcfg
.. code-block:: bash
function configure_x86_64 {
sed -i.bak \
-e 's,//\(#define.*CONSOLE_SERIAL.*\),\1,' \
-e 's,//\(#define.*CONSOLE_FRAMEBUFFER.*\),\1,' \
config/console.h
sed -i.bak \
-e 's,//\(#define.*IMAGE_ZLIB.*\),\1,' \
-e 's,//\(#define.*IMAGE_GZIP.*\),\1,' \
-e 's,//\(#define.*VLAN_CMD.*\),\1,' \
config/general.h
}
For example, the ``imgextract`` command can be `explicitly enabled`_.
.. _explicitly enabled: https://ipxe.org/buildcfg/image_archive_cmd
.. code-block:: bash
function configure_x86_64 {
sed -i.bak \
-e 's,//\(#define.*CONSOLE_SERIAL.*\),\1,' \
-e 's,//\(#define.*CONSOLE_FRAMEBUFFER.*\),\1,' \
config/console.h
sed -i.bak \
-e 's,//\(#define.*IMAGE_ZLIB.*\),\1,' \
-e 's,//\(#define.*IMAGE_GZIP.*\),\1,' \
-e 's,//\(#define.*VLAN_CMD.*\),\1,' \
-e 's,//\(#define.*IMAGE_ARCHIVE_CMD.*\),\1,' \
config/general.h
}
.. note::
``IMG_ARCHIVE_CMD`` is already enabled by default in the iPXE master branch,
but only takes effect when at least one archive image format is configured.
This is the case in the default state of ``build-ipxe.sh``, which enables
support for ZLIB and GZIP archive image formats.
Configuring Warewulf (≥ v4.5.0)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In Warewulf v4.5.0, Warewulf can be configured to use these files using the
``tftp.ipxe`` and ``paths.ipxesource`` configuration parameters in
``warewulf.conf``.
.. code-block:: yaml
# warewulf.conf
tftp:
ipxe:
"00:00": bin-x86_64-pcbios-undionly.kpxe
"00:07": bin-x86_64-efi-snponly.efi
"00:09": bin-x86_64-efi-snponly.efi
"00:0B": bin-arm64-efi-snponly.efi
paths:
ipxesource: /usr/local/share/ipxe
Restart ``warewulfd`` following the change to ``warewulf.conf``. Then remove any
previously-provisioned files from ``/var/lib/tftpboot/warewulf/`` and use
``wwctl configure tftp`` and ``wwctl configure dhcp`` to re-provision the TFTP
files and update the DHCP configuration.
.. code-block:: console
# sudo systemctl restart warewulfd
# rm /var/lib/tftpboot/warewulf/*
# wwctl configure tftp
Writing PXE files to: /var/lib/tftpboot/warewulf
Enabling and restarting the TFTP services
# wwctl configure dhcp
Building overlay for wwctl1: host
Enabling and restarting the DHCP services
Configuring Warewulf (< v4.5.0)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Prior to v4.5.0, Warewulf packages included bundled builds of iPXE and did not
provide a mechanism for configuring which iPXE to use. To use a custom iPXE
before v4.5.0, replace the bundled builds included with Warewulf. After that,
remove any previously-provisioned files from ``/var/lib/tftpboot/warewulf/`` and
use ``wwctl configure tftp`` to re-provision the TFTP files.
.. code-block:: console
# cp /usr/local/share/ipxe/bin-arm64-efi-snponly.efi /usr/share/warewulf/ipxe/arm64.efi
# cp /usr/local/share/ipxe/bin-x86_64-efi-snponly.efi /usr/share/warewulf/ipxe/x86_64.efi
# cp /usr/local/share/ipxe/bin-x86_64-pcbios-undionly.kpxe /usr/share/warewulf/ipxe/x86_64.kpxe
# rm /var/lib/tftpboot/warewulf/*
# wwctl configure tftp
Writing PXE files to: /var/lib/tftpboot/warewulf
Enabling and restarting the TFTP services
Booting with GRUB
=================
Support for GRUB as a network bootloader (replacing iPXE) is available in
Warewulf as a technology preview.
.. graphviz::
digraph G{
node [shape=box];
compound=true;
edge [label2node=true]
bios [shape=record label="{BIOS | boots from DHCP/next-server via TFTP}"]
bios->shim [lhead=cluster1,label="shim.efi"];
subgraph cluster1{
label="Grub boot"
shim[shape=record label="{shim.efi|from ww4 host}"];
grub[shape=record label="{grubx64.efi | name hardcoded in shim.efi|from ww4 host}"]
shim->grub[label="TFTP"];
grubcfg[shape=record label="{grub.cfg|static under TFTP root}"];
grub->grubcfg[label="TFTP"];
}
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"];
grubcfg->kernel[ltail=cluster1,label="http"];
}
Instead of the iPXE starter a combination of `shim and GRUB
<https://www.suse.com/c/uefi-secure-boot-details/>`_ can be used with the
advantage that secure boot can be used. That means that only the signed kernel
of a distribution can be booted. This can be a huge security benefit for some
scenarios.
In order to enable the grub boot method it has to be enabled in `warewulf.conf`.
.. code-block:: yaml
warewulf:
grubboot: true
Nodes which are not known to Warewulf are booted with the shim/grub from the
Warewulf server host.
Secure boot
-----------
.. graphviz::
digraph foo {
node [shape=box];
subgraph boot {
"EFI" [label="EFI",row=boot];
"Shim" [label="Shim",row=boot];
"Grub" [label="Grub",row=boot];
"Kernel" [label="kernel",row=boot];
EFI -> Shim[label="Check for Microsoft signature"];
Shim -> Grub[label="Check for Distribution signature"];
Grub->Kernel[label="Check for Distribution or MOK signature"];
}
}
If secure boot is enabled at every step a signature is checked and the boot
process fails if this check fails. The shim typically only includes the key for
a single operating system, which means that each distribution needs separate
`shim` and `grub` executables. Warewulf extracts these binaries from the images.
If the node is unknown to Warewulf or can't be identified during the TFTP boot
phase, the shim/grub binaries of the host in which Warewulf is running are used.
Install shim and efi
--------------------
`shim.efi` and `grub.efi` must be installed in the image for it to be
booted by GRUB.
.. code-block:: console
# wwctl image shell leap15.5
[leap15.5] Warewulf> zypper install grub2 shim
# wwctl image shell rocky9
[rocky9] Warewulf> dnf install shim-x64.x86_64 grub2-efi-x64.x86_64
These packages must also be installed on the Warewulf server host to enable
node discovery using GRUB.
HTTP boot
---------
Modern EFI systems have the possibility to directly boot per http. The flow
diagram is the following:
.. graphviz::
digraph G{
node [shape=box];
efi [shape=record label="{EFI|boots from URI defined in filename}"];
shim [shape=record label="{shim.efi|replaces shim.efi with grubx64.efi in URI|extracted from node image}"];
grub [shape=record label="{grub.efi|checks for grub.cfg|extracted from node image}"]
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"];
efi->shim [label="http"];
shim->grub [label="http"];
grub->kernel [label="http"];
}
Warewulf delivers the initial `shim.efi` and `grub.efi` via http as taken
directly from the node's assigned image.
.. _booting with dracut:
Booting with dracut
===================
Some systems, typically due to limitations in their BIOS or EFI firmware, are
unable to load image of a certain size directly with a traditional bootloader,
either iPXE or GRUB. As a workaround for such systems, Warewulf can be
configured to load a dracut initramfs from the image and to use that initramfs
to load the full image.
Warewulf provides a dracut module to configure the dracut initramfs to load the
image. This module is available in the ``warewulf-dracut`` subpackage, which
must be installed in the image.
With the ``warewulf-dracut`` package installed, you can build an initramfs
inside the image.
.. code-block:: shell
dnf -y install warewulf-dracut
dracut --force --no-hostonly --add wwinit --regenerate-all
.. note::
In some systems, such as ``rockylinux:8``, it may be necessary to remove
``/etc/machine-id`` for dracut to properly generate the initramfs in the
location that Warewulf is expecting.
To direct iPXE to fetch the node's initramfs image and boot with dracut
semantics, set an ``IPXEMenuEntry`` tag for the node.
.. note::
Warewulf configures iPXE with a template located at
``/etc/warewulf/ipxe/default.ipxe``. Inspect the template to learn more about
the dracut booting process.
.. code-block:: shell
wwctl node set wwnode1 --tagadd IPXEMenuEntry=dracut
.. note::
The IPXEMenuEntry variable may be set at the node or profile level.
Alternatively, to direct GRUB to fetch the node's initramfs image and boot with
dracut semantics, set a ``GrubMenuEntry`` tag for the node.
.. note::
Warewulf configures GRUB with a template located at
``/etc/warewulf/grub/grub.cfg.ww``. Inspect the template to learn more about
the dracut booting process.
.. code-block:: shell
wwctl node set wwnode1 --tagadd GrubMenuEntry=dracut
.. note::
The ``GrubMenuEntry`` variable may be set at the node or profile level.
During boot, ``warewulfd`` will detect and dynamically serve an initramfs from a
node's image in much the same way that it can serve a kernel from an image. This
image is loaded by iPXE (or GRUB) which directs dracut to fetch the node's image
during boot.
The wwinit module provisions to tmpfs. By default, tmpfs is permitted to use up
to 50% of physical memory. This size limit may be adjusted using the kernel
argument `wwinit.tmpfs.size`. (This parameter is passed to the `size` option
during tmpfs mount. See ``tmpfs(5)`` for more details.)

345
userdocs/server/configuration.rst Normal file
View File

@@ -0,0 +1,345 @@
====================
Server Configuration
====================
By default, the Warewulf server configuration is located at
``/etc/warewulf/warewulf.conf``. This is a YAML-formatted configuration file
used by to configured the Warewulf server itself and its external services.
An initial ``warewulf.conf`` is packaged with Warewulf. Each section is covered
in detail below.
Once Warewulf has been installed and configured:
* run ``wwctl configure --all`` to reconfigure external services
* run ``systemctl restart warewulfd`` to apply the configuration to the Warewulf
server
Re-run both of these commands when making changes to ``warewulf.conf``.
.. code-block:: yaml
ipaddr: 192.168.1.1
netmask: 255.255.255.0
network: 192.168.1.0
warewulf:
port: 9873
secure: true
update interval: 60
autobuild overlays: true
host overlay: true
grubboot: false
dhcp:
enabled: true
template: default
systemd name: dhcpd
tftp:
enabled: true
tftproot: /var/lib/tftpboot
systemd name: tftp
ipxe:
00:0B: arm64-efi/snponly.efi
"00:00": undionly.kpxe
"00:07": ipxe-snponly-x86_64.efi
"00:09": ipxe-snponly-x86_64.efi
nfs:
enabled: true
systemd name: nfsd
ssh:
key types:
- ed25519
- ecdsa
- rsa
- dsa
image mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
paths:
bindir: /usr/bin
sysconfdir: /etc
localstatedir: /var/lib
cachedir: /var/cache
ipxesource: /usr/share/ipxe
srvdir: /var/lib
firewallddir: /usr/lib/firewalld/services
systemddir: /usr/lib/systemd/system
datadir: /usr/share
wwoverlaydir: /var/lib/warewulf/overlays
wwchrootdir: /var/lib/warewulf/chroots
wwprovisiondir: /var/lib/warewulf/provision
wwclientdir: /warewulf
warewulf
========
.. code-block:: yaml
ipaddr: 192.168.1.1
netmask: 255.255.255.0
network: 192.168.1.0
warewulf:
port: 9873
secure: true
update interval: 60
autobuild overlays: true
host overlay: true
grubboot: false
* ``ipaddr``: The Warewulf server address on the cluster network. This
configuration must match the server's IP address.
If ``ipaddr`` is specified as a CIDR address, ``netmask`` and ``network`` may
be omitted.
* ``netmask``: The netmask for the cluster network.
* ``network``: The address of the cluster network itself.
* ``warewulf:port``: This is the port that the Warewulf web server will be
listening on. It is recommended not to change this so there is no misalignment
with node's expectations of how to contact the Warewulf service.
* ``warewulf:secure``: When ``true``, this limits the Warewulf server to only
respond to runtime overlay requests originating from a privileged port. This
prevents non-root users from requesting the runtime overlay, which may contain
sensitive information.
When ``true``, ``wwclient`` uses TCP port 987 by default. (A different port
can be specified at ``wwclient:port``.)
Changing this option requires rebuilding node overlays and rebooting compute
nodes to configure them to use a privileged port for `wwclient`.
* ``warewulf:update interval``: This defines the frequency (in seconds) with
which the Warewulf client on the compute node fetches overlay updates.
* ``warewulf:autobuild overlays``: Controls whether per-node overlays will
automatically be rebuilt. (e.g., when an underlying overlay is changed)
Overlay autobuild is not 100% reliable; but it is particularly useful for
building overlays for new nodes.
* ``warewulf:host overlay``: Controls whether the special ``host`` overlay is
applied to the Warewulf server during configuration. (The host overlay is used
to configure external services.)
* ``warewulf::grubboot``: Controls whether iPXE (default) or GRUB is used as the
network bootloader.
dhcp
====
The DHCP external service can be configured explicitly with ``wwctl configure
dhcp``. This (re)writes the DHCP configuration and enables and (re)starts the
DHCP service.
.. code-block:: yaml
dhcp:
enabled: true
template: default
systemd name: dhcpd
* ``dhcp:enabled``: Whether Warewulf should configure a DHCP server on the
cluster network. Set to ``false`` when managing DHCP separately.
* ``dhcp:template`` An optional DHCP template variable to control the
generation of the DHCP template.
Specifying ``template: static`` populates ``dhcpd.conf`` with static leases
for each host, bypassing the DHCP range. (Run ``wwctl configure dhcp`` to
update ``dhcpd.conf`` when nodes are added, removed, or changed.)
* ``dhcp:range start`` and ``dhcp:range end``: Defines a dynamic DHCP range to
use when provisioning cluster nodes. This address range must exist in the
cluster network defined above. (Otherwise, the DHCP server will fail to
start).
This range should not overlap with IP addresses assigned to nodes in
``nodes.conf``.
* ``dhcp:systemd name``: Identifies the systemd service that manages the DHCP
service. Used during ``wwctl configure dhcp`` to restart the service.
tftp
====
The TFTP external service can be configured explicitly with ``wwctl configure
tftp``. This writes the appropriate bootloader executables to the TFTP root
directory and enables the TFTP service.
.. code-block:: yaml
tftp:
enabled: true
tftproot: /var/lib/tftpboot
systemd name: tftp
ipxe:
00:0B: arm64-efi/snponly.efi
"00:00": undionly.kpxe
"00:07": ipxe-snponly-x86_64.efi
"00:09": ipxe-snponly-x86_64.efi
* ``tftp:enabled``: Whether Warewulf should configure a TFTP server on the
cluster network. Set to ``false`` when managing TFTP separately.
* ``tftp:tftproot``: Identifies the local path being served by the managed TFTP
server. Warewulf creates a ``warewulf/`` subdirectory and copies iPXE and/or
GRUB bootloader files to this location depending on the server configuration.
* ``systemd name``: Identifies the systemd service that manages the TFTP
service. Used during ``wwctl configure tftp`` to restart the service.
* ``ipxe``: A map of DHCP option architecture-types to the iPXE binary that
should be used for that architecture. iPXE binaries are searched for in
``paths:ipxesource``. By default, these paths correspond to the location of
the correct iPXE binary for each architecture in the distribution iPXE
packages; but they can be specified explicitly when providing a local iPXE
build.
nfs
===
The NFS external service can be configured explicitly with ``wwctl configure
nfs``. This configures the NFS server (particularly ``/etc/exports``) on the
Warewulf server and enables and starts the NFS service.
.. code-block:: yaml
nfs:
enabled: true
export paths:
- path: /home
export options: rw,sync
- path: /opt
export options: ro,sync,no_root_squash
systemd name: nfsd
* ``nfs:enabled``: Whether Warewulf should configure an NFS server on the
cluster network. Set to ``false`` when not required or when managing NFS
separately.
* ``nfs:export paths``: A list of NFS exports to configure on the Warewulf
server. Each export defines a ``path`` to be exported and the ``export
options`` for that export.
* ``systemd name``: Identifies the systemd service that manages the NFS
service. Used during ``wwctl configure nfs`` to restart the service.
ssh
===
*New in Warewulf v4.5.1*
SSH key types to generate during ``wwctl configure ssh``. This create the
appropriate host keys (stored in ``/etc/warewulf/keys/``) and authentication
keys for passwordless ``ssh`` to cluster nodes. It also installs shell profiles
``/etc/profile.d/ssh_setup.csh`` and ``/etc/profile.d/ssh_setup.sh`` to
initialize authentication keys for new users if and when they log into the
Warewulf server.
.. code-block:: yaml
ssh:
key types:
- ed25519
- ecdsa
- rsa
- dsa
* ``ssh:key types``: Warewulf generate host keys for each listed key type.
The first listed key type is used to generate authentication ssh keys.
image mounts
============
A list of paths to temporarily mount from the Warewulf server into an image
during ``wwctl image exec`` and ``wwctl image shell``, typically to allow them
to operate in the host environment prior to deployment.
.. code-block:: yaml
image mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
* ``image mounts:source``: The path on the Warewulf server to mount into the
image.
* ``image mounts:dest``: The path in the image to use for the mount.
* ``image mounts::readonly``: Whether the mount should be read-only (``true``)
or allow writes into the server path (``false``).
* ``image mounts::copy``: When ``true``, copy files into the image rather than
mount. This is useful for initializing files with a starting value from the
Warewulf server that should then be maintained as part of the image.
paths
=====
*New in Warewulf v4.5.0*
Override paths to images, overlays, and other Warewulf components.
.. code-block:: yaml
paths:
sysconfdir: /etc
cachedir: /var/cache
ipxesource: /usr/share/ipxe
datadir: /usr/share
wwoverlaydir: /var/lib/warewulf/overlays
wwchrootdir: /var/lib/warewulf/chroots
wwprovisiondir: /var/lib/warewulf/provision
wwclientdir: /warewulf
* ``paths:sysconfdir``: The parent directory for the ``warewulf`` configuration
directory, which stores ``warewulf.conf`` and ``nodes.conf``.
* ``paths::cachedir``: The parent directory for the ``warewulf`` cache of OCI
images during ``wwctl image import``.
* ``paths:ipxesource``: Where to get iPXE binaries. These files are copied to
``warewulf.conf:tftp:tftproot`` by ``wwctl configure tftp``.
* ``datadir``: Parent directory for distribution overlays and BMC templates.
* ``paths:wwoverlaydir``: Parent directory for site overlays.
* ``paths:wwchrootdir``: Parent directory for Warewulf images.
* ``paths:wwprovisiondir``: The destination for built images and overlay images.
* ``paths:wwclientdir``: Where ``wwclient`` looks for its configuration on a
provisioned node.
wwclient
========
Configuration for the ``wwclient`` service on cluster nodes.
.. code-block:: yaml
wwclient:
port: 987
* ``wwclient:port``: The source port used by ``wwclient``. By default an
ephemeral port is selected; but ``warewulf.conf:warewulf:secure: true``
requires a known privileged port.
``wwclient`` will use the TCP port "987" by default if ``secure: true``; but,
if that port is otherwise in use, a different port may be specified.
hostfile
========
There are no explicit "hostfile" configuration options in ``warewulf.conf``; but
``wwctl configure hostfile`` updates the Warewulf server's ``/etc/hosts`` file
to include expected configuration for the server itself as well as the known
names of the cluster nodes and thier interfaces.
Entries from the Warewulf server's ``/etc/hosts`` file are distributed to
cluster nodes by the "hosts" overlay.

63
userdocs/server/dnsmasq.rst Normal file
View File

@@ -0,0 +1,63 @@
=============
Using dnsmasq
=============
As an experimental feature, it is possible to use ``dnsmasq`` instead of the ISC
``dhcpd`` server and ``TFTP`` server.
In order to keep the file ``/etc/dnsmasq.d/ww4-hosts.conf`` is created and must
be included in the main ``dnsmasq.conf`` via the ``conf-dir=/etc/dnsmasq.d``
option.
Installation
============
Before the installation, make sure that ``dhcpd`` and ``tftp`` are disabled.
You can do that with the commands:
.. code-block:: shell
systemctl disable --now dhcpd
systemctl disable --now tftp
Now you can install ``dnsmasq``.
.. code-block:: shell
# Rocky Linux
dnf install dnsmasq
# SUSE
zypper install dnsmasq
After the installation, instruct ``warewulf`` to use ``dnsmasq`` as its
``dhcpd`` and ``tftp`` service. This is done in the server configuration file,
typically at ``/etc/warewulf/warewulf.conf``:
.. code-block:: yaml
tftp:
systemd name: dnsmasq
dhcp:
systemd name: dnsmasq
The configuration of ``dnsmasq`` often doesn't need to be changed, as the
default configuration includes all files with following pattern
``/etc/dnsmasq.d/*conf`` into its configuration. This configuration is created
by the overlay template ``host:/etc/dnsmasq.d/ww4-hosts.conf.ww``.
.. note::
In certain distributions, such as Rocky Linux 9, ``dnsmasq`` is configured to
listen locally via the ``interface=lo`` option by default. Replace this entry
in ``/etc/dnsmasq.conf`` with the interface associated with your Warewulf
network, or remove/comment out the interface option entirely to enable
listening on all interfaces.
Once the Warewulf configuration has been updated, re-deploy the configuration
and restart ``warewulfd``.
.. code-block:: shell
wwctl configure --all
systemctl restart warewulfd.service

145
userdocs/server/installation.rst Normal file
View File

@@ -0,0 +1,145 @@
===================
Server Installation
===================
There are multiple methods to install a Warewulf server. This page describes
some of those methods.
Binary RPMs
===========
The Warewulf project builds binary RPMs as part of its CI/CD process. You can
obtain them from the `GitHub releases`_ page.
.. _GitHub releases: https://github.com/warewulf/warewulf/releases
Rocky Linux 9
-------------
.. code-block:: console
# dnf install https://github.com/warewulf/warewulf/releases/download/v4.6.0rc2/warewulf-4.6.0rc2-1.el9.x86_64.rpm
openSuse Leap
-------------
.. code-block:: console
# zypper install https://github.com/warewulf/warewulf/releases/download/v4.6.0rc2/warewulf-4.6.0rc2-1.suse.lp155.x86_64.rpm
Container images
================
Warewulf can be built in a Linux container. This can be especially useful for
testing and development, or to replace traditional package installation. It is
also possible to only use the container for building and the install it in the
host system afterwards. For that look at the INSTALL, UNINSTALL and PURGE labels
inside the `Dockerfile`_
.. _Dockerfile: https://github.com/warewulf/warewulf/blob/main/Dockerfile
Docker
------
.. code-block:: console
# docker build -t warewulf .
# docker run -d --replace --name warewulf-test --privileged --net=host -v /:/host -v /etc/warewulf:/etc/warewulf -v /var/lib/warewulf/:/var/lib/warewulf/ -e NAME=warewulf-test -e IMAGE=warewulf warewulf
Systemd-nspawn
--------------
Warewulf runs multiple services inside one single container and uses systemd as
init system. As such, it might be better to use `systemd-nspawn`_, which was
explicitly made to run containers with a full init system.
.. _systemd-nspawn: https://www.freedesktop.org/software/systemd/man/latest/systemd-nspawn.html
.. code-block:: console
# docker build -t warewulf .
# mkdir warewulf-nspawn
# docker export "$(docker create --name warewulf-test warewulf true)" | tar -x -C warewulf-nspawn
# systemd-nspawn -D warewulf-nspawn/ passwd
# systemd-nspawn -D warewulf-nspawn/ --boot
Compiled from Source
====================
Before you build the Warewulf source code you will first need to install the
build dependencies:
* ``make``: This should be available via your Linux distribution's package
manager (e.g. ``dnf install make``)
* ``go``: Golang is also available on most current Linux distributions, but you
can also install `the most recent version. <https://golang.org/dl/>`_
* Depending on your Linux Distribution, you may need to install other
development packages. Typically it is recommended to install the entire
development group.
.. code-block::
dnf groupinstall "Development Tools"
Once these dependencies are installed, you can obtain and build the source code.
Release Tarball
---------------
The Warewulf project releases source distributions alongside its binary RPMs.
You can obtain them from the `GitHub releases`_ page.
Select the version you wish to install and download the tarball to any
location on the server, then follow these directions making the
appropriate substitutions:
.. code-block:: bash
curl -LO https://github.com/warewulf/warewulf/releases/download/v4.6.0rc2/warewulf-4.6.0rc2.tar.gz
tar -xf warewulf-4.6.0rc2.tar.gz
cd warewulf-4.6.0rc2
make all && sudo make install
Git
---
You can install different versions of Warewulf from its Git tags or branches.
The ``main`` branch is where most active development occurs, so if you want to
obtain the latest and greatest version of Warewulf, this is where to go. But be
forewarned, using a snapshot from ``main`` is not guaranteed to be stable or
generally supported for production.
If you are building for production, it is best to download a release tarball
from the main site, the GitHub releases page, or from a Git tag.
.. code-block:: bash
git clone https://github.com/warewulf/warewulf.git
cd warewulf
git checkout main # or switch to a tag like 'v4.6.0rc2'
make all && sudo make install
Runtime Dependencies
--------------------
In its default configuration, Warewulf requires some operating system provided
services. Generally these are provided by your distribution.
* ``dhcp-server``
* ``tftp-server``
* ``nfs-utils``
If you are using an Enterprise Linux compatible distribution you can install
them with ``dnf install dhcp-server tftp-server nfs-utils``.
Starting warewulfd
==================
The Warewulf installation registers the Warewulf service with systemd, so it
should be as easy to start/stop/check as any other systemd service:
.. code-block:: console
# systemctl enable --now warewulfd

84
userdocs/server/security.rst Normal file
View File

@@ -0,0 +1,84 @@
========
Security
========
While certain parallelization and high performance library capabilities still
require lowering the security threshold within a cluster, Warewulf strives to
support good security practices within the cluster wherever possible.
Provisioning Security
=====================
Provisioning is, by default, a relatively "insecure" process: there is generally
nothing preventing a user on a cluster node from spoofing a provision request
and downloading the node image and overlays for inspection. If any of these
include secrets (e.g., private keys) they are at risk of exposure.
There are multiple ways to secure the Warewulf provisioning process:
* The best way to secure the provisioning process is to dedicate a vLAN
specifically for provisioning, and then not make that vLAN available in the
provisioned environment. Warewulf can be used in such an environment (without
``wwclient``) but you must consult your switch documentation and features to
implement a default vLAN for provisioning and to ensure that the runtime
operating system is configured for a different tagged vLAN once booted.
* Warewulf can leverage hardware "asset tags" which almost all vendors support.
This is a configurable firmware string that is accessible only via root or
physical access. During provisioning (as well as post provisioning via
``wwclient``) Warewulf sends the detected asset tag to the Warewulf server as
a "shared secret" token. If the node is also configured with an ``asset key``
on the Warewulf server (e.g., via ``wwctl node set --assetkey "..."``), the
Warewulf server will only respond to requests with a matching asset tag.
* If the Warewulf server is configured with ``warewulf:secure: true``, then it
will only provide the runtime overlay to a ``wwclient`` communicating from a
privileged (< 1024) TCP port. This prevents unprivileged cluster users from
being able to retrieve the runtime overlay.
* When the nodes are booted via `shim` and `grub` Secure Boot can be enabled.
This means that the nodes only boot the kernel which is provided by the
distributor and also custom complied modules can't be loaded.
SELinux
=======
The Warewulf server can be run with SELinux enabled in "targeted" and
"enforcing" mode.
For more information about running SELinux-enabled cluster node images, see
:ref:`SELinux-Enabled Images <selinux_images>`.
firewalld
=========
If the Warewulf server is running ``firewalld``, the following services must be
added for them to function:
.. code-block:: console
firewall-cmd --permanent --add-service=warewulf
firewall-cmd --permanent --add-service=dhcp
firewall-cmd --permanent --add-service=nfs
firewall-cmd --permanent --add-service=tftp
firewall-cmd --reload
.. note::
The DHCP, TFTP, and NFS services may be managed manually, apart from the
Warewulf server. In that case, they may be omitted from the ``firewalld``
configuration on the Warewulf server; but they must be accessible from where
they are served.
nftables
========
If the Warewulf server is running ``nftables`` directly, without ``firewalld``,
ensure that TCP port ``9873`` must be permitted for cluster nodes to communicate
with the Warewulf server.
.. code-block:: console
nft add rule inet filter input tcp dport 9873 accept
nft list ruleset >/etc/nftables.conf
systemctl restart nftables

22
userdocs/server/upgrade.rst Normal file
View File

@@ -0,0 +1,22 @@
==================
Upgrading Warewulf
==================
New versions of Warewulf might introduce changes to ``warewulf.conf`` and
``nodes.conf``. The ``wwctl upgrade`` command can help ease the transition
between versions.
.. note::
``wwctl upgrade`` will back up any files before it changes them (to
``<name>-old``) but it is good practice to back up your configuration
manually.
.. code-block:: console
# wwctl upgrade config
# wwctl upgrade nodes --add-defaults --replace-overlays
Both upgrade commands support specifying ``--output-path=-`` to print the
upgraded configuration file to standard out for inspection before replacing the
configuration files.

58
userdocs/server/wwctl.rst Normal file
View File

@@ -0,0 +1,58 @@
====================
Controlling Warewulf
====================
Warewulf's command-line interface is based primarily around the ``wwctl``
command. This command has sub-commands for each major component of Warewulf's
functionality.
* ``configure``: configures the Warewulf server and its external services
* ``node``: manages nodes in the cluster
* ``profiles``: defines common sets of node configuration which can be applied
to multiple nodes
* ``image``: configures (node) images
* ``overlays``: manages overlays
``wwctl`` also provides additional helpers for interacting with cluster nodes
over SSH and IPMI.
* ``power``: turns nodes on and off
* ``ssh``: provides basic parallel ssh functionality
All of these subcommands (and their respective sub-subcommands) have
built-in help with either ``wwctl help`` or ``--help``.
Hostlists
=========
Many of the commands (e.g., ``wwctl node list`` support a "hostlist"
syntax for referring to multiple nodes at once. Hostlist expressions
support both ranges and comma-separated numerical lists.
For example:
* ``node[1-2]`` expands to ``node1 node2``
* ``node[1,3]`` expands to ``node1 node3``
* ``node[1,5-6]`` expands to ``node1 node5 node6``
Node status
===========
During the whole provisioning process of your nodes, you can check their status
through the following command :
.. code-block:: console
# wwctl node status
NODENAME STAGE SENT LASTSEEN (s)
================================================================================
n1 RUNTIME_OVERLAY __RUNTIME__.img.gz 16
For each node, there are 4 different stages:
* **IPXE**
* **KERNEL**
* **SYSTEM_OVERLAY**
* **RUNTIME_OVERLAY**
You can use the ``wwctl node status`` to check communication between the
Warewulf server (``warewulfd``) and the Warewulf client (``wwclient``).