From 82cdd1398723857fa5db440cb746b02d68efeec7 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Thu, 20 Apr 2023 06:05:24 -0600 Subject: [PATCH 1/4] Documentation and tests for hostlist syntax Added this to a new top-level page for wwctl Closes #611 Signed-off-by: Jonathon Anderson --- CHANGELOG.md | 4 ++++ pkg/hostlist/hostlist_test.go | 37 +++++++++++++++++++++++++++++++++++ userdocs/contents/wwctl.rst | 33 +++++++++++++++++++++++++++++++ userdocs/index.rst | 1 + 4 files changed, 75 insertions(+) create mode 100644 pkg/hostlist/hostlist_test.go create mode 100644 userdocs/contents/wwctl.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 71dc96e8..2481d695 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 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 From 55778b9d51527d3307ee2b76eabc1d4dbcf26e38 Mon Sep 17 00:00:00 2001 From: Yoshiaki Senda Date: Thu, 8 Jun 2023 12:24:19 +0900 Subject: [PATCH 2/4] fix typo fix package name to gpgme-devel --- userdocs/quickstart/el8.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/userdocs/quickstart/el8.rst b/userdocs/quickstart/el8.rst index acd0a848..b77ab8d8 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 From 5e30205b63f54b1c0a65cebcebd0385e208f788a Mon Sep 17 00:00:00 2001 From: Yoshiaki Senda Date: Fri, 9 Jun 2023 00:59:37 +0900 Subject: [PATCH 3/4] Quickstart Guide for EL9 Quickstart Guide for EL9 --- userdocs/quickstart/el9.rst | 185 ++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 userdocs/quickstart/el9.rst 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! From a7b4abd444c9de36ba5f137a1ad78da43cd17c01 Mon Sep 17 00:00:00 2001 From: Yoshiaki Senda Date: Fri, 9 Jun 2023 01:02:17 +0900 Subject: [PATCH 4/4] Update CHANGELOG.md Add Quickstart guide for EL9 --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 71dc96e8..af737168 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add `--parents` option to `overlay import` subcommand to create necessary parent folder. #608 - Fix kernelargs are not printing properly in node list output. #828 +- Add Quickstart guide for EL9 ### Changed