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

Reflow all userdocs text

Browse Source 
Signed-off-by: Jonathon Anderson <janderson@ciq.co>
This commit is contained in:
Jonathon Anderson
2023-02-22 00:02:08 -07:00
parent 3d7438bc6c
commit ef31b3ddb8
24 changed files with 1005 additions and 362 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
userdocs/contents/background.rst
View File

@@ -2,17 +2,37 @@
Background
==========
Warewulf is based on the design of the original Beowulf Cluster design (and thus the name, soft\ **WARE** implementation of the beo\ **WULF**)
Warewulf is based on the design of the original Beowulf Cluster design
(and thus the name, soft\ **WARE** implementation of the beo\
**WULF**)
The `Beowulf Cluster <https://en.wikipedia.org/wiki/Beowulf_cluster>`_ design was developed in 1996 by Dr. Thomas Sterling and Dr. Donald Becker at NASA. The architecture is defined as a group of similar compute worker nodes all connected together using standard commodity equipment on a private network segment. The control node (historically referred to as the "master" or "head" node) is dual homed (has two network interface cards) with one of these network interface cards attached to the upstream public network and the other connected to a private network which connects to all of the compute worker nodes (as seen in the figure below).
The `Beowulf Cluster <https://en.wikipedia.org/wiki/Beowulf_cluster>`_
design was developed in 1996 by Dr. Thomas Sterling and Dr. Donald
Becker at NASA. The architecture is defined as a group of similar
compute worker nodes all connected together using standard commodity
equipment on a private network segment. The control node (historically
referred to as the "master" or "head" node) is dual homed (has two
network interface cards) with one of these network interface cards
attached to the upstream public network and the other connected to a
private network which connects to all of the compute worker nodes (as
seen in the figure below).
.. image:: beowulf_architecture.png
:alt: Beowulf architecture
This simple topology is the foundation for creating every scalable HPC cluster resource. Even today, almost 30 years after the inception of this architecture, this is the baseline architecture that traditional HPC systems are built to.
This simple topology is the foundation for creating every scalable HPC
cluster resource. Even today, almost 30 years after the inception of
this architecture, this is the baseline architecture that traditional
HPC systems are built to.
Other considerations for a working HPC-type cluster are storage, scheduling and resource management, monitoring, interactive systems, etc. For smaller systems, much of these requirements can be managed all from a single control node, but as the system scales, it may need to have groups of nodes dedicated to these different services.
Other considerations for a working HPC-type cluster are storage,
scheduling and resource management, monitoring, interactive systems,
etc. For smaller systems, much of these requirements can be managed
all from a single control node, but as the system scales, it may need
to have groups of nodes dedicated to these different services.
Warewulf is easily capable of building simple and turnkey HPC clusters, to giant massive complex multi-purpose computing clusters, through next generation computing platforms.
Warewulf is easily capable of building simple and turnkey HPC
clusters, to giant massive complex multi-purpose computing clusters,
through next generation computing platforms.
Anytime a cluster of systems is needed, Warewulf is your tool!
Anytime a cluster of systems is needed, Warewulf is your tool!

49
userdocs/contents/configuration.rst
View File

