From 67d5292141466026de58fdd5b207d9bb0a3d2118 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Sat, 9 Mar 2024 22:59:26 -0700 Subject: [PATCH] Merge Enterprise Linux quickstarts - Closes #394, #401, #977 Signed-off-by: Jonathon Anderson --- userdocs/index.rst | 4 +- userdocs/quickstart/el.rst | 197 +++++++++++++++++++++++++++++++++++ userdocs/quickstart/el7.rst | 165 ------------------------------ userdocs/quickstart/el8.rst | 199 ------------------------------------ userdocs/quickstart/el9.rst | 199 ------------------------------------ 5 files changed, 198 insertions(+), 566 deletions(-) create mode 100644 userdocs/quickstart/el.rst delete mode 100644 userdocs/quickstart/el7.rst delete mode 100644 userdocs/quickstart/el8.rst delete mode 100644 userdocs/quickstart/el9.rst diff --git a/userdocs/index.rst b/userdocs/index.rst index 351d8782..a94f4700 100644 --- a/userdocs/index.rst +++ b/userdocs/index.rst @@ -33,9 +33,7 @@ Welcome to the Warewulf User Guide! :maxdepth: 2 :caption: Quickstart - EL7 (Rocky Linux and RHEL) - EL8 (Rocky Linux and RHEL) - EL9 (Rocky Linux and RHEL) + Enterprise Linux (Rocky Linux, CentOS, and RHEL) openSUSE Leap and SLES 15 Debian 12 diff --git a/userdocs/quickstart/el.rst b/userdocs/quickstart/el.rst new file mode 100644 index 00000000..f45d9658 --- /dev/null +++ b/userdocs/quickstart/el.rst @@ -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! diff --git a/userdocs/quickstart/el7.rst b/userdocs/quickstart/el7.rst deleted file mode 100644 index 5f29fc82..00000000 --- a/userdocs/quickstart/el7.rst +++ /dev/null @@ -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! diff --git a/userdocs/quickstart/el8.rst b/userdocs/quickstart/el8.rst deleted file mode 100644 index 5a9f2eb2..00000000 --- a/userdocs/quickstart/el8.rst +++ /dev/null @@ -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! diff --git a/userdocs/quickstart/el9.rst b/userdocs/quickstart/el9.rst deleted file mode 100644 index dddd8f3f..00000000 --- a/userdocs/quickstart/el9.rst +++ /dev/null @@ -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!