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

Merge Enterprise Linux quickstarts

Browse Source 
- Closes #394, #401, #977

Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2024-03-09 22:59:26 -07:00
parent 2bc3a59823
commit 67d5292141
5 changed files with 198 additions and 566 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
userdocs/index.rst
View File

@@ -33,9 +33,7 @@ Welcome to the Warewulf User Guide!
:maxdepth: 2
:caption: Quickstart
EL7 (Rocky Linux and RHEL) <quickstart/el7>
EL8 (Rocky Linux and RHEL) <quickstart/el8>
EL9 (Rocky Linux and RHEL) <quickstart/el9>
Enterprise Linux (Rocky Linux, CentOS, and RHEL) <quickstart/el>
openSUSE Leap and SLES 15 <quickstart/suse15>
Debian 12 <quickstart/debian12>

197
userdocs/quickstart/el.rst Normal file
View File

@@ -0,0 +1,197 @@
===========================================================
Enterprise Linux Quickstart (Rocky Linux, CentOS, and RHEL)
===========================================================
Install Warewulf
================
The preferred way to install Warewulf on Enterprise Linux is using the
the RPMs published in `GitHub releases`_. For example, to install the
v4.5.0rc2 release on Enterprise Linux 9:
.. code-block:: bash
dnf install https://github.com/warewulf/warewulf/releases/download/v4.5.0rc2/warewulf-4.5.0rc2-1.el9.x86_64.rpm
Packages are available for el7, el8, and el9.
.. note::
CentOS 7 (and el7 in general) uses ``yum``, and does not provide ``dnf``.
.. _GitHub releases: https://github.com/warewulf/warewulf/releases
Install Warewulf from source
----------------------------
If you prefer, you can also install Warewulf from source.
.. code-block:: bash
dnf install git
dnf install epel-release
dnf install golang {libassuan,gpgme}-devel unzip tftp-server dhcp nfs-utils ipxe-bootimgs-{x86,aarch64}
git clone https://github.com/warewulf/warewulf.git
cd warewulf
make
make install
.. note::
CentOS 7 (and el7 in general) only provides a single ``ipxe-bootimgs`` package.
Configure firewalld
===================
Restart firewalld to register the added service file, add the service
to the default zone, and reload.
.. code-block:: bash
systemctl restart firewalld
firewall-cmd --permanent --add-service=warewulf
firewall-cmd --permanent --add-service=nfs
firewall-cmd --permanent --add-service=tftp
firewall-cmd --reload
Configure Warewulf
==================
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 ``10.0.0.1/22`` is the IP
address of your cluster's private network interface.
.. code-block:: yaml
WW_INTERNAL: 45
ipaddr: 10.0.0.1
netmask: 255.255.252.0
network: 10.0.0.0
warewulf:
port: 9873
secure: false
update interval: 60
autobuild overlays: true
host overlay: true
syslog: false
datastore: /usr/share
grubboot: false
dhcp:
enabled: true
template: default
range start: 10.0.1.1
range end: 10.0.1.255
systemd name: dhcpd
tftp:
enabled: true
tftproot: /var/lib/tftpboot
systemd name: tftp
ipxe:
"00:00": undionly.kpxe
"00:07": ipxe-snponly-x86_64.efi
"00:09": ipxe-snponly-x86_64.efi
00:0B: arm64-efi/snponly.efi
nfs:
enabled: true
export paths:
- path: /home
export options: rw,sync
mount options: defaults
mount: true
- path: /opt
export options: ro,sync,no_root_squash
mount options: defaults
mount: false
systemd name: nfs-server
container mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
paths:
bindir: /usr/bin
sysconfdir: /etc
localstatedir: /var/lib
ipxesource: /usr/share/ipxe
srvdir: /var/lib
firewallddir: /usr/lib/firewalld/services
systemddir: /usr/lib/systemd/system
wwoverlaydir: /var/lib/warewulf/overlays
wwchrootdir: /var/lib/warewulf/chroots
wwprovisiondir: /var/lib/warewulf/provision
wwclientdir: /warewulf
.. note::
The DHCP range from ``10.0.1.1`` to ``10.0.1.255`` is dedicated for
DHCP during node boot and should not overlap with any static IP
address assignments.
Enable and start the Warewulf service
=====================================
Warewulf provides a service, ``warewulfd``, which responds to node
boot requests.
.. code-block:: bash
systemctl enable --now warewulfd
Configure system services automatically
=======================================
There are a number of services and configurations that Warewulf relies
on to operate. You can configure all such services with ``wwctl
configure --all``.
.. code-block:: bash
wwctl configure --all
.. note::
If you just installed the system fresh and have SELinux enforcing,
you may need to run ``restorecon -Rv /var/lib/tftpboot/`` to label
files written to q`tftpboot``.
Add a base node image container
===============================
This will pull a basic node image 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
wwctl container import docker://ghcr.io/warewulf/warewulf-rockylinux:9 rockylinux-9 --setdefault
Configure a default node profile
================================
In this example, all nodes share the netmask and gateway
configuration, so we can set them in the default profile.
.. code-block:: bash
wwctl profile set -y default --netmask=255.255.252.0 --gateway=10.0.0.1
wwctl profile list
Add a node
==========
Adding nodes can be done while setting configurations in one
command. Here we set the IP address of the default interface; and
setting the node to be discoverable causes the HW address to be added
to the configuration as the node boots.
Node names must be unique. If you are managing multiple clusters with
overlapping names, distinguish them using dot notation.
.. code-block:: bash
wwctl node add n1 --ipaddr=10.0.2.1 --discoverable=true
wwctl node list -a n1
The full node configuration comes from both cascading profiles and
node configurations which always supersede profile configurations.
Turn on your compute node and watch it boot!

165
userdocs/quickstart/el7.rst
View File

@@ -1,165 +0,0 @@
================================
EL7 Quickstart (CentOS and RHEL)
================================
Install Warewulf and dependencies
=================================
.. code-block:: bash
sudo yum install -y golang tftp-server dhcp nfs-utils
git clone https://github.com/warewulf/warewulf.git
cd warewulf
make all
sudo make install
Configure firewalld
===================
Restart firewalld to register the added service file, add the service
to the default zone, and reload.
.. code-block:: bash
sudo systemctl restart firewalld
sudo firewall-cmd --permanent --add-service warewulf
sudo firewall-cmd --permanent --add-service nfs
sudo firewall-cmd --permanent --add-service tftp
sudo firewall-cmd --reload
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:
.. code-block:: yaml
WW_INTERNAL: 43
ipaddr: 192.168.200.1
netmask: 255.255.255.0
network: 192.168.200.0
warewulf:
port: 9873
secure: false
update interval: 60
autobuild overlays: true
host overlay: true
syslog: false
dhcp:
enabled: true
range start: 192.168.200.50
range end: 192.168.200.99
systemd name: dhcpd
tftp:
enabled: true
systemd name: tftp
nfs:
enabled: true
export paths:
- path: /home
export options: rw,sync
mount options: defaults
mount: true
- path: /opt
export options: ro,sync,no_root_squash
mount options: defaults
mount: false
systemd name: nfs-server
container mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
.. 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``.
Start and enable the Warewulf service
=====================================
.. code-block:: bash
# Start and enable the warewulfd service
sudo systemctl enable --now warewulfd
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.
.. 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 ``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.
.. code-block:: bash
sudo wwctl container import docker://ghcr.io/warewulf/warewulf-centos:7 centos-7 --setdefault
sudo wwctl kernel import $(uname -r) --setdefault
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:
.. 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:
.. code-block:: bash
sudo wwctl profile set -y default --netdev eth0 --netmask 255.255.255.0 --gateway 192.168.200.1
sudo wwctl profile list
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.
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.
.. code-block:: bash
sudo wwctl node add n0000.cluster --ipaddr 192.168.200.100 --discoverable true
sudo wwctl node list -a n0000
Turn on your compute node and watch it boot!

199
userdocs/quickstart/el8.rst
View File

@@ -1,199 +0,0 @@
=====================================
EL8 Quickstart (Rocky Linux and RHEL)
=====================================
Install Warewulf and dependencies
=================================
.. code-block:: bash
sudo dnf groupinstall "Development Tools"
sudo dnf install epel-release
sudo dnf config-manager --set-enabled powertools
sudo dnf install golang tftp-server dhcp-server nfs-utils gpgme-devel libassuan-devel
git clone https://github.com/warewulf/warewulf.git
cd warewulf
make clean defaults \
PREFIX=/usr \
BINDIR=/usr/bin \
SYSCONFDIR=/etc \
DATADIR=/usr/share \
LOCALSTATEDIR=/var/lib \
SHAREDSTATEDIR=/var/lib \
MANDIR=/usr/share/man \
INFODIR=/usr/share/info \
DOCDIR=/usr/share/doc \
SRVDIR=/var/lib \
TFTPDIR=/var/lib/tftpboot \
SYSTEMDDIR=/usr/lib/systemd/system \
BASHCOMPDIR=/etc/bash_completion.d/ \
FIREWALLDDIR=/usr/lib/firewalld/services \
WWCLIENTDIR=/warewulf
make all
sudo make install
Configure firewalld
===================
Restart firewalld to register the added service file, add the service
to the default zone, and reload.
.. code-block:: bash
sudo systemctl restart firewalld
sudo firewall-cmd --permanent --add-service warewulf
sudo firewall-cmd --permanent --add-service nfs
sudo firewall-cmd --permanent --add-service tftp
sudo firewall-cmd --reload
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:
.. code-block:: yaml
WW_INTERNAL: 45
ipaddr: 192.168.200.1
netmask: 255.255.255.0
network: 192.168.200.0
warewulf:
port: 9873
secure: false
update interval: 60
autobuild overlays: true
host overlay: true
syslog: false
dhcp:
enabled: true
range start: 192.168.200.50
range end: 192.168.200.99
systemd name: dhcpd
tftp:
enabled: true
systemd name: tftp
nfs:
enabled: true
export paths:
- path: /home
export options: rw,sync
mount options: defaults
mount: true
- path: /opt
export options: ro,sync,no_root_squash
mount options: defaults
mount: false
systemd name: nfs-server
container mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
.. 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``.
Start and enable the Warewulf service
=====================================
.. code-block:: bash
# Start and enable the warewulfd service
sudo systemctl enable --now warewulfd
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.
.. 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.
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.
.. code-block:: bash
sudo wwctl container import docker://ghcr.io/warewulf/warewulf-rockylinux:8 rocky-8
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.
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
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:
.. code-block:: bash
sudo wwctl profile list -a
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.
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.
.. code-block:: bash
sudo wwctl node add n0000.cluster --ipaddr 192.168.200.100 --discoverable true
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!

199
userdocs/quickstart/el9.rst
View File

@@ -1,199 +0,0 @@
=====================================
EL9 Quickstart (Rocky Linux and RHEL)
=====================================
Install Warewulf and dependencies
=================================
.. code-block:: bash
sudo dnf groupinstall "Development Tools"
sudo dnf install epel-release
sudo dnf config-manager --set-enabled crb
sudo dnf install golang tftp-server dhcp-server nfs-utils gpgme-devel libassuan-devel
git clone https://github.com/warewulf/warewulf.git
cd warewulf
make clean defaults \
PREFIX=/usr \
BINDIR=/usr/bin \
SYSCONFDIR=/etc \
DATADIR=/usr/share \
LOCALSTATEDIR=/var/lib \
SHAREDSTATEDIR=/var/lib \
MANDIR=/usr/share/man \
INFODIR=/usr/share/info \
DOCDIR=/usr/share/doc \
SRVDIR=/var/lib \
TFTPDIR=/var/lib/tftpboot \
SYSTEMDDIR=/usr/lib/systemd/system \
BASHCOMPDIR=/etc/bash_completion.d/ \
FIREWALLDDIR=/usr/lib/firewalld/services \
WWCLIENTDIR=/warewulf
make all
sudo make install
Configure firewalld
===================
Restart firewalld to register the added service file, add the service
to the default zone, and reload.
.. code-block:: bash
sudo systemctl restart firewalld
sudo firewall-cmd --permanent --add-service warewulf
sudo firewall-cmd --permanent --add-service nfs
sudo firewall-cmd --permanent --add-service tftp
sudo firewall-cmd --reload
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:
.. code-block:: yaml
WW_INTERNAL: 45
ipaddr: 192.168.200.1
netmask: 255.255.255.0
network: 192.168.200.0
warewulf:
port: 9873
secure: false
update interval: 60
autobuild overlays: true
host overlay: true
syslog: false
dhcp:
enabled: true
range start: 192.168.200.50
range end: 192.168.200.99
systemd name: dhcpd
tftp:
enabled: true
systemd name: tftp
nfs:
enabled: true
export paths:
- path: /home
export options: rw,sync
mount options: defaults
mount: true
- path: /opt
export options: ro,sync,no_root_squash
mount options: defaults
mount: false
systemd name: nfs-server
container mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
.. 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``.
Start and enable the Warewulf service
=====================================
.. code-block:: bash
# Start and enable the warewulfd service
sudo systemctl enable --now warewulfd
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.
.. 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.
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.
.. code-block:: bash
sudo wwctl container import docker://ghcr.io/warewulf/warewulf-rockylinux:9 rocky-9
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.
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-9 "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
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:
.. code-block:: bash
sudo wwctl profile list -a
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.
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.
.. code-block:: bash
sudo wwctl node add n0000.cluster --ipaddr 192.168.200.100 --discoverable true
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!