Merge branch 'development' into patch-2

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- New documentation for the hostlist syntax. #611
+
 ### Fixed
 
 - The correct header is now displayed when `-al` flags are specified to overlay
@@ -25,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   parent folder.  #608
 - Fix kernelargs are not printing properly in node list output. #828
 - Fix build configuration on Quickstart guide #847
+- Add Quickstart guide for EL9
 
 ### Changed
 

pkg/hostlist/hostlist_test.go

@@ -0,0 +1,37 @@
+package hostlist
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+
+func Test_Single(t *testing.T) {
+	assert.Equal(t, []string{"node1"}, Expand([]string{"node1"}))
+}
+
+func Test_Multiple(t *testing.T) {
+	assert.Equal(t, []string{"node1", "node2"}, Expand([]string{"node1", "node2"}))
+}
+
+
+func Test_Range(t *testing.T) {
+	assert.Equal(t, []string{"node1", "node2"}, Expand([]string{"node[1-2]"}))
+}
+
+
+func Test_Internal_Comma(t *testing.T) {
+	assert.Equal(t, []string{"node1", "node2"}, Expand([]string{"node[1,2]"}))
+}
+
+func Test_Mixed_Range_Comma(t *testing.T) {
+	assert.Equal(t, []string{"node1", "node2", "node3"}, Expand([]string{"node[1,2-3]"}))
+}
+
+
+// not currently supported
+//
+// func Test_External_Comma(t *testing.T) {
+// 	assert.Equal(t, []string{"node1", "node2"}, Expand([]string{"node1,node2"}))
+// }

userdocs/contents/wwctl.rst

@@ -0,0 +1,33 @@
+============================
+Controlling Warewulf (wwctl)
+============================
+
+Warewulf's command-line interface is based primarily around the
+``wwctl`` command. This command has sub-commands for each major
+component of Warewulf's functionality.
+
+* ``configure`` configures external services that Warewulf depends on
+* ``container`` configures containers (node images)
+* ``kernel`` configures override kernels
+* ``node`` manages nodes in the cluster
+* ``profiles`` defines configuration which can be applied to multiple
+  nodes
+* ``overlays`` manages nodes
+* ``power`` turns nodes on and off
+* ``ssh`` provides basic parallel ssh functionality
+
+All of these subcommands (and their respective sub-subcommands) have
+built-in help with either ``wwctl help`` or ``--help``.
+
+Hostlists
+=========
+
+Many of the commands (e.g., ``wwctl node list`` support a "hostlist"
+syntax for referring to multiple nodes at once. Hostlist expressions
+support both ranges and comma-separated numerical lists.
+
+For example:
+
+* ``node[1-2]`` expands to ``node1 node2``
+* ``node[1,3]`` expands to ``node1 node3``
+* ``node[1,5-6]`` expands to ``node1 node5 node6``

userdocs/index.rst

@@ -14,6 +14,7 @@ Welcome to the Warewulf User Guide!
    Control Server Setup <contents/setup>
    Warewulf Installation <contents/installation>
    Warewulf Configuration <contents/configuration>
+   Controlling Warewulf (wwctl) <contents/wwctl>
    Warewulf Initialization <contents/initialization>
    Container Management <contents/containers>
    Kernel Management <contents/kernel>

userdocs/quickstart/el8.rst

@@ -9,7 +9,7 @@ Install Warewulf and dependencies
 
    sudo dnf groupinstall "Development Tools"
    sudo dnf install epel-release
-   sudo dnf install golang tftp-server dhcp-server nfs-utils gpgpme-devel libassuan-devel
+   sudo dnf install golang tftp-server dhcp-server nfs-utils gpgme-devel libassuan-devel
 
    git clone https://github.com/hpcng/warewulf.git
    cd warewulf

userdocs/quickstart/el9.rst

@@ -0,0 +1,185 @@
+=====================================
+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 gpgpme-devel libassuan-devel
+
+   git clone https://github.com/hpcng/warewulf.git
+   cd warewulf
+   make genconfig \
+    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
+
+   ipaddr: 192.168.200.1
+   netmask: 255.255.255.0
+   warewulf:
+     port: 9873
+     secure: false
+     update interval: 60
+   dhcp:
+     enabled: true
+     range start: 192.168.200.10
+     range end: 192.168.200.99
+     template: default
+     systemd name: dhcpd
+   tftp:
+     enabled: true
+     tftproot: /var/lib/tftpboot
+     systemd name: tftp
+   nfs:
+     systemd name: nfs-server
+     exports:
+       - /home
+       - /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``.
+
+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/hpcng/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-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!