@@ -50,12 +50,13 @@ Generally you can leave this file as is, as long as you set the
appropriate networking information. Specifically the following
configurations:
* ``ipaddr``: This is the control node's networking interface connecting
to the cluster's **PRIVATE** network. This configuration must match
the host's network IP address for the cluster's private interface.
* ``ipaddr``: This is the control node's networking interface
connecting to the cluster's **PRIVATE** network. This configuration
must match the host's network IP address for the cluster's private
interface.
* ``netmask``: Similar to the ``ipaddr``, this is the subnet mask for the
cluster's **PRIVATE** network and it must also match the host's
* ``netmask``: Similar to the ``ipaddr``, this is the subnet mask for
the cluster's **PRIVATE** network and it must also match the host's
subnet mask for the cluster's private interface.
* ``dhcp:range start`` and ``dhcp:range end``: This address range must
@@ -64,9 +65,9 @@ configurations:
you want DHCP to use.
.. note::
The network configuration listed above assumes the network
layout in the [Background](background.md) portion of the
documentation.
The network configuration listed above assumes the network layout
in the [Background](background.md) portion of the documentation.
The other configuration options are usually not touched, but they are
explained as follows:
@@ -74,34 +75,35 @@ explained as follows:
* ``*:enabled``: This disables Warewulf's control of an external
service. This is useful if you want to manage that service directly.
* ``*:systemd name``: This is so Warewulf can control some of the host's
services. For the distributions that we've built and tested this on,
these will require no changes.
* ``*:systemd name``: This is so Warewulf can control some of the
host's services. For the distributions that we've built and tested
this on, these will require no changes.
* ``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: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
* ``warewulf:secure``: When ``true``, this limits the Warewulf server
to only respond to runtime overlay requests originating from a
privileged report port. This makes it so that only the ``root`` user
on a compute node can request the runtime overlay. While generally
there is nothing super "secure" in these overlays, this adds the
necessary protection that the user's can not obtain this
information.
* ``warewulf:update interval``: This defines the frequency (in seconds)
with which the Warewulf client on the compute node fetches overlay
updates.
* ``warewulf:update interval``: This defines the frequency (in
seconds) with which the Warewulf client on the compute node fetches
overlay updates.
* ``warewulf:autobuild overlays``: This determines whether per-node
overlays will automatically be rebuilt, e.g., when an underlying
overlay is changed.
* ``warewulf:host overlay``: This determines whether the special ``host``
overlay is applied to the Warewulf server during configuration. (The
host overlay is used to configure the dependent services.)
* ``warewulf:host overlay``: This determines whether the special
``host`` overlay is applied to the Warewulf server during
configuration. (The host overlay is used to configure the dependent
services.)
* ``warewulf:syslog``: This determines whether Warewulf server logs go
to syslog or are written directly to a log file. (e.g.,
@@ -125,6 +127,7 @@ format of this file as it is recommended to edit with the ``wwctl``
command.
.. note::
This configuration is not written at install time, but the
first time you attempt to run ``wwctl``, this file will be generated
if it does not exist already.

133
userdocs/contents/containers.rst
View File

@@ -2,23 +2,47 @@
Container Management
====================
Since the inception of Warewulf over 20 years ago, Warewulf has used the model of the "Virtual Node File System" (VNFS) as a template image for the compute nodes. This is similar to a golden master image, except that the node file system exists within a directory on the Warewulf control node (e.g. a `chroot()`).
Since the inception of Warewulf over 20 years ago, Warewulf has used
the model of the "Virtual Node File System" (VNFS) as a template image
for the compute nodes. This is similar to a golden master image,
except that the node file system exists within a directory on the
Warewulf control node (e.g. a `chroot()`).
In hindsight, we've been using containers all along, but the buzzword just didn't exist. Over the last 5-6 years, the enterprise has created a lot of tooling and standards around defining, building, distributing, securing, and managing containers, so Warewulf (as of v4.0) now integrates directly within the container ecosystem to facilitate the process of VNFS image management.
In hindsight, we've been using containers all along, but the buzzword
just didn't exist. Over the last 5-6 years, the enterprise has created
a lot of tooling and standards around defining, building,
distributing, securing, and managing containers, so Warewulf (as of
v4.0) now integrates directly within the container ecosystem to
facilitate the process of VNFS image management.
If you are not currently leveraging the container ecosystem in any other way, you can still build your own chroot directories and use Warewulf as you always have.
If you are not currently leveraging the container ecosystem in any
other way, you can still build your own chroot directories and use
Warewulf as you always have.
It is important to understand that Warewulf is not running a container runtime on the nodes. While that is absolutely possible to run containers from the booted hosts, Warewulf is provisioning the container image to the bare metal and booting it. This container will be used as the base operating system and by default it will run stateless in memory. This means when you reboot the node, the node persists no information about Warewulf or how it booted.
It is important to understand that Warewulf is not running a container
runtime on the nodes. While that is absolutely possible to run
containers from the booted hosts, Warewulf is provisioning the
container image to the bare metal and booting it. This container will
be used as the base operating system and by default it will run
stateless in memory. This means when you reboot the node, the node
persists no information about Warewulf or how it booted.
Container Tools
===============
There are different container managment tools available. Docker is probably the most recognizable one in the enterprise. Podman is another one that is gaining traction on the RHEL platforms. In HPC, Apptainer is the most utilized container management tool. You can use any of these to create and manage the containers to be later imported into Warewulf.
There are different container managment tools available. Docker is
probably the most recognizable one in the enterprise. Podman is
another one that is gaining traction on the RHEL platforms. In HPC,
Apptainer is the most utilized container management tool. You can use
any of these to create and manage the containers to be later imported
into Warewulf.
Importing From A Registry
=========================
Warewulf supports importing an image from any OCI compliant registry. This means you can import from a public registry or from a private registry.
Warewulf supports importing an image from any OCI compliant
registry. This means you can import from a public registry or from a
private registry.
Here is an example of importing from Docker Hub.
@@ -35,17 +59,29 @@ Here is an example of importing from Docker Hub.
Building container: rocky-8
.. note::
Most containers in Docker Hub are not "bootable", in that, they have a limited version of Systemd to make them lighter weight for container purposes. For this reason, don't expect any base Docker container (e.g. ``docker://rockylinux`` or ``docker://debian``) to boot properly. They will not, as they will get stuck into a single user mode. The containers in `https://hub.docker.com/u/warewulf <https://hub.docker.com/u/warewulf>`_ are not limited and thus they boot as you would expect.
Most containers in Docker Hub are not "bootable", in that, they
have a limited version of Systemd to make them lighter weight for
container purposes. For this reason, don't expect any base Docker
container (e.g. ``docker://rockylinux`` or ``docker://debian``) to
boot properly. They will not, as they will get stuck into a single
user mode. The containers in `https://hub.docker.com/u/warewulf
<https://hub.docker.com/u/warewulf>`_ are not limited and thus
they boot as you would expect.
Private Registry
----------------
It is possible to use a private registry that is password protected or does not have the requirement for TLS. In order to do so, you have two choices for handling the credentials.
It is possible to use a private registry that is password protected or
does not have the requirement for TLS. In order to do so, you have two
choices for handling the credentials.
* Set environmental variables
* Use ``docker login`` or ``podman login`` which will store the credentials locally
* Use ``docker login`` or ``podman login`` which will store the
credentials locally
Please note, there is no requirement to install and use docker or podman on your control node just for importing images into Warewulf.
Please note, there is no requirement to install and use docker or
podman on your control node just for importing images into Warewulf.
Here are the environmental variables that can be used.
@@ -63,21 +99,31 @@ Here is an example:
export WAREWULF_OCI_PASSWORD=super-secret-password-or-token
sudo -E wwctl import docker://ghcr.io/privatereg/rocky:8
The above is just an example. Consideration should be done before doing it this way if you are in a security sensitive environment or shared environments. You would not want these showing up in bash history or logs.
The above is just an example. Consideration should be done before
doing it this way if you are in a security sensitive environment or
shared environments. You would not want these showing up in bash
history or logs.
Syncuser
--------
At import time Warewulf checks if the names of the users on the host match the users and UIDs/GIDs in the imported container. If there is mismatch, the import command will print out a warning.
By setting the ``--syncuser`` flag you advise Warewulf to try to syncronize the users from the host to the container, which means that ``/etc/passwd`` and ``/etc/group`` of the imported container are updated and all the files belonning to these UIDs and GIDs will also be updated.
At import time Warewulf checks if the names of the users on the host
match the users and UIDs/GIDs in the imported container. If there is
mismatch, the import command will print out a warning. By setting the
``--syncuser`` flag you advise Warewulf to try to syncronize the users
from the host to the container, which means that ``/etc/passwd`` and
``/etc/group`` of the imported container are updated and all the files
belonning to these UIDs and GIDs will also be updated.
A check if the users of the host and container matches can be triggered with the ``syncuser`` command.
A check if the users of the host and container matches can be
triggered with the ``syncuser`` command.
.. code-block:: bash
wwctl container syncuser container-name
With the ``--write`` flag it will update the container to match the user database of the host as described above.
With the ``--write`` flag it will update the container to match the
user database of the host as described above.
.. code-block:: bash
@@ -86,7 +132,8 @@ With the ``--write`` flag it will update the container to match the user databas
Listing All Imported Containers
===============================
Once the container has been imported, you can list them all with the following command:
Once the container has been imported, you can list them all with the
following command:
.. code-block:: bash
@@ -94,12 +141,15 @@ Once the container has been imported, you can list them all with the following c
CONTAINER NAME BUILT NODES
rocky-8 true 0
Once a container has been imported and showing up in this list you can configure it to boot compute nodes.
Once a container has been imported and showing up in this list you can
configure it to boot compute nodes.
Making Changes To Containers
============================
Warewulf has a minimal container runtime built into it. This means you can run commands inside of any of the containers and make changes to them as follows:
Warewulf has a minimal container runtime built into it. This means you
can run commands inside of any of the containers and make changes to
them as follows:
.. code-block:: bash
@@ -110,7 +160,8 @@ Warewulf has a minimal container runtime built into it. This means you can run c
Rebuilding container...
[INFO] Skipping (VNFS is current)
You can also ``--bind`` directories from your host into the container when using the exec command. This works as follows:
You can also ``--bind`` directories from your host into the container
when using the exec command. This works as follows:
.. code-block:: bash
@@ -118,23 +169,35 @@ You can also ``--bind`` directories from your host into the container when using
[rocky-8] Warewulf>
.. note::
As with any mount command, both the source and the target must exist. This is why the example uses the ``/mnt/`` directory location, as it is almost always present and empty in every Linux distribution (as prescribed by the LSB file hierarchy standard).
When the command completes, if anything within the container changed, the container will be rebuilt into a bootable static object automatically.
As with any mount command, both the source and the target must
exist. This is why the example uses the ``/mnt/`` directory
location, as it is almost always present and empty in every Linux
distribution (as prescribed by the LSB file hierarchy standard).
If the files ``/etc/passwd`` or ``/etc/group`` were updated, there will be an additional check to confirm if the users are in sync as described in `Syncuser`_ section.
When the command completes, if anything within the container changed,
the container will be rebuilt into a bootable static object
automatically.
If the files ``/etc/passwd`` or ``/etc/group`` were updated, there
will be an additional check to confirm if the users are in sync as
described in `Syncuser`_ section.
Creating Containers From Scratch
================================
You can also create containers from scratch and import those containers into Warewulf as previous versions of Warewulf did.
You can also create containers from scratch and import those
containers into Warewulf as previous versions of Warewulf did.
Building A Container From Your Host
-----------------------------------
RPM based distributions, as well as Debian variants can all bootstrap mini ``chroot()`` directories which can then be used to bootstrap your node's container.
RPM based distributions, as well as Debian variants can all bootstrap
mini ``chroot()`` directories which can then be used to bootstrap your
node's container.
For example, on an RPM based Linux distribution with YUM or DNF, you can do something like the following:
For example, on an RPM based Linux distribution with YUM or DNF, you
can do something like the following:
.. code-block:: bash
@@ -154,7 +217,8 @@ You can do something similar with Debian-based distributions:
sudo apt-get install debootstrap
sudo debootstrap stable /tmp/newroot http://ftp.us.debian.org/debian
Once you have created and modified your new ``chroot()``, you can import it into Warewulf with the following command:
Once you have created and modified your new ``chroot()``, you can
import it into Warewulf with the following command:
.. code-block:: bash
@@ -163,9 +227,17 @@ Once you have created and modified your new ``chroot()``, you can import it into
Building A Container Using Apptainer
--------------------------------------
Apptainer, a container platform for HPC and performance intensive applications, can also be used to create node containers for Warewulf. There are several Apptainer container recipes in the ``containers/Apptainer/`` directory and can be found on GitHub at `https://github.com/hpcng/warewulf/tree/main/containers/Apptainer <https://github.com/hpcng/warewulf/tree/main/containers/Apptainer>`_.
Apptainer, a container platform for HPC and performance intensive
applications, can also be used to create node containers for
Warewulf. There are several Apptainer container recipes in the
``containers/Apptainer/`` directory and can be found on GitHub at
`https://github.com/hpcng/warewulf/tree/main/containers/Apptainer
<https://github.com/hpcng/warewulf/tree/main/containers/Apptainer>`_.
You can use these as starting points and adding any additional steps you want in the ``%post`` section of the recipe file. Once you've done that, installing Apptainer, building a container sandbox and importing into Warewulf can be done with the following steps:
You can use these as starting points and adding any additional steps
you want in the ``%post`` section of the recipe file. Once you've done
that, installing Apptainer, building a container sandbox and importing
into Warewulf can be done with the following steps:
.. code-block:: bash
@@ -177,7 +249,10 @@ You can use these as starting points and adding any additional steps you want in
Building A Container Using Podman
--------------------------------------
You can also build a container using podman via a `Dockerfile`. For this step the container must be exported to a tar archive, which then can be imported to Warewulf. The following steps will create an openSUSE Leap container and import it to Warewulf:
You can also build a container using podman via a `Dockerfile`. For
this step the container must be exported to a tar archive, which then
can be imported to Warewulf. The following steps will create an
openSUSE Leap container and import it to Warewulf:
.. code-block:: bash

48
userdocs/contents/initialization.rst
View File

@@ -5,41 +5,65 @@ Warewulf Initialization
System Services
===============
Once Warewulf has been installed and configured, it is ready to be initialized and have the associated system services started. To do this, start by configuring the system services that Warewulf depends on for operation. To do that, run the following command:
Once Warewulf has been installed and configured, it is ready to be
initialized and have the associated system services started. To do
this, start by configuring the system services that Warewulf depends
on for operation. To do that, run the following command:
.. code-block:: bash
sudo wwctl configure --all
This command will configure the system for Warewulf to run properly. Here are the things it will do:
This command will configure the system for Warewulf to run
properly. Here are the things it will do:
* **dhcp**: (re)Write the DHCP configuration and restart the service from the **host** template under ``/etc/dhcpd.conf.ww`` and enable the system service.
* **hostfile**: Update the system's /etc/hosts file based on the **host** template ``/etc/hosts.ww``.
* **nfs**: Configure the NFS server on the control node as well as the ``/etc/fstab`` in the system overlay based on the configuration in ``/etc/warewulf/warewulf.conf`` and enable the system service. Also the file `/etc/exports.ww` from the **host** template is installed.
* **ssh**: Create the appropriate host keys (stored in ``/etc/warewulf/keys/``) and user keys for passwordless ``ssh`` into the nodes. Addionally the shell profiles ``/etc/profile.d/ssh_setup.csh`` and ``/etc/profile.d/ssh_setup.sh`` are installed.
* **tftp**: Write the appropriate binary PXE/iPXE blobs to the TFTP root directory and enable the system service.
* **dhcp**: (re)Write the DHCP configuration and restart the service
from the **host** template under ``/etc/dhcpd.conf.ww`` and enable
the system service.
* **hostfile**: Update the system's /etc/hosts file based on the
**host** template ``/etc/hosts.ww``.
* **nfs**: Configure the NFS server on the control node as well as the
``/etc/fstab`` in the system overlay based on the configuration in
``/etc/warewulf/warewulf.conf`` and enable the system service. Also
the file `/etc/exports.ww` from the **host** template is installed.
* **ssh**: Create the appropriate host keys (stored in
``/etc/warewulf/keys/``) and user keys for passwordless ``ssh`` into
the nodes. Addionally the shell profiles
``/etc/profile.d/ssh_setup.csh`` and ``/etc/profile.d/ssh_setup.sh``
are installed.
* **tftp**: Write the appropriate binary PXE/iPXE blobs to the TFTP
root directory and enable the system service.
This command will quickly setup the system services per the Warewulf configuration. Watch this output carefully for errors and resolve them in the configuration portion of this manual.
This command will quickly setup the system services per the Warewulf
configuration. Watch this output carefully for errors and resolve them
in the configuration portion of this manual.
Warewulf Service
================
The Warewulf installation attempts to register the Warewulf service with Systemd, so it should be as easy to start/stop/check as any other Systemd service:
The Warewulf installation attempts to register the Warewulf service
with Systemd, so it should be as easy to start/stop/check as any other
Systemd service:
.. code-block:: bash
sudo systemctl enable --now warewulfd
You can also check and control the Warewulf service using the `wwctl` command line program as follows:
You can also check and control the Warewulf service using the `wwctl`
command line program as follows:
.. code-block:: bash
sudo wwctl server status
.. note::
If the Warewulf service is running via Systemd, restarting stopping, and starting it from the ``wwctl`` command may result in unexpected results.
If the Warewulf service is running via Systemd, restarting
stopping, and starting it from the ``wwctl`` command may result in
unexpected results.
Logs
----
The Warewulf server logs are by default written to ``/var/log/warewulfd.log``.
The Warewulf server logs are by default written to
``/var/log/warewulfd.log``.

19
userdocs/contents/installation.rst
View File

@@ -54,7 +54,17 @@ Select the version you wish to install and download the tarball to any location
Git
---
Warewulf is developed in "Git", a source code management platform that allows collaborative development and revision control. From the Git repository, you can download different versions of the project either from tags or branches. By default, when you go to the GitHub page, you will find the default branch entitled ``main``. The ``main`` branch is where most of the 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.
Warewulf is developed in "Git", a source code management platform that
allows collaborative development and revision control. From the Git
repository, you can download different versions of the project either
from tags or branches. By default, when you go to the GitHub page, you
will find the default branch entitled ``main``. The ``main`` branch is
where most of the 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
@@ -68,7 +78,9 @@ Warewulf is developed in "Git", a source code management platform that allows co
Runtime Dependencies
--------------------
In Warewulf's default configuration, it will require some operating system provided services. Generally these are provided by your installation vendor and can be installed over the network.
In Warewulf's default configuration, it will require some operating
system provided services. Generally these are provided by your
installation vendor and can be installed over the network.
These are the services you will need to install:
@@ -76,4 +88,5 @@ These are the services you will need to install:
* ``tftp-server``
* ``nfs-utils``
If you are using an Enterprise Linux compatible distribution you can install them with: ``yum install dhcp-server tftp-server nfs-utils``
If you are using an Enterprise Linux compatible distribution you can
install them with ``yum install dhcp-server tftp-server nfs-utils``.

63
userdocs/contents/introduction.rst
View File

@@ -5,32 +5,71 @@ Introduction
The Warewulf Vision
===================
Warewulf has had a number of iterations over the last 20 years, but its design tenets have always remained the same: a simple, scalable, stateless (however some versions were able to provision stateful), and very flexible operating system provisioning system for all types of clusters. This is an overview of how Warewulf works.
Warewulf has had a number of iterations over the last 20 years, but
its design tenets have always remained the same: a simple, scalable,
stateless (however some versions were able to provision stateful), and
very flexible operating system provisioning system for all types of
clusters. This is an overview of how Warewulf works.
About Warewulf
==============
Warewulf is an operating system provisioning platform for Linux that is designed to produce secure, scalable, turnkey cluster deployments that maintain flexibility and simplicity.
Warewulf is an operating system provisioning platform for Linux that
is designed to produce secure, scalable, turnkey cluster deployments
that maintain flexibility and simplicity.
Since its initial release in 2001, Warewulf has become the most popular open source and vendor-agnostic provisioning system within the global HPC community. Warewulf is known for its massive scalability and simple management of stateless (disk optional) provisioning.
Since its initial release in 2001, Warewulf has become the most
popular open source and vendor-agnostic provisioning system within the
global HPC community. Warewulf is known for its massive scalability
and simple management of stateless (disk optional) provisioning.
Warewulf leverages a simple administrative model centralizing administration around virtual node images which are used to provision out to the cluster nodes. This means you can have hundreds or thousands of cluster nodes all booting and running on the same, identical virtual node file system image. As of Warewulf v4, the virtual node image is a standard container image which means all compute resources within a cluster can be managed using any existing container tooling and/or CI pipelines that are being used. This can be as simple as DockerHub or your own private GitLab CI infrastructure.
Warewulf leverages a simple administrative model centralizing
administration around virtual node images which are used to provision
out to the cluster nodes. This means you can have hundreds or
thousands of cluster nodes all booting and running on the same,
identical virtual node file system image. As of Warewulf v4, the
virtual node image is a standard container image which means all
compute resources within a cluster can be managed using any existing
container tooling and/or CI pipelines that are being used. This can be
as simple as DockerHub or your own private GitLab CI infrastructure.
With this architecture, Warewulf combines the best of High Performance Computing (HPC), Cloud, Hyperscale, and Enterprise deployment principals to create and maintain large scalable stateless clusters.
With this architecture, Warewulf combines the best of High Performance
Computing (HPC), Cloud, Hyperscale, and Enterprise deployment
principals to create and maintain large scalable stateless clusters.
While Warewulf's roots are in HPC, it has been used for many different types of tasks and use cases. Everything from clustered web servers, to rendering farms, and even Kubernetes and cloud deployments, Warewulf brings benefit in experience of general operating system management at scale.
While Warewulf's roots are in HPC, it has been used for many different
types of tasks and use cases. Everything from clustered web servers,
to rendering farms, and even Kubernetes and cloud deployments,
Warewulf brings benefit in experience of general operating system
management at scale.
Features
========
* **Lightweight**: Warewulf provisions stateless operating system images and then gets out of the way. There should be no underlying system dependencies or changes to the provisioned cluster node operating systems.
* **Lightweight**: Warewulf provisions stateless operating system
images and then gets out of the way. There should be no underlying
system dependencies or changes to the provisioned cluster node
operating systems.
* **Simple**: Warewulf is used by hobbyists, researchers, scientists, engineers and systems administrators because it is easy, lightweight, and simple.
* **Simple**: Warewulf is used by hobbyists, researchers, scientists,
engineers and systems administrators because it is easy,
lightweight, and simple.
* **Flexible**: Warewulf is highly flexible and can address the needs of any environment-- from a computer lab with graphical workstations, to under-the-desk clusters, to massive supercomputing centers providing traditional HPC capabilities to thousands of users.
* **Flexible**: Warewulf is highly flexible and can address the needs
of any environment-- from a computer lab with graphical
workstations, to under-the-desk clusters, to massive supercomputing
centers providing traditional HPC capabilities to thousands of
users.
* **Agnostic**: From the Linux distribution of choice to the underlying hardware, Warewulf is agnostic and standards compliant. From ARM to x86, Atos to Dell, Debian, SuSE, Rocky, CentOS, and RHEL, Warewulf can do it all.
* **Agnostic**: From the Linux distribution of choice to the
underlying hardware, Warewulf is agnostic and standards
compliant. From ARM to x86, Atos to Dell, Debian, SuSE, Rocky,
CentOS, and RHEL, Warewulf can do it all.
* **Secure**: Warewulf is the only stateless provisioning system that will support SELinux out of the box. Just enable your node operating system container to support SELinux, and Warewulf do the rest!
* **Secure**: Warewulf is the only stateless provisioning system that
will support SELinux out of the box. Just enable your node operating
system container to support SELinux, and Warewulf do the rest!
* **Open Source**: For the last 20 years, Warewulf has remained open source and continues to be the golden standard for cluster provisioning.
* **Open Source**: For the last 20 years, Warewulf has remained open
source and continues to be the golden standard for cluster
provisioning.

42
userdocs/contents/ipmi.rst
View File

@@ -2,18 +2,28 @@
IPMI
====
It is possible to control the power or connect a console to your nodes being managed by Warewulf by connecting to the BMC through the use of IPMI. We will discuss how to set this up below.
It is possible to control the power or connect a console to your nodes
being managed by Warewulf by connecting to the BMC through the use of
IPMI. We will discuss how to set this up below.
IPMI Settings
=============
The common settings for the IPMI interfaces on all nodes can be set on a Profile level. The only field that would need to be assigned to each individual node would be the IP address.
The common settings for the IPMI interfaces on all nodes can be set on
a Profile level. The only field that would need to be assigned to
each individual node would be the IP address.
The settings are only written to the IPMI interface if ``--ipmiwrite`` is set to `true`. The write process happens at every boot of the node through the script ``/warewulf/init.d/50-ipmi`` in the **system** overlay.
The settings are only written to the IPMI interface if ``--ipmiwrite``
is set to `true`. The write process happens at every boot of the node
through the script ``/warewulf/init.d/50-ipmi`` in the **system**
overlay.
If an individual node has different settings, you can set the IPMI settings for that specific node, overriding the default settings.
If an individual node has different settings, you can set the IPMI
settings for that specific node, overriding the default settings.
Here is a table outlining the fields on a Profile and Node which is the same as the parameter that can be used when running `wwctl profile set` or `wwctl node set`.
Here is a table outlining the fields on a Profile and Node which is
the same as the parameter that can be used when running `wwctl profile
set` or `wwctl node set`.
+----------------+---------+------+--------------------+---------------+
| Parameter | Profile | Node | Valid Values | Default Value |
@@ -39,7 +49,8 @@ Here is a table outlining the fields on a Profile and Node which is the same as
Reviewing Settings
==================
There are multiple ways to review the IPMI settings. They can be reviewed from a Profile level, all the way down to a specific Node.
There are multiple ways to review the IPMI settings. They can be
reviewed from a Profile level, all the way down to a specific Node.
Profile View
------------
@@ -75,6 +86,7 @@ Profile View
Node View
---------
.. code-block:: bash
$ sudo wwctl node list -a n001
@@ -116,23 +128,26 @@ Node View
Review Only IPMI Settings
-------------------------
The above views show you everything that is set on a Profile or Node level. That is a lot of detail. If you want to view key IPMI connecton details for a node or all nodes, you can do the following.
The above views show you everything that is set on a Profile or Node
level. That is a lot of detail. If you want to view key IPMI connecton
details for a node or all nodes, you can do the following.
.. code-block:: bash
$ sudo wwctl node list -i
NODE NAME IPMI IPADDR IPMI PORT IPMI USERNAME IPMI INTERFACE
==================================================================================================
n001 192.168.1.11 -- hwadmin --
n002 192.168.1.12 -- hwadmin --
n003 192.168.1.13 -- hwadmin --
n004 192.168.1.14 -- hwadmin --
n001 192.168.1.11 -- hwadmin --
n002 192.168.1.12 -- hwadmin --
n003 192.168.1.13 -- hwadmin --
n004 192.168.1.14 -- hwadmin --
Power Commands
==============
The ``power`` command can be used to manage the current power state of your nodes through IPMI.
The ``power`` command can be used to manage the current power state of
your nodes through IPMI.
``wwctl power [command]`` where ``[command]`` is one of:
@@ -157,6 +172,7 @@ status
Console
=======
If your node is setup to use serial over lan (SOL), Warewulf can connect a console to the node.
If your node is setup to use serial over lan (SOL), Warewulf can
connect a console to the node.
``sudo wwctl node console n001``

40
userdocs/contents/kernel.rst
View File

@@ -5,11 +5,16 @@ Kernel Management
Node Kernels
============
Warewulf nodes require a Linux kernel to boot. There are multiple ways to do this, but the default, and easiest way is to install the kernel you wish to use for a particular container, into the container.
Warewulf nodes require a Linux kernel to boot. There are multiple ways
to do this, but the default, and easiest way is to install the kernel
you wish to use for a particular container, into the container.
Warewulf will locate the kernel automatically within the container and by default use that kernel for any node configured to use that container image.
Warewulf will locate the kernel automatically within the container and
by default use that kernel for any node configured to use that
container image.
You can see what kernel is included in a container by using the ``wwctl container list`` command:
You can see what kernel is included in a container by using the
``wwctl container list`` command:
.. code-block:: bash
@@ -19,30 +24,42 @@ You can see what kernel is included in a container by using the ``wwctl containe
rocky 0 4.18.0-348.12.2.el8_5.x86_64
rocky_updated 1 4.18.0-348.23.1.el8_5.x86_64
Here you will notice the alpine contianer that was imported has no kernel within it, and each of the rocky containers include a kernel.
Here you will notice the alpine contianer that was imported has no
kernel within it, and each of the rocky containers include a kernel.
This model was introduced in Warewulf 4.3.0. Previously, Warewulf managed the kernel and the container separately, which made it hard to build and distribute containers that have custom drivers and/or configurations included (e.g. OFED, GPUs, etc.).
This model was introduced in Warewulf 4.3.0. Previously, Warewulf
managed the kernel and the container separately, which made it hard to
build and distribute containers that have custom drivers and/or
configurations included (e.g. OFED, GPUs, etc.).
Kernel Overrides
================
It is still possible to specify a kernel to a container if it doesn't include it's own kernel, or if you wish to override the default kernel by using the ``kernel override`` capability.
It is still possible to specify a kernel to a container if it doesn't
include it's own kernel, or if you wish to override the default kernel
by using the ``kernel override`` capability.
You can specify this option either within the ``nodes.conf`` directly or via the command line with the ``--kerneloverride`` option to ``wwctl node set`` or ``wwctl profile set`` commands.
You can specify this option either within the ``nodes.conf`` directly
or via the command line with the ``--kerneloverride`` option to
``wwctl node set`` or ``wwctl profile set`` commands.
In this case you will also need to import a kernel specifically into Warewulf for this purpose using the ``wwctl kernel import`` command as follows:
In this case you will also need to import a kernel specifically into
Warewulf for this purpose using the ``wwctl kernel import`` command as
follows:
.. code-block:: bash
$ sudo wwctl kernel import $(uname -r)
4.18.0-305.3.1.el8_4.x86_64: Done
This process will import not only the kernel image itself, but also all of the kernel modules and firmware associated to this kernel.
This process will import not only the kernel image itself, but also
all of the kernel modules and firmware associated to this kernel.
Listing All Imported Kernels
----------------------------
Once the kernel has been imported, you can list them all with the following command:
Once the kernel has been imported, you can list them all with the
following command:
.. code-block:: bash
@@ -50,4 +67,5 @@ Once the kernel has been imported, you can list them all with the following comm
VNFS NAME NODES
4.18.0-305.3.1.el8_4.x86_64 0
Once a kernel has been imported and showing up in this list you can configure it to boot compute nodes.
Once a kernel has been imported and showing up in this list you can
configure it to boot compute nodes.

43
userdocs/contents/nodeconfig.rst
View File

@@ -6,9 +6,9 @@ The Node Configuration DB
=========================
As mentioned in the [Configuration](configuration) section, node
configs are persisted to the ``nodes.conf`` YAML file, but generally it
is best not to edit this file directly (however that is supported, it
is just prone to errors).
configs are persisted to the ``nodes.conf`` YAML file, but generally
it is best not to edit this file directly (however that is supported,
it is just prone to errors).
This method of using a YAML configuration file as a backend datastore
is both scalable and very lightweight. We've tested this out to over
@@ -28,8 +28,8 @@ Creating a new node is as simple as running the following command:
Adding several nodes
--------------------
Several nodes can be added with a single command if a node range is given. An
additional IP address will incremented. So the command
Several nodes can be added with a single command if a node range is
given. An additional IP address will incremented. So the command
.. code-block:: bash
@@ -77,8 +77,8 @@ their attributes as follows:
$ sudo wwctl node list
You can also see the node's full attribute list by specifying the ``-a``
option (all):
You can also see the node's full attribute list by specifying the
``-a`` option (all):
.. code-block:: bash
@@ -120,8 +120,9 @@ option (all):
.. note::
The attribute values in parenthesis are default values and can
be overridden in the next section, granted, the default values are
The attribute values in parenthesis are default values and can be
overridden in the next section, granted, the default values are
generally usable.
Setting Node Attributes
@@ -133,9 +134,9 @@ are a kernel and container, and for that node to be useful, we will
also need to configure the network so the nodes are reachable after
they boot.
Node configurations are set using the ``wwctl node set`` command. To see
a list of all configuration attributes, use the command ``wwctl node
set --help``.
Node configurations are set using the ``wwctl node set`` command. To
see a list of all configuration attributes, use the command ``wwctl
node set --help``.
Configuring the Node's Container Image
======================================
@@ -157,20 +158,19 @@ Configuring the Node's Kernel
While the recommended method for assigning a kernel in 4.3 and beyond
is to include it in the container / node image, a kernel can still be
specified as an override at the node or profile.
To illustrate this, we import the most recent kernel from a openSUSE Tumbleweed release
specified as an override at the node or profile. To illustrate this,
we import the most recent kernel from a openSUSE Tumbleweed release
.. code-block:: bash
$ sudo wwctl container import docker://registry.opensuse.org/science/warewulf/tumbleweed/containerfile/kernel:latest tw
$ sudo wwctl kernel import -DC tw
$ sudo wwctl kernel list
KERNEL NAME KERNEL VERSION NODES
KERNEL NAME KERNEL VERSION NODES
tw 6.1.10-1-default 0
$ sudo wwctl node set --kerneloverride tw n001
Are you sure you want to modify 1 nodes(s): y
$ sudo wwctl node list -a n001 | grep kerneloverride
n001 kerneloverride -- tw
@@ -226,11 +226,11 @@ container, kernel, and network:
n001 default:mtu -- --
n001 default:primary -- true
$ sudo wwctl node set --cluster cluster01 n001
Are you sure you want to modify 1 nodes(s): y
$ sudo wwctl node set --cluster cluster01 n001
Are you sure you want to modify 1 nodes(s): y
$ sudo wwctl node list -a n001 | grep cluster
n001 cluster -- cluster01
$ sudo wwctl node list -a n001 | grep cluster
n001 cluster -- cluster01
Un-setting Node Attributes
==========================
@@ -238,7 +238,6 @@ Un-setting Node Attributes
If you wish to ``unset`` a particular value, set the value to
``UNDEF``. For example:
And to unset this configuration attribute:
.. code-block:: bash

143
userdocs/contents/overlays.rst
View File

@@ -2,16 +2,31 @@
Warewulf Overlays
=================
So at this point, we have discussed how Warewulf is designed to scalably provision and manage thousands of cluster nodes by utilizing identical stateless boot images. And there-in lies a problem to solve. If these boot images are completely identical, then how do we configure things like hostnames? IP addresses? Or any other node specific custom configurations?
So at this point, we have discussed how Warewulf is designed to
scalably provision and manage thousands of cluster nodes by utilizing
identical stateless boot images. And there-in lies a problem to
solve. If these boot images are completely identical, then how do we
configure things like hostnames? IP addresses? Or any other node
specific custom configurations?
While some of this can be managed by services like DHCP, and other bits by configuration management, which can absolutely be done with Warewulf and many people choose to do, these are heavy-weight solutions to a simple problem to solve.
While some of this can be managed by services like DHCP, and other
bits by configuration management, which can absolutely be done with
Warewulf and many people choose to do, these are heavy-weight
solutions to a simple problem to solve.
Warewulf solves this with overlays and uses overlays in different ways through the provisioning process. A node or profile can configure an overlay in two different ways:
Warewulf solves this with overlays and uses overlays in different ways
through the provisioning process. A node or profile can configure an
overlay in two different ways:
* An overlay can be configured to run during boot as part of the ``wwinit`` process. These overlays are called **system overlay** or **wwinit overlays**.
* An overlay can be configured to run periodically while the system is running. These overlays are called **runtime overlays** or **generic overlays**.
* An overlay can be configured to run during boot as part of the
``wwinit`` process. These overlays are called **system overlay** or
**wwinit overlays**.
* An overlay can be configured to run periodically while the system is
running. These overlays are called **runtime overlays** or **generic
overlays**.
The default profile has both a **wwinit** and a **runtime** overlay configured.
The default profile has both a **wwinit** and a **runtime** overlay
configured.
Overlays are compiled for each compute node individually.
@@ -20,14 +35,21 @@ Defined Overlays
System or wwinit overlay
------------------------
This overlay contains all the nesscesary scripts to provision a Warewulf node. It is available before the `systemd` or other init is called and contains all configurations which are needed to bring up the compute node. It is not updated during run time. Besides the network configurations for
This overlay contains all the nesscesary scripts to provision a
Warewulf node. It is available before the `systemd` or other init is
called and contains all configurations which are needed to bring up
the compute node. It is not updated during run time. Besides the
network configurations for
* wicked
* NetworkManager
* EL legacy network scripts
it also contains udev rules, which will set the interface name of the first network device to `eth0`.
Before the `systemd` init is called, the overlay loops through the scripts in `/wwinit/warwulf/init.d/*` which will setup
it also contains udev rules, which will set the interface name of the
first network device to `eth0`. Before the `systemd` init is called,
the overlay loops through the scripts in `/wwinit/warwulf/init.d/*`
which will setup
* Ipmi
* wwclient
@@ -36,28 +58,47 @@ Before the `systemd` init is called, the overlay loops through the scripts in `/
Runtime Overlay or generic Overlay
----------------------------------
The runtime overlay is updated by the `wwclient` service on a regular basis (by default, once per minute). In the standard configuration it includes updates for `/etc/passwd`, `/etc/group` and `/etc/hosts`. Additionally the `authorized_keys` file of the root user is updated.
It is recommended to use this overlay for dynamic configuration files like `slurm.conf`.
Once the system is provisioned and booted, the ``wwclient`` program (which is provisioned as part of the ``wwinit`` system overlay) will continuously update the node with updates in the runtime overlay.
The runtime overlay is updated by the `wwclient` service on a regular
basis (by default, once per minute). In the standard configuration it
includes updates for `/etc/passwd`, `/etc/group` and
`/etc/hosts`. Additionally the `authorized_keys` file of the root user
is updated. It is recommended to use this overlay for dynamic
configuration files like `slurm.conf`. Once the system is provisioned
and booted, the ``wwclient`` program (which is provisioned as part of
the ``wwinit`` system overlay) will continuously update the node with
updates in the runtime overlay.
Host Overlay
------------
Configuration files used for the configuration of the Warewulf host / server are stored in the **host** overlay. Unlike other overlays, it *must* have the name `host`. Existing files on the host are copied to backup files with a `wwbackup` suffix at the first run. (Subsequent use of the host overlay won't overwrite existing `wwbackup` files.)
Configuration files used for the configuration of the Warewulf host /
server are stored in the **host** overlay. Unlike other overlays, it
*must* have the name `host`. Existing files on the host are copied to
backup files with a `wwbackup` suffix at the first run. (Subsequent
use of the host overlay won't overwrite existing `wwbackup` files.)
The following services get configuration files via the host overlay:
* ssh keys are created with the scrips `ssh_setup.sh` and `ssh_setup.csh`
* hosts entries are created by manipulating `/etc/hosts` with the template `hosts.ww`
* nfs kernel server receives its exports from the template `exports.ww`
* ssh keys are created with the scrips `ssh_setup.sh` and
`ssh_setup.csh`
* hosts entries are created by manipulating `/etc/hosts` with the
template `hosts.ww`
* nfs kernel server receives its exports from the template
`exports.ww`
* the dhcpd service is configured with `dhcpd.conf.ww`
Combining Overlays
==================
When changing the overlays, it is recommended not to change them, but to add the changed files to a new overlay and combine them in the configuration. This is possible as the configuration fields for the **wwinit** and **runtime** overlays are lists and can contain several overlays.
As an example for this, we will overwrite the `/etc/issue` file from the **wwinit** overlay.
For this we will create a new overlay called welcome and import the file `/etc/issue` from the host to it. This overlay is then combined with the existing **wwinit** overlay.
When changing the overlays, it is recommended not to change them, but
to add the changed files to a new overlay and combine them in the
configuration. This is possible as the configuration fields for the
**wwinit** and **runtime** overlays are lists and can contain several
overlays. As an example for this, we will overwrite the `/etc/issue`
file from the **wwinit** overlay. For this we will create a new
overlay called welcome and import the file `/etc/issue` from the host
to it. This overlay is then combined with the existing **wwinit**
overlay.
..code-block:: bash
$ wwctl overlay create welcome
@@ -72,19 +113,32 @@ For this we will create a new overlay called welcome and import the file `/etc/i
Templates
=========
Templates allow you to create dynamic content such that the files downloaded for each node will be customized for that node. Templates allow you to insert everything from variables, to including files from the control node, as well as conditional content and loops.
Templates allow you to create dynamic content such that the files
downloaded for each node will be customized for that node. Templates
allow you to insert everything from variables, to including files from
the control node, as well as conditional content and loops.
Warewulf uses the ``text/template`` engine to facilitate implementing dynamic content in a simple and standardized manner.
Warewulf uses the ``text/template`` engine to facilitate implementing
dynamic content in a simple and standardized manner.
All template files will end with the suffix of ``.ww``. That tells Warewulf that when building a file, that it should parse that file as a template. When it does that, the resulting file is static and can have node customizations that are obtained from the node configuration attributes.
All template files will end with the suffix of ``.ww``. That tells
Warewulf that when building a file, that it should parse that file as
a template. When it does that, the resulting file is static and can
have node customizations that are obtained from the node configuration
attributes.
.. note::
When the file is persisted within the built overlay, the ``.ww`` will be dropped, so ``/etc/hosts.ww`` will end up being ``/etc/hosts``.
When the file is persisted within the built overlay, the ``.ww``
will be dropped, so ``/etc/hosts.ww`` will end up being
``/etc/hosts``.
Using Overlays
==============
Warewulf includes a command group for manipulating overlays (``wwctl overlay``). With this you can add, edit, remove, change ownership, permissions, etc.
Warewulf includes a command group for manipulating overlays (``wwctl
overlay``). With this you can add, edit, remove, change ownership,
permissions, etc.
..
note::
@@ -97,10 +151,18 @@ Build
wwctl overlay build [-H,--hosts|-N,--nodes|-o,--output directory|-O,--overlay-name] nodepattern
Without any arguments the command will interpret the templates for all overlays for every compute node and also all the templates in the host overlay. For every overlay of the compute nodes a gzip compressed cpio archive is created. The range of the nodes can be restricted as the last argument.
With the `-H` flag only the host overlay is built. With the `-N` flag only compute node overlays are built. Specific overlays can be selected with `-O` flag. For debugging purposes the templates can be written to a directory given via the `-o` flag.
Without any arguments the command will interpret the templates for all
overlays for every compute node and also all the templates in the host
overlay. For every overlay of the compute nodes a gzip compressed cpio
archive is created. The range of the nodes can be restricted as the
last argument. With the `-H` flag only the host overlay is
built. With the `-N` flag only compute node overlays are
built. Specific overlays can be selected with `-O` flag. For debugging
purposes the templates can be written to a directory given via the
`-o` flag.
By default Warewulf will build/update and cache overlays as needed (configurable in the `warewulf.conf`).
By default Warewulf will build/update and cache overlays as needed
(configurable in the `warewulf.conf`).
Chmod
-----
@@ -139,7 +201,10 @@ Delete
wwctl overlay delete [-f,--force] overlay-name [File [File ...]]
Either the given overlay is deleted (must be empty or use the `--force flag`) or the specified file within the overlay is deleted. With the `--parents` flag the directory of the deleted file is also removed if no other file is in the directory.
Either the given overlay is deleted (must be empty or use the `--force
flag`) or the specified file within the overlay is deleted. With the
`--parents` flag the directory of the deleted file is also removed if
no other file is in the directory.
Edit
----
@@ -147,7 +212,10 @@ Edit
wwctl overlay edit [--mode,-m MODE|--parents,p] overlay-name file
Use this command to edit an existing or a new file in the given overlay. If a the new file ends with a `.ww` suffix an example template header is added to the file. With the `--parents` flag necessary parent directories for a new file are created.
Use this command to edit an existing or a new file in the given
overlay. If a the new file ends with a `.ww` suffix an example
template header is added to the file. With the `--parents` flag
necessary parent directories for a new file are created.
Import
------
@@ -155,7 +223,10 @@ Import
wwctl overlay import [--mode,-m|--noupdate,-n] overlay-name file-name [new-file-name]
The given file is imported to the overlay. If no new-file-name is given, the file will be placed in the overlay at the same path as on the host. With the `--noupdate` flag you can block the rebuild of the overlays.
The given file is imported to the overlay. If no new-file-name is
given, the file will be placed in the overlay at the same path as on
the host. With the `--noupdate` flag you can block the rebuild of the
overlays.
List
----
@@ -164,7 +235,11 @@ List
wwctl overlay list [--all,-a|--long,-l] [overlay-name]
With this command all existing overlays and files in them can be listed. Without any option only the overlay names and their number of files are listed. With the `--all` switch also the every file is shown. The `--long` option will also display the permissions, UID, and GID of each file.
With this command all existing overlays and files in them can be
listed. Without any option only the overlay names and their number of
files are listed. With the `--all` switch also the every file is
shown. The `--long` option will also display the permissions, UID, and
GID of each file.
Show
----
@@ -173,4 +248,8 @@ Show
wwctl overlay show [--quiet,-q|--render,-r nodename] overlay-name file
The content of the file for the given overlay is displayed with this command. With the `--render` option a template is rendered as it will be rendered for the given node. The node name is a mandatory argument to the `--render` flag. Additional information for the file can be suppressed with the `--quiet` option.
The content of the file for the given overlay is displayed with this
command. With the `--render` option a template is rendered as it will
be rendered for the given node. The node name is a mandatory argument
to the `--render` flag. Additional information for the file can be
suppressed with the `--quiet` option.

69
userdocs/contents/profiles.rst
View File

@@ -2,14 +2,27 @@
Node Profiles
=============
Profiles provide a way to scalably group node configurations together. Instead of redundant configurations for each node, you can put that into a profile and the nodes will inherit these configurations. This is very handy if you have groups of node specific customizations. For example, a few hundred nodes that are running a particular container or kernel, and another group of nodes that are running a different kernel or container.
Profiles provide a way to scalably group node configurations
together. Instead of redundant configurations for each node, you can
put that into a profile and the nodes will inherit these
configurations. This is very handy if you have groups of node specific
customizations. For example, a few hundred nodes that are running a
particular container or kernel, and another group of nodes that are
running a different kernel or container.
Any node configuration attributes can be applied to a profile, but there are always going to be some node configurations which must be specific to a node, like a network HW/MAC address or an IP address.
Any node configuration attributes can be applied to a profile, but
there are always going to be some node configurations which must be
specific to a node, like a network HW/MAC address or an IP address.
An Introduction To Profiles
===========================
Every new node is automatically added to a profile called ``default``. You can view the configuration attributes of this profile by using the ``wwctl profile list`` command. Like the ``wwctl node list`` command, this will provide a summary, but you can see **all** configuration attributes by using the ``--all`` or ``-a`` flag as follows:
Every new node is automatically added to a profile called
``default``. You can view the configuration attributes of this profile
by using the ``wwctl profile list`` command. Like the ``wwctl node
list`` command, this will provide a summary, but you can see **all**
configuration attributes by using the ``--all`` or ``-a`` flag as
follows:
.. code-block:: bash
@@ -43,7 +56,11 @@ And with the ``-a`` flag:
default IpmiUserName --
default IpmiInterface --
As you can see here, there is only one attribute set by default in this profile, and that is the "Comment" field. That Comment is inherited by any nodes that are configured to use this profile. So if we look at the node we configured in the last section, we can see that configuration attribute there:
As you can see here, there is only one attribute set by default in
this profile, and that is the "Comment" field. That Comment is
inherited by any nodes that are configured to use this profile. So if
we look at the node we configured in the last section, we can see that
configuration attribute there:
.. code-block:: bash
@@ -54,12 +71,17 @@ As you can see here, there is only one attribute set by default in this profile,
n0000 Comment default This profile is automatically included for each node
n0000 Cluster -- --
Here you can see that the "Comment" attribute was inherited by this node, and it also provides you with the information of which profile this attribute was inherited from. This is very useful information as nodes can be part of multiple profiles with inheritance being cascading.
Here you can see that the "Comment" attribute was inherited by this
node, and it also provides you with the information of which profile
this attribute was inherited from. This is very useful information as
nodes can be part of multiple profiles with inheritance being
cascading.
Multiple Profiles
=================
For demonstration purposes, let's create another profile and demonstrate how to use this second profile.
For demonstration purposes, let's create another profile and
demonstrate how to use this second profile.
.. code-block:: bash
@@ -70,7 +92,8 @@ For demonstration purposes, let's create another profile and demonstrate how to
default This profile is automatically included for each node
test_profile --
Now that we've created a new profile, let's create a configuration attribute in this profile:
Now that we've created a new profile, let's create a configuration
attribute in this profile:
.. code-block:: bash
@@ -102,7 +125,8 @@ And you can now verify that the node has both profile configurations:
Cascading Profiles
==================
In the previous example, we set a single node to have two profile configurations. We can also overwrite configurations as follows:
In the previous example, we set a single node to have two profile
configurations. We can also overwrite configurations as follows:
.. code-block:: bash
@@ -117,7 +141,8 @@ In the previous example, we set a single node to have two profile configurations
n0000 Cluster test_profile cluster01
n0000 Profiles -- default,test_profile
And if we delete the superseded profile attribute from ``test_profile`` we can now see the previous configuration:
And if we delete the superseded profile attribute from
``test_profile`` we can now see the previous configuration:
.. code-block:: bash
@@ -132,12 +157,17 @@ And if we delete the superseded profile attribute from ``test_profile`` we can n
n0000 Cluster test_profile cluster01
n0000 Profiles -- default,test_profile
This is a very useful feature for dealing with many groups of cluster nodes and/or testing new configurations on smaller subsets of cluster nodes. For example, you can use this method to run a different kernel on only a subset or group of cluster nodes without changing any other node attributes.
This is a very useful feature for dealing with many groups of cluster
nodes and/or testing new configurations on smaller subsets of cluster
nodes. For example, you can use this method to run a different kernel
on only a subset or group of cluster nodes without changing any other
node attributes.
Overriding Profiles
===================
All profile configurations can be overwritten by a node configuration as can be seen here:
All profile configurations can be overwritten by a node configuration
as can be seen here:
.. code-block:: bash
@@ -155,8 +185,19 @@ All profile configurations can be overwritten by a node configuration as can be
How To Use Profiles Effectively
===============================
There are a lot of ways to use profiles to facilitate the management of large cluster node attributes, but there is nothing inherent in the design of Warewulf that requires use of them for anything. It is completely reasonable to not use profiles at all to help with node configuration attributes.
There are a lot of ways to use profiles to facilitate the management
of large cluster node attributes, but there is nothing inherent in the
design of Warewulf that requires use of them for anything. It is
completely reasonable to not use profiles at all to help with node
configuration attributes.
But if you do wish to use profiles, the best way to use them is to manage "fixed" configurations of groups of cluster nodes. For example, if you have multiple sub-clusters in your cluster, it might be advantageous to have a ``cluster_name`` profile which includes things like network configurations, and/or a specific kernel, container, boot arguments, etc.
But if you do wish to use profiles, the best way to use them is to
manage "fixed" configurations of groups of cluster nodes. For example,
if you have multiple sub-clusters in your cluster, it might be
advantageous to have a ``cluster_name`` profile which includes things
like network configurations, and/or a specific kernel, container, boot
arguments, etc.
Node specific information, like HW/MAC addresses and IP addresses should always be put in a node configuration rather than a profile configuration.
Node specific information, like HW/MAC addresses and IP addresses
should always be put in a node configuration rather than a profile
configuration.

61
userdocs/contents/provisioning.rst
View File

@@ -7,37 +7,66 @@ Once the nodes are configured in Warewulf, they are ready to boot.
Node Hardware Setup
===================
The only thing that Warewulf requires to provision is that the node is set to PXE boot. You may need to change the boot order if there is a local disk present and bootable. This is a configuration change you will have to make in the BIOS of the cluster node.
The only thing that Warewulf requires to provision is that the node is
set to PXE boot. You may need to change the boot order if there is a
local disk present and bootable. This is a configuration change you
will have to make in the BIOS of the cluster node.
Each vendor does this differently and as a result we won't go into the setup specifics here and if you can not find information on how to PXE boot your nodes, please contact your hardware vendor support.
Each vendor does this differently and as a result we won't go into the
setup specifics here and if you can not find information on how to PXE
boot your nodes, please contact your hardware vendor support.
.. note::
If you find that you are going to use Warewulf, or any other cluster provisioning tool, it is very helpful to require that hardware vendors preconfigure your cluster nodes with values of your choosing, and ask them to provide a text file that includes all of the HW/MAC addresses of the compute nodes in the order they are racked (which most creditable vendors will do). You can also ask them to certify their computing stack for the operating system you wish to use and the provisioning system. This helps hardware vendors to ensure their stack works with open source projects like Warewulf, Debian, OpenSuSE, and Rocky Linux.
If you find that you are going to use Warewulf, or any other
cluster provisioning tool, it is very helpful to require that
hardware vendors preconfigure your cluster nodes with values of
your choosing, and ask them to provide a text file that includes
all of the HW/MAC addresses of the compute nodes in the order they
are racked (which most creditable vendors will do). You can also
ask them to certify their computing stack for the operating system
you wish to use and the provisioning system. This helps hardware
vendors to ensure their stack works with open source projects like
Warewulf, Debian, OpenSuSE, and Rocky Linux.
The Provisioning Process
========================
When the cluster node boots, the following order of operations will occur:
When the cluster node boots, the following order of operations will
occur:
#. BIOS:
#. The system BIOS will bootstrap the initialization of the hardware
#. The system BIOS will bootstrap the initialization of the
hardware
#. The network card will register its option ROM into the BIOS
#. The BIOS will run through all of its functions and finish with boot devices
#. The BIOS will run through all of its functions and finish with
boot devices
#. The boot devices are attempted in order
#. When it gets to the network boot device, PXE is run from the firmware on the network card
#. When it gets to the network boot device, PXE is run from the
firmware on the network card
#. PXE:
#. PXE will request a BOOTP/DHCP address on the network
#. The Warewulf controller's DHCP server will respond with a network configuration and filename to try and boot
#. PXE will attempt to download the filename referred to in the DHCP response via TFTP
#. The downloaded file will execute an iPXE stack which will reach out to the Warewulf server for it's configuration
#. The Warewulf controller's DHCP server will respond with a
network configuration and filename to try and boot
#. PXE will attempt to download the filename referred to in the
DHCP response via TFTP
#. The downloaded file will execute an iPXE stack which will reach
out to the Warewulf server for it's configuration
#. Bootstrap:
#. The Warewulf server will generate the iPXE configuration which will include directions of what else is necessary to download and how to boot.
#. The kernel, container image, kernel modules, and system overlay are all downloaded over REST HTTP from the Warewulf Server
#. iPXE executes the kernel and processes the overlays to provide a unified root file system
#. Warewulf bootstraps the initialization of cluster node's operating system
#. The Warewulf server will generate the iPXE configuration which
will include directions of what else is necessary to download
and how to boot.
#. The kernel, container image, kernel modules, and system overlay
are all downloaded over REST HTTP from the Warewulf Server
#. iPXE executes the kernel and processes the overlays to provide
a unified root file system
#. Warewulf bootstraps the initialization of cluster node's
operating system
#. File System (re)configuration
#. SELinux
#. ``wwclient`` is called as a background daemon and sleeps until network is ready
#. ``wwclient`` is called as a background daemon and sleeps
until network is ready
#. The Warewulf bootstrap execs the container's ``/sbin/init``
#. Container:
#. The container now boots exactly as any operating system would expect
#. The container now boots exactly as any operating system would
expect

74
userdocs/contents/security.rst
View File

@@ -2,35 +2,87 @@
Security
========
Historically, most HPC clusters utilize a security model that is "hard on the exterior and soft and gushy on the interior". It is not that a user has free roam once logged in, but rather we tend to rely on just simple POSIX security models on the inside. For example, one of the common practices is to completely disable SELinux on a new cluster setup. Just kill it because it gets in the way.
Historically, most HPC clusters utilize a security model that is "hard
on the exterior and soft and gushy on the interior". It is not that a
user has free roam once logged in, but rather we tend to rely on just
simple POSIX security models on the inside. For example, one of the
common practices is to completely disable SELinux on a new cluster
setup. Just kill it because it gets in the way.
For that reason, most critical HPC clusters leverage VPNs and/or bastion hosts with multi-factor authentication (MFA) to help secure it on the outside. But even with MFA and secure ssh connections through a bastion host, it is still possible for malicious users to gain access to these systems. Security being like layers of an onion is accurate, but on an HPC system, those layers are predominately on the outside of the cluster, not the inside.
For that reason, most critical HPC clusters leverage VPNs and/or
bastion hosts with multi-factor authentication (MFA) to help secure it
on the outside. But even with MFA and secure ssh connections through a
bastion host, it is still possible for malicious users to gain access
to these systems. Security being like layers of an onion is accurate,
but on an HPC system, those layers are predominately on the outside of
the cluster, not the inside.
Warewulf was written and designed from the ground up to go a bit further. And while certain parallelization and high performance library capabilities still require lowering the security threshold, Warewulf strives to not be a blocker here.
Warewulf was written and designed from the ground up to go a bit
further. And while certain parallelization and high performance
library capabilities still require lowering the security threshold,
Warewulf strives to not be a blocker here.
SELinux
=======
The Warewulf server itself was developed with SELinux enabled in "targeted" and "enforcing" mode and with the firewall active.
The Warewulf server itself was developed with SELinux enabled in
"targeted" and "enforcing" mode and with the firewall active.
Additionally, the provisioning process fully supports SELinux by default. In previous versions you had to enable a switch to support SELinux, but in Warewulf v4 and above, it is always enabled, but you do have to make some configuration changes.
Additionally, the provisioning process fully supports SELinux by
default. In previous versions you had to enable a switch to support
SELinux, but in Warewulf v4 and above, it is always enabled, but you
do have to make some configuration changes.
#. The first thing to do is to change the provision "Root" option. By default this is ``initramfs`` which means, take whatever file system the kernel hands us. By default this is a ``ramfs`` type file system (however this may not always be the case) and this format does not support extended file attributes which are required for SELinux. Instead you must configure Warewulf to use ``tmpfs`` for the provisioning file system. That change is made like: ``$ sudo wwctl profile set --root tmpfs default``.
#. The first thing to do is to change the provision "Root" option. By
default this is ``initramfs`` which means, take whatever file
system the kernel hands us. By default this is a ``ramfs`` type
file system (however this may not always be the case) and this
format does not support extended file attributes which are required
for SELinux. Instead you must configure Warewulf to use ``tmpfs``
for the provisioning file system. That change is made like: ``$
sudo wwctl profile set --root tmpfs default``.
#. That is all you have to do to ensure that Warewulf will probably support SELinux. Once that is done, you just need to enable SELinux in ``/etc/sysconfig/selinux`` and install the appropriate profiles into the container.
#. That is all you have to do to ensure that Warewulf will probably
support SELinux. Once that is done, you just need to enable SELinux
in ``/etc/sysconfig/selinux`` and install the appropriate profiles
into the container.
Provisioning Security
=====================
Provisioning in generally is known to be rather "insecure" because when a user lands on a compute node, there is generally nothing stopping them from spoofing a provision request and downloading the provisioned raw materials for inspection.
Provisioning in generally is known to be rather "insecure" because
when a user lands on a compute node, there is generally nothing
stopping them from spoofing a provision request and downloading the
provisioned raw materials for inspection.
In Warewulf there are two ways to secure the provisioning process:
#. The provisioning connections and transfers are not secure due to not being able to manage a secure root of trust through a PXE process. The best way to secure the provisioning process is to enact a vLAN used specifically for provisioning. Warewulf supports this but you must consult your switch documentation and features to implement a default vLAN for provisioning and ensure that the runtime operating system is configured for a different tagged vLAN once booted.
#. The provisioning connections and transfers are not secure due to
not being able to manage a secure root of trust through a PXE
process. The best way to secure the provisioning process is to
enact a vLAN used specifically for provisioning. Warewulf supports
this but you must consult your switch documentation and features to
implement a default vLAN for provisioning and ensure that the
runtime operating system is configured for a different tagged vLAN
once booted.
#. Warewulf will leverage hardware "asset tags" which almost all vendors support. It is a configurable string that is configured in firmware and accessible only via root or physical access. During provisioning (as well as post provisioning via ``wwclient``) Warewulf, can use the asset tag as a secure token. If you have setup your hardware with an asset tag, you simply need to tell Warewulf what that asset tag is. When the asset tag is defined in Warewulf (``wwctl node set --assetkey "..."``), it will only provision and communicate with requests from that system matching that asset tag.
#. Warewulf will leverage hardware "asset tags" which almost all
vendors support. It is a configurable string that is configured in
firmware and accessible only via root or physical access. During
provisioning (as well as post provisioning via ``wwclient``)
Warewulf, can use the asset tag as a secure token. If you have
setup your hardware with an asset tag, you simply need to tell
Warewulf what that asset tag is. When the asset tag is defined in
Warewulf (``wwctl node set --assetkey "..."``), it will only
provision and communicate with requests from that system matching
that asset tag.
Summary
=======
Warewulf does not limit the security posture of a cluster at all, and perhaps it increases it as not all provisioners work with firewalls and SELinux enabled and enforcing. But even with that, cluster security is always up to the system manager and organizational policies. Our job is just to ensure that we don't limit those policies in any way.
Warewulf does not limit the security posture of a cluster at all, and
perhaps it increases it as not all provisioners work with firewalls
and SELinux enabled and enforcing. But even with that, cluster
security is always up to the system manager and organizational
policies. Our job is just to ensure that we don't limit those policies
in any way.

57
userdocs/contents/setup.rst
View File

@@ -5,34 +5,69 @@ Control Server Setup
Operating System Installation
=============================
Warewulf has almost no predetermined or required configurations aside from a base architecture networking layout. Install your Linux distribution of choice as you would like, but do pay attention to the cluster's private network configuration.
Warewulf has almost no predetermined or required configurations aside
from a base architecture networking layout. Install your Linux
distribution of choice as you would like, but do pay attention to the
cluster's private network configuration.
Network
=======
A clustered resource depends on a private management network. This network can be either persistent (it is always "up" even after provisioning) to temporary which might only be used for provisioning and/or out of band system control and management e.g. IPMI).
A clustered resource depends on a private management network. This
network can be either persistent (it is always "up" even after
provisioning) to temporary which might only be used for provisioning
and/or out of band system control and management e.g. IPMI).
It is important for this management network to be private to the compute resource because Warewulf requires network services on that network which may conflict with services on the production/public network (e.g. DHCP). It is also important from a security perspective as the management network for typical HPC systems have an implied trust level associated with it and generally there is no firewalling or network monitoring occurring on these networks.
It is important for this management network to be private to the
compute resource because Warewulf requires network services on that
network which may conflict with services on the production/public
network (e.g. DHCP). It is also important from a security perspective
as the management network for typical HPC systems have an implied
trust level associated with it and generally there is no firewalling
or network monitoring occurring on these networks.
Usually, the control node is "dual homed" which means it has at least two interface cards, one connected to the private cluster network and one dedicated to the public network (as the figure above demonstrates).
Usually, the control node is "dual homed" which means it has at least
two interface cards, one connected to the private cluster network and
one dedicated to the public network (as the figure above
demonstrates).
> note: It is possible to omit the public network interface with a reverse NAT. Warewulf can operate in this configuration but it extends beyond the scope of this documentation.
.. note::
Many clusters have more then one private network. This is common for performance critical HPC clusters that implement a high speed and low latency network like InfiniBand. In this case, this network is used for high speed data transfers for inter-process communication between compute nodes and file system IO.
It is possible to omit the public network interface with a reverse
NAT. Warewulf can operate in this configuration but it extends
beyond the scope of this documentation.
Warewulf will need to be configured to use the private cluster management network. Warewulf will use this network for booting the nodes over PXE. There are three network protocols used to accomplish this DHCP/BOOT, TFTP, and HTTP on port ``9873``. Warewulf will use the operating system's provided version of DHCP (ISC-DHCP) and TFTP for the PXE bootstrap to iPXE, and then iPXE will use Warewulf's internal HTTP services to transfer the larger files for provisioning.
Many clusters have more then one private network. This is common for
performance critical HPC clusters that implement a high speed and low
latency network like InfiniBand. In this case, this network is used
for high speed data transfers for inter-process communication between
compute nodes and file system IO.
Warewulf will need to be configured to use the private cluster
management network. Warewulf will use this network for booting the
nodes over PXE. There are three network protocols used to accomplish
this DHCP/BOOT, TFTP, and HTTP on port ``9873``. Warewulf will use the
operating system's provided version of DHCP (ISC-DHCP) and TFTP for
the PXE bootstrap to iPXE, and then iPXE will use Warewulf's internal
HTTP services to transfer the larger files for provisioning.
Addressing
==========
The addressing scheme of your private cluster network is 100% up to the system integrator, but for large clusters, many organizations like to organize the address allocations. Below is a recommended IP addressing scheme which we will use for the rest of this document.
The addressing scheme of your private cluster network is 100% up to
the system integrator, but for large clusters, many organizations like
to organize the address allocations. Below is a recommended IP
addressing scheme which we will use for the rest of this document.
* ``10.0.0.1``: Private network address IP
* ``255.255.252.0``: Private network subnet mask
Here is an example of how the cluster's address can be divided for a 255 node cluster:
Here is an example of how the cluster's address can be divided for a
255 node cluster:
* ``10.0.0.1 - 10.0.0.255``: Cluster infrastructure including this host, schedulers, file systems, routers, switches, etc.
* ``10.0.0.1 - 10.0.0.255``: Cluster infrastructure including this
host, schedulers, file systems, routers, switches, etc.
* ``10.0.1.1 - 10.0.1.255``: DHCP range for booting nodes
* ``10.0.2.1 - 10.0.2.255``: Static node addresses
* ``10.0.3.1 - 10.0.3.255``: IPMI and/or out of band addresses for the compute nodes
* ``10.0.3.1 - 10.0.3.255``: IPMI and/or out of band addresses for the
compute nodes

