diff --git a/CHANGELOG.md b/CHANGELOG.md index a0dbae63..9723f2f7 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/pkg/hostlist/hostlist_test.go b/pkg/hostlist/hostlist_test.go new file mode 100644 index 00000000..bd89d1ff --- /dev/null +++ b/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"})) +// } diff --git a/userdocs/contents/wwctl.rst b/userdocs/contents/wwctl.rst new file mode 100644 index 00000000..5fa8ee48 --- /dev/null +++ b/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`` diff --git a/userdocs/index.rst b/userdocs/index.rst index 125a5dc0..a6f342d1 100644 --- a/userdocs/index.rst +++ b/userdocs/index.rst @@ -14,6 +14,7 @@ Welcome to the Warewulf User Guide! Control Server Setup Warewulf Installation Warewulf Configuration + Controlling Warewulf (wwctl) Warewulf Initialization Container Management Kernel Management diff --git a/userdocs/quickstart/el8.rst b/userdocs/quickstart/el8.rst index 8f1d770d..b2ab3772 100644 --- a/userdocs/quickstart/el8.rst +++ b/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 diff --git a/userdocs/quickstart/el9.rst b/userdocs/quickstart/el9.rst new file mode 100644 index 00000000..02f1915f --- /dev/null +++ b/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!