70
userdocs/contents/stateless.rst
View File

@@ -5,36 +5,82 @@ Stateless Provisioning
Why is Provisioning Important
=============================
Clusters are pools of servers bundled together to do a particular job or set of jobs. While there are a number of different use cases for clustering today, Warewulf was originally designed out of necessity.
Clusters are pools of servers bundled together to do a particular job
or set of jobs. While there are a number of different use cases for
clustering today, Warewulf was originally designed out of necessity.
Back in 2000, when Linux clustering was growing up for HPC, the issues of scale became apparent. Of course in HPC, there are many scalability factors which needed to be overcome as we continued to scale up clusters. Pretty early on was the "administrative scaling" which is the factor that full time systems administrators could only maintain so many servers. While homogenous configurations were able to help that, we still had the problem that every installed server became a point of administration, version creep, and debugging. The larger the cluster, the harder this problem was to solve.
Back in 2000, when Linux clustering was growing up for HPC, the issues
of scale became apparent. Of course in HPC, there are many scalability
factors which needed to be overcome as we continued to scale up
clusters. Pretty early on was the "administrative scaling" which is
the factor that full time systems administrators could only maintain
so many servers. While homogenous configurations were able to help
that, we still had the problem that every installed server became a
point of administration, version creep, and debugging. The larger the
cluster, the harder this problem was to solve.
Warewulf was created to help with exactly this.
Provisioning Overview
=====================
Provisioning in this definition is the process of putting an operating system onto a system. There are many ways to provision operating system images, from copying hard drives, to scripted installs, to automated installs. There are many valuable tools to facilitate this and they all helped to solve this problem.
Provisioning in this definition is the process of putting an operating
system onto a system. There are many ways to provision operating
system images, from copying hard drives, to scripted installs, to
automated installs. There are many valuable tools to facilitate this
and they all helped to solve this problem.
In a cluster environment, this means one could group all of the nodes together, to be installed in bulk. Previous to cluster provisioning system administrators would go around to each cluster node, and install it from scratch, with an ISO or USB thumb drive. This obviously is not scalable. But being able to automatically install hundreds or thousands of computers in parallel and automate the management of these systems completely changed the paradigm.
In a cluster environment, this means one could group all of the nodes
together, to be installed in bulk. Previous to cluster provisioning
system administrators would go around to each cluster node, and
install it from scratch, with an ISO or USB thumb drive. This
obviously is not scalable. But being able to automatically install
hundreds or thousands of computers in parallel and automate the
management of these systems completely changed the paradigm.
There were several cluster provision and management toolkits already available when Warewulf was created and while these tools absolutely helped, there was even more optimization to be had. Stateless computing.
There were several cluster provision and management toolkits already
available when Warewulf was created and while these tools absolutely
helped, there was even more optimization to be had. Stateless
computing.
Stateless Provisioning
======================
The next step past automated installs is to just skip the installation completely; boot directly into the runtime operating system without ever doing an installation.
The next step past automated installs is to just skip the installation
completely; boot directly into the runtime operating system without
ever doing an installation.
This is Warewulf.
Stateless provisioning is realizing you never have to install another compute node. Think of it like booting a LiveOS or LiveISO on nodes over the network. This means that no node individually is a point of system administration, but rather the entire cluster, inclusively is administrated as a single unit.
Stateless provisioning is realizing you never have to install another
compute node. Think of it like booting a LiveOS or LiveISO on nodes
over the network. This means that no node individually is a point of
system administration, but rather the entire cluster, inclusively is
administrated as a single unit.
If all cluster nodes are booting the same OS image (or set of OS images), then any individual nodes that have problems is hardware. Debugging software and doing system administration in single points within a cluster is not needed. There is no version drift, because it is not possible for nodes to fall out of sync. Every reboot makes it exactly the same as its neighbors.
If all cluster nodes are booting the same OS image (or set of OS
images), then any individual nodes that have problems is
hardware. Debugging software and doing system administration in single
points within a cluster is not needed. There is no version drift,
because it is not possible for nodes to fall out of sync. Every reboot
makes it exactly the same as its neighbors.
Warewulf provisions the operating system by default to system memory. There is no need for hard drives with Warewulf.
Warewulf provisions the operating system by default to system
memory. There is no need for hard drives with Warewulf.
Previous versions of Warewulf had the ability to write the operating system to hard disk as well as do hybrid provisioning (the core operating system in memory, other pieces overlaid over NFS) but these have been obsoleted in Warewulf v4 as there are easier ways to accomplish the same thing (e.g. use of swap space).
Previous versions of Warewulf had the ability to write the operating
system to hard disk as well as do hybrid provisioning (the core
operating system in memory, other pieces overlaid over NFS) but these
have been obsoleted in Warewulf v4 as there are easier ways to
accomplish the same thing (e.g. use of swap space).
> note: If you wish to provision to the hard drive, we might add that feature back based on user requests but in the mean time, you may wish to look at an automated or scripted installation platform instead of a cluster provisioning system.
.. note::
In our experience, the Warewulf provisioning model is by far the most advantageous, simplest, and most flexible and scalable cluster provisioning platform available.
If you wish to provision to the hard drive, we might add that
feature back based on user requests but in the mean time, you may
wish to look at an automated or scripted installation platform
instead of a cluster provisioning system.
In our experience, the Warewulf provisioning model is by far the most
advantageous, simplest, and most flexible and scalable cluster
provisioning platform available.

42
userdocs/contents/templating.rst
View File

@@ -2,16 +2,23 @@
Templating
==========
Warewulf uses the ``text/template`` engine to convert dynamic content into static content and auto-populate files with the appropriate data on demand.
Warewulf uses the ``text/template`` engine to convert dynamic content
into static content and auto-populate files with the appropriate data
on demand.
In Warewulf, you can find templates both for the provisioning services (e.g. ``/etc/warewulf/ipxe/``, ``/etc/warewulf/dhcp/``, and ``/etc/warewulf/hosts.tmpl``) as well as within the runtime and system overlays.
In Warewulf, you can find templates both for the provisioning services
(e.g. ``/etc/warewulf/ipxe/``, ``/etc/warewulf/dhcp/``, and
``/etc/warewulf/hosts.tmpl``) as well as within the runtime and system
overlays.
(more documentation coming soon)
Examples
========
Comment
-------
.. code-block:: go
{{ /* This comment won't show up in file, but an empty line /* }}
@@ -57,6 +64,7 @@ iterate over elements of an array and decrement ``i`` each loop cycle
Access Tag
----------
Acces the value of an individual tag `foo`
.. code-block:: go
@@ -68,7 +76,9 @@ Acces the value of an individual tag `foo`
Create Multiple Files
---------------------
The following template will create a file called `ifcfg-NETWORKNAME.xml` for every network present on the node
The following template will create a file called
`ifcfg-NETWORKNAME.xml` for every network present on the node
.. code-block:: go
@@ -125,11 +135,12 @@ The following template will create a file called `ifcfg-NETWORKNAME.xml` for eve
</interface>
{{ end -}}
Special Commands
----------------
Include
^^^^^^^
A file from the host can be include with following template
.. code-block:: go
@@ -138,6 +149,7 @@ A file from the host can be include with following template
IncludeFrom
^^^^^^^^^^^
With following snippet a file from a given container can be included
.. code-block:: go
@@ -147,10 +159,10 @@ With following snippet a file from a given container can be included
IncludeBlock
^^^^^^^^^^^^
Includes a file up to the line where a abort string is found. This is useful, e.g.,
for the hosts file, which can have local modifications which are not controlled
by warewulf. For this example the abort string is
"# Do not edit after this line"
Includes a file up to the line where a abort string is found. This is
useful, e.g., for the hosts file, which can have local modifications
which are not controlled by warewulf. For this example the abort
string is "# Do not edit after this line"
.. code-block:: go
@@ -159,11 +171,11 @@ by warewulf. For this example the abort string is
# Host: {{.BuildHost}}
# Time: {{.BuildTime}}
# Source: {{.BuildSource}}
# Warewulf Server
{{$.Ipaddr}} warewulf {{$.BuildHost}}
{{- range $node := $.AllNodes}} {{/* for each node */}}
# Entry for {{$node.Id.Get}}
{{- range $devname, $netdev := $node.NetDevs}} {{/* for each network device on the node */}}
@@ -183,10 +195,10 @@ If ``{{ abort }}`` is found in a template, the resulting file isn't written.
Nobackup
^^^^^^^^
If a file exists on the target, a backup file is written with the suffix
`.wwbackup`. This only happens for the `host` overlay, as e.g. the `/etc/hosts`
exists on the host. If this is not the intended behavior, the ``{{ nobackup }}``
flag can be added to a template.
If a file exists on the target, a backup file is written with the
suffix `.wwbackup`. This only happens for the `host` overlay, as
e.g. the `/etc/hosts` exists on the host. If this is not the intended
behavior, the ``{{ nobackup }}`` flag can be added to a template.
Split
^^^^^

88
userdocs/contributing/contributing.rst
View File

@@ -2,35 +2,57 @@
Contributing
============
Warewulf is an open source project, meaning we have the challenge of limited resources. We are grateful for any support that you can offer. Helping other users, raising issues, helping write documentation, or contributing code are all ways to help!
Warewulf is an open source project, meaning we have the challenge of
limited resources. We are grateful for any support that you can
offer. Helping other users, raising issues, helping write
documentation, or contributing code are all ways to help!
Join the community
==================
This is a huge endeavor, and your help would be greatly appreciated! Post to online communities about Warewulf, and request that your distribution vendor, service provider, and system administrators include Warewulf for you!
This is a huge endeavor, and your help would be greatly appreciated!
Post to online communities about Warewulf, and request that your
distribution vendor, service provider, and system administrators
include Warewulf for you!
Warewulf on Slack
-----------------
Many of our users come to Slack for quick help with an issue. You can find us at `HPCng <https://join.slack.com/t/hpcng/shared_invite/zt-k9atb2dj-rnlPjSh5Os3Ks6vlDEOyAA>`_.
Many of our users come to Slack for quick help with an issue. You can
find us at `HPCng
<https://join.slack.com/t/hpcng/shared_invite/zt-k9atb2dj-rnlPjSh5Os3Ks6vlDEOyAA>`_.
Raise an Issue
==============
For general bugs/issues, you can open an issue `at the GitHub repo <https://github.com/hpcng/warewulf/issues/new>`_. However, if you find a security related issue/problem, please email HPCng directly at `security@hpcng.org <mailto:security@hpcng.org>`_. More information about the HPCng security policies and procedures can be found `here <https://hpcng.org/security-policy>`_.
For general bugs/issues, you can open an issue `at the GitHub repo
<https://github.com/hpcng/warewulf/issues/new>`_. However, if you find
a security related issue/problem, please email HPCng directly at
`security@hpcng.org <mailto:security@hpcng.org>`_. More information
about the HPCng security policies and procedures can be found `here
<https://hpcng.org/security-policy>`_.
Contribute to the code
======================
We use the traditional `GitHub Flow <https://guides.github.com/introduction/flow>`_ to develop. This means that you fork the main repo, create a new branch to make changes, and submit a pull request (PR) to the master branch.
We use the traditional `GitHub Flow
<https://guides.github.com/introduction/flow>`_ to develop. This means
that you fork the main repo, create a new branch to make changes, and
submit a pull request (PR) to the master branch.
Check out our official `CONTRIBUTING.md <https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md>`_ document, which also includes a `code of conduct <https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md#code-of-conduct>`_.
Check out our official `CONTRIBUTING.md
<https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md>`_
document, which also includes a `code of conduct
<https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md#code-of-conduct>`_.
Step 1. Fork the repo
---------------------
To contribute to Warewulf, you should obtain a GitHub account and fork the `Warewulf <https://github.com/hpcng/warewulf>`_ repository. Once forked, clone your fork of the repo to your computer. (Obviously, you should replace ``your-username`` with your GitHub username.)
To contribute to Warewulf, you should obtain a GitHub account and fork
the `Warewulf <https://github.com/hpcng/warewulf>`_ repository. Once
forked, clone your fork of the repo to your computer. (Obviously, you
should replace ``your-username`` with your GitHub username.)
.. code-block:: bash
@@ -40,10 +62,11 @@ To contribute to Warewulf, you should obtain a GitHub account and fork the `Ware
Step 2. Checkout a new branch
-----------------------------
`Branches <https://guides.github.com/introduction/flow>`_` are a way of
isolating your features from the main branch. Given that we’ve just cloned the
repo, we will probably want to make a new branch from master in which to work on
our new feature. Lets call that branch ``new-feature``:
`Branches <https://guides.github.com/introduction/flow>`_ are a way
of isolating your features from the main branch. Given that we’ve just
cloned the repo, we will probably want to make a new branch from
master in which to work on our new feature. Lets call that branch
``new-feature``:
.. code-block:: bash
@@ -51,37 +74,50 @@ our new feature. Lets call that branch ``new-feature``:
git checkout -b new-feature
.. note::
You can always check which branch you are in by running ``git branch``.
You can always check which branch you are in by running ``git
branch``.
Step 3. Make your changes
-------------------------
On your new branch, go nuts! Make changes, test them, and when you are happy commit the changes to the branch:
On your new branch, go nuts! Make changes, test them, and when you are
happy commit the changes to the branch:
.. code-block:: bash
git add file-changed1 file-changed2...
git commit -m "what changed?"
This commit message is important - it should describe exactly the changes that you have made. Good commit messages read like so:
This commit message is important - it should describe exactly the
changes that you have made. Good commit messages read like so:
.. code-block:: bash
git commit -m "changed function getConfig in functions.go to output csv to fix #2"
git commit -m "updated docs about shell to close #10"
The tags ``close #10`` and ``fix #2`` are referencing issues that are posted on the upstream repo where you will direct your pull request. When your PR is merged into the master branch, these messages will automatically close the issues, and further, they will link your commits directly to the issues they intend to fix. This will help future maintainers understand your contribution, or (hopefully not) revert the code back to a previous version if necessary.
The tags ``close #10`` and ``fix #2`` are referencing issues that are
posted on the upstream repo where you will direct your pull
request. When your PR is merged into the master branch, these messages
will automatically close the issues, and further, they will link your
commits directly to the issues they intend to fix. This will help
future maintainers understand your contribution, or (hopefully not)
revert the code back to a previous version if necessary.
Step 4. Push your branch to your fork
-------------------------------------
When you are done with your commits, you should push your branch to your fork (and you can also continuously push commits here as you work):
When you are done with your commits, you should push your branch to
your fork (and you can also continuously push commits here as you
work):
.. code-block:: bash
git push origin new-feature
Note that you should always check the status of your branches to see what has been pushed (or not):
Note that you should always check the status of your branches to see
what has been pushed (or not):
.. code-block:: bash
@@ -90,12 +126,24 @@ Note that you should always check the status of your branches to see what has be
Step 5. Submit a Pull Request
-----------------------------
Once you have pushed your branch, then you can go to your fork (in the web GUI on GitHub) and `submit a Pull Request <https://help.github.com/articles/creating-a-pull-request>`_. Regardless of the name of your branch, your PR should be submitted to the ``main`` branch. Submitting your PR will open a conversation thread for the maintainers of Warewulf to discuss your contribution. At this time, the continuous integration that is linked with the code base will also be executed. If there is an issue, or if the maintainers suggest changes, you can continue to push commits to your branch and they will update the Pull Request.
Once you have pushed your branch, then you can go to your fork (in the
web GUI on GitHub) and `submit a Pull Request
<https://help.github.com/articles/creating-a-pull-request>`_. Regardless
of the name of your branch, your PR should be submitted to the
``main`` branch. Submitting your PR will open a conversation thread
for the maintainers of Warewulf to discuss your contribution. At this
time, the continuous integration that is linked with the code base
will also be executed. If there is an issue, or if the maintainers
suggest changes, you can continue to push commits to your branch and
they will update the Pull Request.
Step 6. Keep your branch in sync
--------------------------------
Cloning the repo will create an exact copy of the Warewulf repository at that moment. As you work, your branch may become out of date as others merge changesinto the upstream master. In the event that you need to update a branch, you will need to follow the next steps:
Cloning the repo will create an exact copy of the Warewulf repository
at that moment. As you work, your branch may become out of date as
others merge changesinto the upstream master. In the event that you
need to update a branch, you will need to follow the next steps:
.. code-block:: bash
@@ -107,4 +155,4 @@ Cloning the repo will create an exact copy of the Warewulf repository at that mo
# to update your fork
git push origin master
git checkout new-feature
git merge master
git merge master

24
userdocs/contributing/development-environment-vbox.rst
View File

@@ -1,11 +1,12 @@
====================================
Development Environment (VirtualBox)
====================================
I have VirtualBox running on my desktop.
1. Create a NAT Network (a private vlan) to be used for the Warewlf Server and compute nodes inside the VirtualBox. Make sure to turnoff DHCP service within this NAT Network.
1. Create a NAT Network (a private vlan) to be used for the Warewlf
Server and compute nodes inside the VirtualBox. Make sure to
turnoff DHCP service within this NAT Network.
.. code-block:: console
@@ -13,7 +14,12 @@ I have VirtualBox running on my desktop.
VBoxManage natnetwork add --netname wwnatnetwork --network "10.0.8.0/24" --enable --dhcp off
2. Create a Centos 7 development Virtual machine (wwdev) to be used as the Warewulf Server. Enable two Network adapters one with a standard NAT and SSH port mapping such that you can access this VM from the host machine. Assign the second network adapter to the NAT Network created in step #1. Assign sufficient memory (e.g: 4GB) to the VM.
2. Create a Centos 7 development Virtual machine (wwdev) to be used as
the Warewulf Server. Enable two Network adapters one with a
standard NAT and SSH port mapping such that you can access this VM
from the host machine. Assign the second network adapter to the NAT
Network created in step #1. Assign sufficient memory (e.g: 4GB) to
the VM.
.. code-block:: console
@@ -135,7 +141,14 @@ I have VirtualBox running on my desktop.
sudo wwctl server start
sudo wwctl server status
4. Create a new guest VM instance inside the VirtualBox to be the Warewulf client/compute node. Under the system configuration make sure to select the optical and network options only for the boot order. The default iPXE used by VirtualBox does not come with bzImage capability which is needed for Warewulf. Download the ipxe.iso available at ipxe.org and mount the ipxe.iso to the optical drive. Enable one Network adapter for this VM and assign it to the NAT Network created in step #1 above.
4. Create a new guest VM instance inside the VirtualBox to be the
Warewulf client/compute node. Under the system configuration make
sure to select the optical and network options only for the boot
order. The default iPXE used by VirtualBox does not come with
bzImage capability which is needed for Warewulf. Download the
ipxe.iso available at ipxe.org and mount the ipxe.iso to the
optical drive. Enable one Network adapter for this VM and assign it
to the NAT Network created in step #1 above.
.. code-block:: console
@@ -144,4 +157,5 @@ I have VirtualBox running on my desktop.
# VM Settings -> Storage and mount the above download ipxe.so to the Optical Drive.
# VM Settings -> Network Enable adapter #1, attach to 'Nat Network' and choose 'wwnatnetwork' from the drop down list.
Boot your node and watch the console and the output of the Warewulfd process
Boot your node and watch the console and the output of the Warewulfd
process.

19
userdocs/contributing/documentation.rst
View File

@@ -2,10 +2,21 @@
Documentation
=============
We (like almost all open source software providers) have a documentation dilemma… We tend to focus on the code features and functionality before working on documentation. And there is very good reason for this: we want to share the love so nobody feels left out!
We (like almost all open source software providers) have a
documentation dilemma… We tend to focus on the code features and
functionality before working on documentation. And there is very good
reason for this: we want to share the love so nobody feels left out!
You can contribute to the documentation by `raising an issue to suggest an improvement <https://github.com/hpcng/warewulf-web/issues/new>`_ or by sending a `pull request <https://github.com/hpcng/warewulf-web/compare>`_ on `our repository <https://github.com/hpcng/warewulf-web>`_.
You can contribute to the documentation by `raising an issue to
suggest an improvement
<https://github.com/hpcng/warewulf-web/issues/new>`_ or by sending a
`pull request <https://github.com/hpcng/warewulf-web/compare>`_ on
`our repository <https://github.com/hpcng/warewulf-web>`_.
The current documentation is generated with `Docusaurus <https://v2.docusaurus.io/docs/>`_.
The current documentation is generated with `Docusaurus
<https://v2.docusaurus.io/docs/>`_.
For more information on using Git and GitHub to create a pull request suggesting additions and edits to the docs, see the `section on contributing to the code <contributing>`_. The procedure is identical for contributions to the documentation and the code base.
For more information on using Git and GitHub to create a pull request
suggesting additions and edits to the docs, see the `section on
contributing to the code <contributing>`_. The procedure is identical
for contributions to the documentation and the code base.

2
userdocs/index.rst
View File

@@ -46,4 +46,4 @@ Welcome to the Warewulf User Guide!
:maxdepth: 2
:caption: Reference
Glossary <reference/glossary>
Glossary <reference/glossary>

58
userdocs/quickstart/el7.rst
View File

@@ -17,7 +17,8 @@ Install Warewulf and dependencies
Configure firewalld
===================
Restart firewalld to register the added service file, add the service to the default zone, and reload.
Restart firewalld to register the added service file, add the service
to the default zone, and reload.
.. code-block:: bash
@@ -30,9 +31,10 @@ Restart firewalld to register the added service file, add the service to the def
Configure the controller
========================
Edit the file ``/etc/warewulf/warewulf.conf`` and ensure that you've set the appropriate
configuration parameters. Here are some of the defaults for reference assuming that ``192.168.200.1``
is the IP address of your cluster's private network interface:
Edit the file ``/etc/warewulf/warewulf.conf`` and ensure that you've
set the appropriate configuration parameters. Here are some of the
defaults for reference assuming that ``192.168.200.1`` is the IP
address of your cluster's private network interface:
.. code-block:: yaml
@@ -59,8 +61,10 @@ is the IP address of your cluster's private network interface:
- /var/warewulf
.. note::
The DHCP range ends at `192.168.200.99` and as you will see below, the first node static IP
address (post boot) is configured to `192.168.200.100`.
The DHCP range ends at `192.168.200.99` and as you will see below,
the first node static IP address (post boot) is configured to
`192.168.200.100`.
Start and enable the Warewulf service
=====================================
@@ -73,21 +77,29 @@ Start and enable the Warewulf service
Configure system services automatically
=======================================
There are a number of services and configurations that Warewulf relies on to operate.
If you wish to configure all services, you can do so individually (omitting the ``--all``)
will print a help and usage instructions.
There are a number of services and configurations that Warewulf relies
on to operate. If you wish to configure all services, you can do so
individually (omitting the ``--all``) will print a help and usage
instructions.
.. code-block:: bash
sudo wwctl configure --all
.. note::
If you just installed the system fresh and have SELinux enforcing, you may need to reboot the system at this stage to properly set the contexts of the TFTP contents. After rebooting, you might also need to run ``$ sudo restorecon -Rv /var/lib/tftpboot/`` if there are errors with TFTP still.
If you just installed the system fresh and have SELinux enforcing,
you may need to reboot the system at this stage to properly set the
contexts of the TFTP contents. After rebooting, you might also need
to run ``$ sudo restorecon -Rv /var/lib/tftpboot/`` if there are
errors with TFTP still.
Pull and build the VNFS container and kernel
============================================
This will pull a basic VNFS container from Docker Hub and import the default running kernel from the controller node and set both in the "default" node profile.
This will pull a basic VNFS container from Docker Hub and import the
default running kernel from the controller node and set both in the
"default" node profile.
.. code-block:: bash
@@ -97,13 +109,19 @@ This will pull a basic VNFS container from Docker Hub and import the default run
Set up the default node profile
===============================
The ``--setdefault`` arguments above will automatically set those entries in the default profile, but if you wanted to set them by hand to something different, you can do the following:
The ``--setdefault`` arguments above will automatically set those
entries in the default profile, but if you wanted to set them by hand
to something different, you can do the following:
.. code-block:: bash
sudo wwctl profile set -y default -K $(uname -r) -C centos-7
Next we set some default networking configurations for the first ethernet device. On modern Linux distributions, the name of the device is not critical, as it will be setup according to the HW address. Because all nodes will share the netmask and gateway configuration, we can set them in the default profile as follows:
Next we set some default networking configurations for the first
ethernet device. On modern Linux distributions, the name of the device
is not critical, as it will be setup according to the HW
address. Because all nodes will share the netmask and gateway
configuration, we can set them in the default profile as follows:
.. code-block:: bash
@@ -113,15 +131,21 @@ Next we set some default networking configurations for the first ethernet device
Add a node
==========
Adding nodes can be done while setting configurations in one command. Here we are setting the IP address of ``eth0`` and setting this node to be discoverable, which will then automatically have the HW address added to the configuration as the node boots.
Adding nodes can be done while setting configurations in one
command. Here we are setting the IP address of ``eth0`` and setting
this node to be discoverable, which will then automatically have the
HW address added to the configuration as the node boots.
Node names must be unique. If you have node groups and/or multiple clusters, designate them using dot notation.
Node names must be unique. If you have node groups and/or multiple
clusters, designate them using dot notation.
Note that the full node configuration comes from both cascading profiles and node configurations which always supersede profile configurations.
Note that the full node configuration comes from both cascading
profiles and node configurations which always supersede profile
configurations.
.. code-block:: bash
sudo wwctl node add n0000.cluster --netname default -I 192.168.200.100 --discoverable
sudo wwctl node list -a n0000
Turn on your compute node and watch it boot!
Turn on your compute node and watch it boot!

75
userdocs/quickstart/el8.rst
View File

@@ -19,7 +19,8 @@ Install Warewulf and dependencies
Configure firewalld
===================
Restart firewalld to register the added service file, add the service to the default zone, and reload.
Restart firewalld to register the added service file, add the service
to the default zone, and reload.
.. code-block:: bash
@@ -32,9 +33,10 @@ Restart firewalld to register the added service file, add the service to the def
Configure the controller
========================
Edit the file ``/etc/warewulf/warewulf.conf`` and ensure that you've set the appropriate
configuration parameters. Here are some of the defaults for reference assuming that ``192.168.200.1``
is the IP address of your cluster's private network interface:
Edit the file ``/etc/warewulf/warewulf.conf`` and ensure that you've
set the appropriate configuration parameters. Here are some of the
defaults for reference assuming that ``192.168.200.1`` is the IP
address of your cluster's private network interface:
.. code-block:: yaml
@@ -61,8 +63,10 @@ is the IP address of your cluster's private network interface:
- /var/warewulf
.. note::
The DHCP range ends at ``192.168.200.99`` and as you will see below, the first node static IP
address (post boot) is configured to ``192.168.200.100``.
The DHCP range ends at ``192.168.200.99`` and as you will see
below, the first node static IP address (post boot) is configured
to ``192.168.200.100``.
Start and enable the Warewulf service
=====================================
@@ -75,22 +79,29 @@ Start and enable the Warewulf service
Configure system services automatically
=======================================
There are a number of services and configurations that Warewulf relies on to operate.
If you wish to configure all services, you can do so individually (omitting the ``--all``)
will print a help and usage instructions.
There are a number of services and configurations that Warewulf relies
on to operate. If you wish to configure all services, you can do so
individually (omitting the ``--all``) will print a help and usage
instructions.
.. code-block:: bash
sudo wwctl configure --all
.. note::
If you just installed the system fresh and have SELinux enforcing, you may need to reboot the system at this stage to properly set the contexts of the TFTP contents. After rebooting, you might also need to run ``$ sudo restorecon -Rv /var/lib/tftpboot/`` if there are errors with TFTP still.
If you just installed the system fresh and have SELinux enforcing,
you may need to reboot the system at this stage to properly set the
contexts of the TFTP contents. After rebooting, you might also need
to run ``$ sudo restorecon -Rv /var/lib/tftpboot/`` if there are
errors with TFTP still.
Pull and build the VNFS container (including the kernel)
========================================================
This will pull a basic VNFS container from Docker Hub and import the default running
kernel from the controller node and set both in the "default" node profile.
This will pull a basic VNFS container from Docker Hub and import the
default running kernel from the controller node and set both in the
"default" node profile.
.. code-block:: bash
@@ -100,26 +111,29 @@ kernel from the controller node and set both in the "default" node profile.
Set up the default node profile
===============================
Node configurations can be set via node profiles. Each node by default is configured to
be part of the ``default`` node profile, so any changes you make to that profile will
affect all nodes.
Node configurations can be set via node profiles. Each node by default
is configured to be part of the ``default`` node profile, so any
changes you make to that profile will affect all nodes.
The following command will set the container we just imported above to the ``default`` node profile:
The following command will set the container we just imported above to
the ``default`` node profile:
.. code-block:: bash
sudo wwctl profile set --yes --container rocky-8 "default"
Next we set some default networking configurations for the first ethernet device. On
modern Linux distributions, the name of the device is not critical, as it will be setup
according to the HW address. Because all nodes will share the netmask and gateway
Next we set some default networking configurations for the first
ethernet device. On modern Linux distributions, the name of the device
is not critical, as it will be setup according to the HW
address. Because all nodes will share the netmask and gateway
configuration, we can set them in the default profile as follows:
.. code-block:: bash
sudo wwctl profile set --yes --netdev eth0 --netmask 255.255.255.0 --gateway 192.168.200.1 "default"
Once those configurations have been set, you can view the changes by listing the profiles as follows:
Once those configurations have been set, you can view the changes by
listing the profiles as follows:
.. code-block:: bash
@@ -128,24 +142,27 @@ Once those configurations have been set, you can view the changes by listing the
Add a node
==========
Adding nodes can be done while setting configurations in one command. Here we are setting
the IP address of ``eth0`` and setting this node to be discoverable, which will then
automatically have the HW address added to the configuration as the node boots.
Adding nodes can be done while setting configurations in one
command. Here we are setting the IP address of ``eth0`` and setting
this node to be discoverable, which will then automatically have the
HW address added to the configuration as the node boots.
Node names must be unique. If you have node groups and/or multiple clusters, designate
them using dot notation.
Node names must be unique. If you have node groups and/or multiple
clusters, designate them using dot notation.
Note that the full node configuration comes from both cascading profiles and node
configurations which always supersede profile configurations.
Note that the full node configuration comes from both cascading
profiles and node configurations which always supersede profile
configurations.
.. code-block:: bash
sudo wwctl node add n0000.cluster --ipaddr 192.168.200.100 --discoverable
At this point you can view the basic configuration of this node by typing the following:
At this point you can view the basic configuration of this node by
typing the following:
.. code-block:: bash
sudo wwctl node list -a n0000.cluster
Turn on your compute node and watch it boot!
Turn on your compute node and watch it boot!

98
userdocs/quickstart/suse15.rst
View File

@@ -20,7 +20,8 @@ Install Warewulf and dependencies
make all
sudo make install
The standard configuration template for the dhcpd service is installed at the wrong location, you have to fix this with
The standard configuration template for the dhcpd service is installed
at the wrong location, you have to fix this with
.. code-block:: bash
@@ -29,16 +30,19 @@ The standard configuration template for the dhcpd service is installed at the wr
Install Warewulf from the open build service
============================================
You can also just install the 'warewulf4' package with ``zypper`` from the openbuild service. Up to date versions are available on the devel project
You can also just install the 'warewulf4' package with ``zypper`` from
the openbuild service. Up to date versions are available on the devel
project
``https://build.opensuse.org/project/show/network:cluster``
Configure the controller
========================
Edit the file ``/etc/warewulf/warewulf.conf`` and ensure that you've set the appropriate
configuration paramaters. Here are some of the defaults for reference assuming that ``192.168.200.1``
is the IP address of your cluster's private network interface:
Edit the file ``/etc/warewulf/warewulf.conf`` and ensure that you've
set the appropriate configuration paramaters. Here are some of the
defaults for reference assuming that ``192.168.200.1`` is the IP
address of your cluster's private network interface:
.. code-block:: yaml
@@ -74,8 +78,10 @@ is the IP address of your cluster's private network interface:
systemd name: nfs-server
.. note::
The DHCP range ends at ``192.168.200.99`` and as you will see below, the first node static IP
address (post boot) is configured to ``192.168.200.100``.
The DHCP range ends at ``192.168.200.99`` and as you will see
below, the first node static IP address (post boot) is configured
to ``192.168.200.100``.
Start and enable the Warewulf service
=====================================
@@ -88,13 +94,16 @@ Start and enable the Warewulf service
Configure system services automatically
=======================================
There are a number of services and configurations that Warewulf relies on to operate.
If you wish to configure all services, you can do so individually (omitting the ``--all``)
will print a help and usage instructions.
There are a number of services and configurations that Warewulf relies
on to operate. If you wish to configure all services, you can do so
individually (omitting the ``--all``) will print a help and usage
instructions.
.. note::
If the ``dhcpd`` service was not used before you will have to add the interface on which
the cluster network is running to the ``DHCP_INTERFACE`` in the file ``/etc/sysconfig/dhcpd``.
If the ``dhcpd`` service was not used before you will have to add
the interface on which the cluster network is running to the
``DHCP_INTERFACE`` in the file ``/etc/sysconfig/dhcpd``.
.. code-block:: bash
@@ -103,8 +112,9 @@ will print a help and usage instructions.
Pull and build the VNFS container and kernel
============================================
This will pull a basic VNFS container from Docker Hub and import the default running
kernel from the controller node and set both in the "default" node profile.
This will pull a basic VNFS container from Docker Hub and import the
default running kernel from the controller node and set both in the
"default" node profile.
.. code-block:: bash
@@ -113,17 +123,18 @@ kernel from the controller node and set both in the "default" node profile.
Set up the default node profile
===============================
The ``--setdefault`` arguments above will automatically set those entries in the default
profile, but if you wanted to set them by hand to something different, you can do the
following:
The ``--setdefault`` arguments above will automatically set those
entries in the default profile, but if you wanted to set them by hand
to something different, you can do the following:
.. code-block:: bash
sudo wwctl profile set -y -C leap15.4
Next we set some default networking configurations for the first ethernet device. On
modern Linux distributions, the name of the device is not critical, as it will be setup
according to the HW address. Because all nodes will share the netmask and gateway
Next we set some default networking configurations for the first
ethernet device. On modern Linux distributions, the name of the device
is not critical, as it will be setup according to the HW
address. Because all nodes will share the netmask and gateway
configuration, we can set them in the default profile as follows:
.. code-block:: bash
@@ -134,15 +145,17 @@ configuration, we can set them in the default profile as follows:
Add a node
==========
Adding nodes can be done while setting configurations in one command. Here we are setting
the IP address of ``eth0`` and setting this node to be discoverable, which will then
automatically have the HW address added to the configuration as the node boots.
Adding nodes can be done while setting configurations in one
command. Here we are setting the IP address of ``eth0`` and setting
this node to be discoverable, which will then automatically have the
HW address added to the configuration as the node boots.
Node names must be unique. If you have node groups and/or multiple clusters, designate
them using dot notation.
Node names must be unique. If you have node groups and/or multiple
clusters, designate them using dot notation.
Note that the full node configuration comes from both cascading profiles and node
configurations which always supersede profile configurations.
Note that the full node configuration comes from both cascading
profiles and node configurations which always supersede profile
configurations.
.. code-block:: bash
@@ -154,22 +167,25 @@ Warewulf Overlays
There are two types of overlays: system and runtime overlays.
System overlays are provisioned to the node before ``/sbin/init`` is called. This enables us
to prepopulate node configurations with content that is node specific like networking and
service configurations.
System overlays are provisioned to the node before ``/sbin/init`` is
called. This enables us to prepopulate node configurations with
content that is node specific like networking and service
configurations.
Runtime overlays are provisioned after the node has booted and periodically during the
normal runtime of the node. Because these overlays are provisioned at periodic intervals,
they are very useful for content that changes, like users and groups.
Runtime overlays are provisioned after the node has booted and
periodically during the normal runtime of the node. Because these
overlays are provisioned at periodic intervals, they are very useful
for content that changes, like users and groups.
Overlays are generated from a template structure that is viewed using the ``wwctl overlay``
commands. Files that end in the ``.ww`` suffix are templates and abide by standard
text/template rules. This supports loops, arrays, variables, and functions making overlays
extremely flexible.
Overlays are generated from a template structure that is viewed using
the ``wwctl overlay`` commands. Files that end in the ``.ww`` suffix
are templates and abide by standard text/template rules. This supports
loops, arrays, variables, and functions making overlays extremely
flexible.
All overlays are compiled before being provisioned. This accelerates the provisioning
process because there is less to do when nodes are being managed at scale.
All overlays are compiled before being provisioned. This accelerates
the provisioning process because there is less to do when nodes are
being managed at scale.
Here are some of the common ``overlay`` commands:
@@ -180,4 +196,4 @@ Here are some of the common ``overlay`` commands:
sudo wwctl overlay edit default /etc/hello_world.ww
sudo wwctl overlay build -a
Boot your compute node and watch it boot!
Boot your compute node and watch it boot!

18
userdocs/reference/glossary.rst
View File

@@ -3,10 +3,19 @@ Glossary
========
Container
Containers are used by Warewulf as the template for the VNFS image. Warewulf containers can be any type of OCI or Singularity standard image formats but maintained on disk as an "OCI bundle". Warewulf integrates with Docker, Docker Hub, any OCI registery, Singularity, standard chroots, etc.
Containers are used by Warewulf as the template for the VNFS
image. Warewulf containers can be any type of OCI or Singularity
standard image formats but maintained on disk as an "OCI
bundle". Warewulf integrates with Docker, Docker Hub, any OCI
registery, Singularity, standard chroots, etc.
Controller
The controller node(s) are the resources responsible for management, control, and administration of the cluster. Historically these systems have been called "master", "head", or "administrative" nodes, but we feel the term "controller" is more appropriate and descriptive of the role of this system.
The controller node(s) are the resources responsible for
management, control, and administration of the
cluster. Historically these systems have been called "master",
"head", or "administrative" nodes, but we feel the term
"controller" is more appropriate and descriptive of the role of
this system.
Initramfs
@@ -17,4 +26,7 @@ Overlays
Virtual Node File System (VNFS)
Workers
Worker nodes are the systems that are being provisioned by Warewulf. The roles of these systems could be "compute", "storage", "GPU", "IO", etc. which would typically be used as a prefix, for example: "**compute worker node**"
Worker nodes are the systems that are being provisioned by
Warewulf. The roles of these systems could be "compute",
"storage", "GPU", "IO", etc. which would typically be used as a
prefix, for example: "**compute worker node**"