diff --git a/userdocs/conf.py b/userdocs/conf.py index 573a75e7..3420cbe6 100644 --- a/userdocs/conf.py +++ b/userdocs/conf.py @@ -7,14 +7,14 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'Warewulf User Guide' -copyright = '2022, Warewulf Project Contributors' +copyright = '2023, Warewulf Project Contributors' author = 'Warewulf Project Contributors' release = 'development' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = ['sphinx.ext.autosectionlabel'] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] @@ -45,4 +45,4 @@ html_context = { html_logo = 'logo.png' html_favicon = 'favicon.png' -html_show_copyright = False \ No newline at end of file +html_show_copyright = False diff --git a/userdocs/contents/configuration.rst b/userdocs/contents/configuration.rst index 2fc2f04d..e486211a 100644 --- a/userdocs/contents/configuration.rst +++ b/userdocs/contents/configuration.rst @@ -113,7 +113,7 @@ explained as follows: nodes.conf ========== -The ``nodes.conf`` is the primary database file for all compute +The ``nodes.conf`` file is the primary database file for all compute nodes. It is a flat text YAML configuration file that is managed by the ``wwctl`` command, but some sites manage the compute nodes and infrastructure via configuration management. This file being flat text @@ -129,8 +129,45 @@ command. first time you attempt to run ``wwctl``, this file will be generated if it does not exist already. +defaults.conf +============= + +The ``defaults.conf`` file configures default values used when none +are specified. For example: if a node does not have a "runtime +overlay" specified, the respective value from ``defaultnode`` is +used. If a network device does not specify a "device," the device +value of the ``dummy`` device is used. + +If ``defaults.conf`` does not exist, the following values are used as +compiled into Warewulf at build-time: + +.. code-block:: yaml + + -- + defaultnode: + runtime overlay: + - generic + system overlay: + - wwinit + kernel: + args: quiet crashkernel=no vga=791 net.naming-scheme=v238 + init: /sbin/init + root: initramfs + ipxe template: default + profiles: + - default + network devices: + dummy: + device: eth0 + type: ethernet + netmask: 255.255.255.0 + +There should never be a need to change this file: all site-local +parameters should be specified using either nodes or profiles. + Directories =========== -The ``/etc/warewulf/ipxe/`` contains *text/templates* that are used by -the Warewulf configuration process to configure the ``ipxe`` service. \ No newline at end of file +The ``/etc/warewulf/ipxe/`` directory contains *text/templates* that +are used by the Warewulf configuration process to configure the +``ipxe`` service. diff --git a/userdocs/contents/containers.rst b/userdocs/contents/containers.rst index 4b186545..e1b63234 100644 --- a/userdocs/contents/containers.rst +++ b/userdocs/contents/containers.rst @@ -13,7 +13,7 @@ It is important to understand that Warewulf is not running a container runtime o Container Tools =============== -There are different container managment tools available. Docker is probably the most recognizable one in the enterprise. Podman is another one that is gaining traction on the RHEL platforms. In HPC, Singularity is the most utilized container management tool. You can use any of these to create and manage the containers to be later imported into Warewulf. +There are different container managment tools available. Docker is probably the most recognizable one in the enterprise. Podman is another one that is gaining traction on the RHEL platforms. In HPC, Apptainer is the most utilized container management tool. You can use any of these to create and manage the containers to be later imported into Warewulf. Importing From A Registry ========================= @@ -65,6 +65,24 @@ Here is an example: The above is just an example. Consideration should be done before doing it this way if you are in a security sensitive environment or shared environments. You would not want these showing up in bash history or logs. +Syncuser +-------- + +At import time warewulf checks if the names of the users on the host match the users and UIDs/GIDs in the imported container. If there is mismatch, the import command will print out a warning. +By setting the ``--syncuser`` flag you advise warewulf to try to syncronize the users from the host to the container, which means that ``/etc/passwd`` and ``/etc/group`` of the imported container are updated and all the files belonning to these UIDs and GIDs will also be updated. + +A check if the users of the host and container matches can be triggered with the ``syncuser`` command. + +.. code-block:: bash + + wwctl container syncuser container-name + +With the ``--write`` flag it will update the container to match the user database of the host as described above. + +.. code-block:: bash + + wwctl container syncuser --write container-name + Listing All Imported Containers =============================== @@ -104,6 +122,8 @@ You can also ``--bind`` directories from your host into the container when using When the command completes, if anything within the container changed, the container will be rebuilt into a bootable static object automatically. +If the files ``/etc/passwd`` or ``/etc/group`` were updated, there will be an additional check to confirm if the users are in sync as described in `Syncuser`_ section. + Creating Containers From Scratch ================================ @@ -140,16 +160,27 @@ Once you have created and modified your new ``chroot()``, you can import it into sudo wwctl container import /tmp/newroot containername -Building A Container Using Singularity +Building A Container Using Apptainer -------------------------------------- -Singularity, a container platform for HPC and performance intensive applications, can also be used to create node containers for Warewulf. There are several Singularity container recipes in the ``containers/Singularity/`` directory and can be found on GitHub at `https://github.com/hpcng/warewulf/tree/main/containers/Singularity `_. +Apptainer, a container platform for HPC and performance intensive applications, can also be used to create node containers for Warewulf. There are several Apptainer container recipes in the ``containers/Apptainer/`` directory and can be found on GitHub at `https://github.com/hpcng/warewulf/tree/main/containers/Apptainer `_. -You can use these as starting points and adding any additional steps you want in the ``%post`` section of the recipe file. Once you've done that, installing Singularity, building a container sandbox and importing into Warewulf can be done with the following steps: +You can use these as starting points and adding any additional steps you want in the ``%post`` section of the recipe file. Once you've done that, installing Apptainer, building a container sandbox and importing into Warewulf can be done with the following steps: .. code-block:: bash sudo yum install epel-release - sudo yum install singularity - sudo singularity build --sandbox /tmp/newroot /path/to/Singularity/recipe.def - sudo wwctl container import /tmp/newroot containername \ No newline at end of file + sudo yum install Apptainer + sudo Apptainer build --sandbox /tmp/newroot /path/to/Apptainer/recipe.def + sudo wwctl container import /tmp/newroot containername + +Building A Container Using Podman +-------------------------------------- + +You can also build a container using podman via a `Dockerfile`. For this step the container must be exported to a tar archive, which then can be imported to warewulf. The following steps will create an openSUSE Leap container and import it to Warewulf: + +.. code-block:: bash + + $ sudo podman build -f containers/Docker/openSUSE/Containerfile --tag leap-ww + $ sudo podman save localhost/leap-ww:latest -o ~/leap-ww.tar + $ sudo wwctl container import file://root/leap-ww.tar leap-ww diff --git a/userdocs/contents/initialization.rst b/userdocs/contents/initialization.rst index 6a9cc197..c4a103f9 100644 --- a/userdocs/contents/initialization.rst +++ b/userdocs/contents/initialization.rst @@ -13,10 +13,10 @@ Once Warewulf has been installed and configured, it is ready to be initialized a This command will configure the system for Warewulf to run properly. Here are the things it will do: -* **dhcp**: (re)Write the DHCP configuration and restart the service from the configured template in ``/etc/warewulf/dhcp/`` and enable the system service. -* **hostfile**: Update the system's /etc/hosts file based on the template ``/etc/warewulf/hosts.tmpl``. -* **nfs**: Configure the NFS server on the control node as well as the ``/etc/fstab`` in the system overlay based on the configuration in ``/etc/warewulf/warewulf.conf`` and enable the system service. -* **ssh**: Create the appropriate host keys (stored in ``/etc/warewulf/keys/``) and user keys for passwordless ``ssh`` into the nodes. +* **dhcp**: (re)Write the DHCP configuration and restart the service from the **host** template under ``/etc/dhcpd.conf.ww`` and enable the system service. +* **hostfile**: Update the system's /etc/hosts file based on the **host** template ``/etc/hosts.ww``. +* **nfs**: Configure the NFS server on the control node as well as the ``/etc/fstab`` in the system overlay based on the configuration in ``/etc/warewulf/warewulf.conf`` and enable the system service. Also the file `/etc/exports.ww` from the **host** template is installed. +* **ssh**: Create the appropriate host keys (stored in ``/etc/warewulf/keys/``) and user keys for passwordless ``ssh`` into the nodes. Addionally the shell profiles ``/etc/profile.d/ssh_setup.csh`` and ``/etc/profile.d/ssh_setup.sh`` are installed. * **tftp**: Write the appropriate binary PXE/iPXE blobs to the TFTP root directory and enable the system service. This command will quickly setup the system services per the Warewulf configuration. Watch this output carefully for errors and resolve them in the configuration portion of this manual. diff --git a/userdocs/contents/ipmi.rst b/userdocs/contents/ipmi.rst index fe1a7a94..8f37cc0b 100644 --- a/userdocs/contents/ipmi.rst +++ b/userdocs/contents/ipmi.rst @@ -9,21 +9,32 @@ IPMI Settings The common settings for the IPMI interfaces on all nodes can be set on a Profile level. The only field that would need to be assigned to each individual node would be the IP address. +The settings are only written to the IPMI interface if ``--ipmiwrite`` is set to `true`. The write process happens at every boot of the node through the script ``/warewulf/init.d/50-ipmi`` in the **system** overlay. + If an individual node has different settings, you can set the IPMI settings for that specific node, overriding the default settings. -Here is a table outlining the fields on a Profile and Node level, along with the parameters that can be used when running ``wwctl profile set`` or ``wwctl node set``. +Here is a table outlining the fields on a Profile and Node which is the same as the parameter that can be used when running `wwctl profile set` or `wwctl node set`. + ++----------------+---------+------+--------------------+---------------+ +| Parameter | Profile | Node | Valid Values | Default Value | ++================+=========+======+====================+===============+ +| --ipmiaddr | false | true | | | ++----------------+---------+------+--------------------+---------------+ +| --ipminetmask | true | true | | | ++----------------+---------+------+--------------------+---------------+ +| --ipmiport | true | true | | 623 | ++----------------+---------+------+--------------------+---------------+ +| --ipmigateway | true | true | | | ++----------------+---------+------+--------------------+---------------+ +| --ipmiuser | true | true | | | ++----------------+---------+------+--------------------+---------------+ +| --ipmipass | true | true | | | ++----------------+---------+------+--------------------+---------------+ +| --ipmiinterface| true | true | 'lan' or 'lanplus' | lan | ++----------------+---------+------+--------------------+---------------+ +| --ipmiwrite | true | true | true or false | false | ++----------------+---------+------+--------------------+---------------+ -============= =============== ======== ======= ================== ============= -Field Parameter Profile Node Valid Values Default Value -============= =============== ======== ======= ================== ============= -IpmiIpaddr --ipmi X -IpmiNetmask --ipminetmask X X -IpmiPort --ipmiport X X 623 -IpmiGateway --ipmigateway X X -IpmiUserName --ipmiuser X X -IpmiPassword --ipmipass X X -IpmiInterface --ipmiinterface X X 'lan' or 'lanplus' lan -============= =============== ======== ======= ================== ============= Reviewing Settings ================== @@ -35,67 +46,72 @@ Profile View .. code-block:: bash - $ sudo wwctl profile list -a + $ sudo wwctl profile list -a + PROFILE FIELD PROFILE VALUE + ===================================================================================== + default Id -- default + default comment -- This profile is automatically included for each node + default cluster -- -- + default container -- sle-micro-5.3 + default ipxe -- -- + default runtime -- -- + default wwinit -- -- + default root -- -- + default discoverable -- -- + default init -- -- + default asset -- -- + default profile -- -- + default default:type -- -- + default default:onboot -- -- + default default:netdev -- -- + default default:hwaddr -- -- + default default:ipaddr -- -- + default default:ipaddr6 -- -- + default default:netmask -- -- + default default:gateway -- -- + default default:mtu -- -- + default default:primary -- -- - ################################################################################ - PROFILE NAME FIELD VALUE - default Id default - default Comment This profile is automatically included for each node - default Cluster -- - default Container rocky - default Kernel 4.18.0-348.2.1.el8_5.x86_64 - default KernelArgs -- - default Init -- - default Root -- - default RuntimeOverlay -- - default SystemOverlay -- - default Ipxe -- - default IpmiNetmask 255.255.255.0 - default IpmiPort -- - default IpmiGateway 192.168.99.1 - default IpmiUserName admin - default IpmiInterface lanplus - default eth0:IPADDR -- - default eth0:NETMASK 255.255.240.0 - default eth0:GATEWAY 10.1.96.6 - default eth0:HWADDR -- - default eth0:TYPE -- - default eth0:DEFAULT false Node View --------- - .. code-block:: bash - $ sudo wwctl node list node0001 -a - - ################################################################################ - NODE FIELD PROFILE VALUE - node0001 Id -- node0001 - node0001 Comment default This profile is automatically included for each node - node0001 Cluster -- -- - node0001 Profiles -- default - node0001 Discoverable -- false - node0001 Container default rocky - node0001 Kernel default 4.18.0-348.2.1.el8_5.x86_64 - node0001 KernelArgs -- (quiet crashkernel=no vga=791 rootfstype=rootfs) - node0001 RuntimeOverlay -- (default) - node0001 SystemOverlay -- (default) - node0001 Ipxe -- (default) - node0001 Init -- (/sbin/init) - node0001 Root -- (initramfs) - node0001 IpmiIpaddr -- 192.168.99.10 - node0001 IpmiNetmask -- 255.255.255.0 - node0001 IpmiPort -- -- - node0001 IpmiGateway -- 192.168.99.1 - node0001 IpmiUserName default admin - node0001 IpmiInterface default lanplus - node0001 eth0:HWADDR -- 52:54:00:1a:08:60 - node0001 eth0:IPADDR -- 192.168.100.152 - node0001 eth0:NETMASK default 255.255.255.0 - node0001 eth0:GATEWAY default 192.168.100.1 - node0001 eth0:TYPE -- -- - node0001 eth0:DEFAULT -- false + $ sudo wwctl node list -a n001 + NODE FIELD PROFILE VALUE + ===================================================================================== + n001 Id -- n001 + n001 comment default This profile is automatically included for each node + n001 cluster -- -- + n001 container default sle-micro-5.3 + n001 ipxe -- (default) + n001 runtime -- (generic) + n001 wwinit -- (wwinit) + n001 root -- (initramfs) + n001 discoverable -- -- + n001 init -- (/sbin/init) + n001 asset -- -- + n001 kerneloverride -- tw + n001 kernelargs -- (quiet crashkernel=no vga=791 net.naming-scheme=v238) + n001 ipmiaddr -- -- + n001 ipminetmask -- -- + n001 ipmiport -- -- + n001 ipmigateway -- -- + n001 ipmiuser -- -- + n001 ipmipass -- -- + n001 ipmiinterface -- -- + n001 ipmiwrite -- -- + n001 profile -- default + n001 default:type -- (ethernet) + n001 default:onboot -- -- + n001 default:netdev -- eth0 + n001 default:hwaddr -- 11:22:33:44:55:66 + n001 default:ipaddr -- 10.0.2.1 + n001 default:ipaddr6 -- -- + n001 default:netmask -- 255.255.252.0 + n001 default:gateway -- -- + n001 default:mtu -- -- + n001 default:primary -- true Review Only IPMI Settings ------------------------- @@ -105,12 +121,13 @@ The above views show you everything that is set on a Profile or Node level. That .. code-block:: bash $ sudo wwctl node list -i + NODE NAME IPMI IPADDR IPMI PORT IPMI USERNAME IPMI INTERFACE + ================================================================================================== + n001 192.168.1.11 -- hwadmin -- + n002 192.168.1.12 -- hwadmin -- + n003 192.168.1.13 -- hwadmin -- + n004 192.168.1.14 -- hwadmin -- - NODE NAME IPMI IPADDR IPMI PORT IPMI USERNAME IPMI PASSWORD IPMI INTERFACE - ============================================================================================================ - node0001 192.168.99.10 -- admin supersecret lanplus - node0002 192.168.99.11 -- admin supersecret lanplus - node0003 192.168.99.12 -- admin supersecret lanplus Power Commands ============== @@ -142,4 +159,4 @@ Console If your node is setup to use serial over lan (SOL), Warewulf can connect a console to the node. -``sudo wwctl node console node0001`` \ No newline at end of file +``sudo wwctl node console n001`` diff --git a/userdocs/contents/nodeconfig.rst b/userdocs/contents/nodeconfig.rst index bd751dc2..3d643925 100644 --- a/userdocs/contents/nodeconfig.rst +++ b/userdocs/contents/nodeconfig.rst @@ -22,8 +22,30 @@ Creating a new node is as simple as running the following command: .. code-block:: bash - $ sudo wwctl node add n0000 - Added node: n0000 + $ sudo wwctl node add n001 -I 172.16.1.11 + Added node: n001 + +Adding several nodes +-------------------- + +Several nodes can be added with a single command if a node range is given. An +additional IP address will incremented. So the command + +.. code-block:: bash + + $ sudo wwctl node add n00[2-4] -I 172.16.1.12 + Added node: n002 + Added node: n003 + Added node: n004 + $ wwctl node list -n n00[1-4] + NODE NAME NAME HWADDR IPADDR GATEWAY DEVICE + ========================================================================================== + n001 default -- 172.16.1.11 -- (eth0) + n002 default -- 172.16.1.12 -- (eth0) + n003 default -- 172.16.1.13 -- (eth0) + n004 default -- 172.16.1.14 -- (eth0) + +has added 4 nodes with the incremented IP addresses. Node Names ---------- @@ -32,7 +54,7 @@ For small clusters, you can use simple names (e.g. ``n0000``); but for larger, more complicated clusters that are comprised of multiple clusters and roles it is highly recommended to use node names that include a cluster descriptor. In Warewulf, this is generally done by -using a domain name (e.g. ``n0000.cluster01``). Warewulf will +using a domain name (e.g. ``n001.cluster01``). Warewulf will automatically assume that the domain is the equivalent of the cluster name. @@ -49,39 +71,53 @@ their attributes as follows: .. code-block:: bash + NODE NAME PROFILES NETWORK + ================================================================================ + n001 default + $ sudo wwctl node list - NODE NAME PROFILES NETWORK - ================================================================================ - n0000 default You can also see the node's full attribute list by specifying the ``-a`` option (all): .. code-block:: bash - $ sudo wwctl node list -a - ################################################################################ - NODE FIELD PROFILE VALUE - n0000 Id -- n0000 - n0000 Comment default This profile is automatically included for each node - n0000 Cluster -- -- - n0000 Profiles -- default - n0000 Discoverable -- false - n0000 Container -- -- - n0000 KernelOverride -- -- - n0000 KernelArgs -- (quiet crashkernel=no vga=791 rootfstype=rootfs) - n0000 RuntimeOverlay -- (default) - n0000 SystemOverlay -- (default) - n0000 Ipxe -- (default) - n0000 Init -- (/sbin/init) - n0000 Root -- (initramfs) - n0000 IpmiIpaddr -- -- - n0000 IpmiNetmask -- -- - n0000 IpmiPort -- -- - n0000 IpmiGateway -- -- - n0000 IpmiUserName -- -- - n0000 IpmiInterface -- -- - n0000 IpmiWrite -- -- + $ sudo wwctl node list -a n001 + NODE FIELD PROFILE VALUE + ===================================================================================== + n001 Id -- n001 + n001 comment default This profile is automatically included for each node + n001 cluster -- -- + n001 container default sle-micro-5.3 + n001 ipxe -- (default) + n001 runtime -- (generic) + n001 wwinit -- (wwinit) + n001 root -- (initramfs) + n001 discoverable -- -- + n001 init -- (/sbin/init) + n001 asset -- -- + n001 kerneloverride -- -- + n001 kernelargs -- (quiet crashkernel=no vga=791 net.naming-scheme=v238) + n001 ipmiaddr -- -- + n001 ipminetmask -- -- + n001 ipmiport -- -- + n001 ipmigateway -- -- + n001 ipmiuser -- -- + n001 ipmipass -- -- + n001 ipmiinterface -- -- + n001 ipmiwrite -- -- + n001 profile -- default + n001 default:type -- (ethernet) + n001 default:onboot -- -- + n001 default:netdev -- (eth0) + n001 default:hwaddr -- -- + n001 default:ipaddr -- 172.16.1.11 + n001 default:ipaddr6 -- -- + n001 default:netmask -- (255.255.255.0) + n001 default:gateway -- -- + n001 default:mtu -- -- + n001 default:primary -- true + .. note:: The attribute values in parenthesis are default values and can @@ -106,14 +142,14 @@ Configuring the Node's Container Image .. code-block:: bash - $ sudo wwctl node set --container rocky-8 n0000 + $ sudo wwctl node set --container rocky-8 n001 Are you sure you want to modify 1 nodes(s): y -And you can check that the container name is set for ``n0000``: +And you can check that the container name is set for ``n001``: .. code-block:: bash - $ sudo wwctl node list -a n0000 | grep Container + $ sudo wwctl node list -a n001 | grep Container n0000 Container -- rocky-8 Configuring the Node's Kernel @@ -122,14 +158,22 @@ Configuring the Node's Kernel While the recommended method for assigning a kernel in 4.3 and beyond is to include it in the container / node image, a kernel can still be specified as an override at the node or profile. +To illustrate this, we import the most recent kernel from a openSUSE Tumbleweed release + .. code-block:: bash - $ sudo wwctl node set --kerneloverride $(uname -r) n0000 - Are you sure you want to modify 1 nodes(s): y + $ sudo wwctl container import docker://registry.opensuse.org/science/warewulf/tumbleweed/containerfile/kernel:latest tw + $ sudo wwctl kernel import -DC tw + $ sudo wwctl kernel list + KERNEL NAME KERNEL VERSION NODES + tw 6.1.10-1-default 0 + $ sudo wwctl node set --kerneloverride tw n001 + Are you sure you want to modify 1 nodes(s): y + + $ sudo wwctl node list -a n001 | grep kerneloverride + n001 kerneloverride -- tw - $ sudo wwctl node list -a n0000 | grep KernelOverride - n0000 KernelOverride -- 4.18.0-305.3.1.el8_4.x86_64 Configuring the Node's Network ------------------------------ @@ -139,7 +183,7 @@ provide the network information as follows: .. code-block:: bash - $ sudo wwctl node set --netdev eth0 --hwaddr 11:22:33:44:55:66 --ipaddr 10.0.2.1 --netmask 255.255.252.0 n0000 + $ sudo wwctl node set --netdev eth0 --hwaddr 11:22:33:44:55:66 --ipaddr 10.0.2.1 --netmask 255.255.252.0 n001 Are you sure you want to modify 1 nodes(s): y You can now see that the node contains configuration attributes for @@ -147,35 +191,46 @@ container, kernel, and network: .. code-block:: bash - $ sudo wwctl node list -a n0000 - ################################################################################ - NODE FIELD PROFILE VALUE - n0000 Id -- n0000 - n0000 Comment default This profile is automatically included for each node - n0000 Cluster -- -- - n0000 Profiles -- default - n0000 Discoverable -- false - n0000 Container -- rocky-8 - n0000 Kernel -- 4.18.0-305.3.1.el8_4.x86_64 - n0000 KernelArgs -- (quiet crashkernel=no vga=791 rootfstype=rootfs) - n0000 RuntimeOverlay -- (default) - n0000 SystemOverlay -- (default) - n0000 Ipxe -- (default) - n0000 Init -- (/sbin/init) - n0000 Root -- (initramfs) - n0000 IpmiIpaddr -- -- - n0000 IpmiNetmask -- -- - n0000 IpmiPort -- -- - n0000 IpmiGateway -- -- - n0000 IpmiUserName -- -- - n0000 IpmiInterface -- -- - n0000 default:DEVICE -- eth0 - n0000 default:HWADDR -- 11:22:33:44:55:66 - n0000 default:IPADDR -- 10.0.2.1 - n0000 default:NETMASK -- 255.255.252.0 - n0000 default:GATEWAY -- -- - n0000 default:TYPE -- -- - n0000 default:DEFAULT -- false + $ sudo wwctl node list -a n001 + ===================================================================================== + n001 Id -- n001 + n001 comment default This profile is automatically included for each node + n001 cluster -- -- + n001 container default sle-micro-5.3 + n001 ipxe -- (default) + n001 runtime -- (generic) + n001 wwinit -- (wwinit) + n001 root -- (initramfs) + n001 discoverable -- -- + n001 init -- (/sbin/init) + n001 asset -- -- + n001 kerneloverride -- tw + n001 kernelargs -- (quiet crashkernel=no vga=791 net.naming-scheme=v238) + n001 ipmiaddr -- -- + n001 ipminetmask -- -- + n001 ipmiport -- -- + n001 ipmigateway -- -- + n001 ipmiuser -- -- + n001 ipmipass -- -- + n001 ipmiinterface -- -- + n001 ipmiwrite -- -- + n001 profile -- default + n001 default:type -- (ethernet) + n001 default:onboot -- -- + n001 default:netdev -- eth0 + n001 default:hwaddr -- 11:22:33:44:55:66 + n001 default:ipaddr -- 10.0.2.1 + n001 default:ipaddr6 -- -- + n001 default:netmask -- 255.255.252.0 + n001 default:gateway -- -- + n001 default:mtu -- -- + n001 default:primary -- true + + $ sudo wwctl node set --cluster cluster01 n001 + Are you sure you want to modify 1 nodes(s): y + + $ sudo wwctl node list -a n001 | grep cluster + n001 cluster -- cluster01 Un-setting Node Attributes ========================== @@ -183,20 +238,13 @@ Un-setting Node Attributes If you wish to ``unset`` a particular value, set the value to ``UNDEF``. For example: -.. code-block:: bash - - $ sudo wwctl node set --cluster cluster01 n0000 - Are you sure you want to modify 1 nodes(s): y - - $ sudo wwctl node list -a n0000 | grep Cluster - n0000 Cluster -- cluster01 And to unset this configuration attribute: .. code-block:: bash - $ sudo wwctl node set --cluster UNDEF n0000 + $ sudo wwctl node set --cluster UNDEF n001 Are you sure you want to modify 1 nodes(s): y - $ sudo wwctl node list -a n0000 | grep Cluster - n0000 Cluster -- -- \ No newline at end of file + $ sudo wwctl node list -a n001 | grep Cluster + n001 Cluster -- -- diff --git a/userdocs/contents/overlays.rst b/userdocs/contents/overlays.rst index 5ebe7829..7b5193af 100644 --- a/userdocs/contents/overlays.rst +++ b/userdocs/contents/overlays.rst @@ -6,23 +6,69 @@ So at this point, we have discussed how Warewulf is designed to scalably provisi While some of this can be managed by services like DHCP, and other bits by configuration management, which can absolutely be done with Warewulf and many people choose to do, these are heavy-weight solutions to a simple problem to solve. -Warewulf solves this with overlays and uses overlays in different ways through the provisioning process. Two of these overlays are exposed to the users, the **system overlay** and the **runtime overlay**. +Warewulf solves this with overlays and uses overlays in different ways through the provisioning process. A node or profile can configure an overlay in two different ways: -.. note:: - Another overlay that isn't directly exposed is the **kmods overlay** which contains all of the kernel modules to match the configured kernel. Because this overlay is used "behind the scenes" it is outside the scope of this document. +* An overlay can be configured to run during boot as part of the ``wwinit`` process. These overlays are called **system overlay** or **wwinit overlays**. +* An overlay can be configured to run periodically while the system is running. These overlays are called **runtime overlays** or **generic overlays**. -System Overlay -============== +The default profile has both a **wwinit** and a **runtime** overlay configured. -The System Overlay is used by the core of Warewulf to setup the environment on the node necessary for provisioning. The default system overlay is called ``wwinit``. Generally speaking, it will not be necessary to make changes to this overlay, but it is possible to change or configure this overlay to meet site specific needs if necessary. +Overlays are compiled for each compute node individually. -Runtime Overlay -=============== +Defined Overlays +================ -The Runtime Overlay is the overlay that is responsible for most of the typical system administration configurations. Here you will make changes necessary to support your operating system as well as application configurations. +System or wwinit overlay +------------------------ +This overlay contains all the nesscesary scripts to provision a Warewulf node. It is available before the `systemd` or other init is called and contains all configurations which are needed to bring up the compute node. It is not updated during run time. Besides the network configurations for +* wicked +* NetworkManager +* EL legacy network scripts + +it also contains udev rules, which will set the interface name of the first network device to `eth0`. +Before the `systemd` init is called, the overlay loops through the scripts in `/wwinit/warwulf/init.d/*` which will setup + +* Ipmi +* wwclient +* selinux + +Runtime Overlay or generic Overlay +---------------------------------- + +The runtime overlay is updated by the `wwclient` service on a regular basis (by default, once per minute). In the standard configuration it includes updates for `/etc/passwd`, `/etc/group` and `/etc/hosts`. Additionally the `authorized_keys` file of the root user is updated. +It is recommended to use this overlay for dynamic configuration files like `slurm.conf`. Once the system is provisioned and booted, the ``wwclient`` program (which is provisioned as part of the ``wwinit`` system overlay) will continuously update the node with updates in the runtime overlay. +Host Overlay +------------ + +Configuration files used for the configuration of the Warewulf host / server are stored in the **host** overlay. Unlike other overlays, it *must* have the name `host`. Existing files on the host are copied to backup files with a `wwbackup` suffix at the first run. (Subsequent use of the host overlay won't overwrite existing `wwbackup` files.) + +The following services get configuration files via the host overlay: + +* ssh keys are created with the scrips `ssh_setup.sh` and `ssh_setup.csh` +* hosts entries are created by manipulating `/etc/hosts` with the template `hosts.ww` +* nfs kernel server receives its exports from the template `exports.ww` +* the dhcpd service is configured with `dhcpd.conf.ww` + +Combining Overlays +================== + +When changing the overlays, it is recommended not to change them, but to add the changed files to a new overlay and combine them in the configuration. This is possible as the configuration fields for the **wwinit** and **runtime** overlays are lists and can contain several overlays. +As an example for this, we will overwrite the `/etc/issue` file from the **wwinit** overlay. +For this we will create a new overlay called welcome and import the file `/etc/issue` from the host to it. This overlay is then combined with the existing **wwinit** overlay. + +..code-block:: bash + $ wwctl overlay create welcome + $ wwctl overlay mkdir welcome /etc + $ wwctl overlay import welcome /etc/issue + $ wwctl profile set default --wwinit=wwinit,welcome + ? Are you sure you want to modify 1 profile(s)? [y/N] y + $ wwctl profile list default -a |grep welcome + default SystemOverlay wwinit,welcome + + Templates ========= @@ -40,102 +86,91 @@ Using Overlays Warewulf includes a command group for manipulating overlays (``wwctl overlay``). With this you can add, edit, remove, change ownership, permissions, etc. -The general syntax is as follows: +.. + note:: + There is now possibility to delete files with an overlay! [example needed] + +Build +----- .. code-block:: bash - wwctl overlay [action] [overlay name] ... + wwctl overlay build [-H,--hosts|-N,--nodes|-o,--output directory|-O,--overlay-name] nodepattern -* **action**: the overlay subcommand you are invoking -* **overlay name**: the name of the overlay in question within a given type -* **...**: additional arguments are action specific +Without any arguments the command will interpret the templates for all overlays for every compute node and also all the templates in the host overlay. For every overlay of the compute nodes a gzip compressed cpio archive is created. The range of the nodes can be restricted as the last argument. +With the `-H` flag only the host overlay is built. With the `-N` flag only compute node overlays are built. Specific overlays can be selected with `-O` flag. For debugging purposes the templates can be written to a directory given via the `-o` flag. -By default there is one overlay in each of the system and runtime overlay types. Both overlays are called "default". To say it differently, there are two default overlays, one is a system overlay and one is a runtime overlay. +By default Warewulf will build/update and cache overlays as needed (configurable in the `warewulf.conf`). -Viewing the Files Within an Overlay -=================================== - -Overlays can be viewed with the command ``wwctl overlay list``. You can see the files within an overlay by adding the ``-a`` or ``-l`` options as follows: +Chmod +----- .. code-block:: bash - $ sudo wwctl overlay list -l generic - PERM MODE UID GID OVERLAY FILE PATH - -rwxr-xr-x 0 0 generic /etc/ - -rw-r--r-- 0 0 generic /etc/group.ww - -rw-r--r-- 0 0 generic /etc/hosts.ww - -rw-r--r-- 0 0 generic /etc/passwd.ww - -rwxr-xr-x 0 0 generic /root/ - -rwxr-xr-x 0 0 generic /root/.ssh/ - -rw-r--r-- 0 0 generic /root/.ssh/authorized_keys.ww + wwctl overlay chmod overlay-name filename mode -Creating a New File Within an Overlay -===================================== +This subcommand changes the permissions of a single file within an +overlay. You can use any mode format supported by the chmod command. -Just like any file on the system, you can create and edit a file at the same time. So to do that, you simple ``edit`` a new file as follows: +Chown +----- .. code-block:: bash - $ sudo wwctl overlay edit [overlay name] [file path] + wwctl overlay chown overlay-name filename UID [GID] -For example: +With this command you can change the ownership of a file within a +given overlay to the user specified by UID. Optionally, it will also +change group ownership to GID. + +Create +------ .. code-block:: bash - $ sudo wwctl overlay edit generic /etc/testfile + wwctl overlay create overlay-name -and you can validate that the file is there with the ``list`` command: +This command creates a new empty overlay with the given name. + +Delete +------ .. code-block:: bash - $ sudo wwctl overlay list generic -l - PERM MODE UID GID RUNTIME-OVERLAY FILE PATH - -rwxr-xr-x 0 0 generic /etc/ - -rw-r--r-- 0 0 generic /etc/group.ww - -rw-r--r-- 0 0 generic /etc/hosts.ww - -rw-r--r-- 0 0 generic /etc/passwd.ww - -rwxr-xr-x 0 0 generic /etc/testfile - -rwxr-xr-x 0 0 generic /root/ - -rwxr-xr-x 0 0 generic /root/.ssh/ - -rw-r--r-- 0 0 generic /root/.ssh/authorized_keys.ww + wwctl overlay delete [-f,--force] overlay-name [File [File ...]] -.. note:: - To create a template file, simply name the file with the suffix ``.ww``. This suffix will tell Warewulf that the file should be parsed by the templating engine and written into the overlay with the suffix stripped off. +Either the given overlay is deleted (must be empty or use the `--force flag`) or the specified file within the overlay is deleted. With the `--parents` flag the directory of the deleted file is also removed if no other file is in the directory. -Building Overlays -================= +Edit +---- +.. code-block:: bash -By default Warewulf will build/update and cache overlays as needed (configurable in the ``warewulf.conf``). + wwctl overlay edit [--mode,-m MODE|--parents,p] overlay-name file -You can however build overlays by hand, and in some cases this will be advantageous (like if you are freshly booting thousands of compute nodes in parallel). The command to do that is: +Use this command to edit an existing or a new file in the given overlay. If a the new file ends with a `.ww` suffix an example template header is added to the file. With the `--parents` flag necessary parent directories for a new file are created. + +Import +------ +.. code-block:: bash + + wwctl overlay import [--mode,-m|--noupdate,-n] overlay-name file-name [new-file-name] + +The given file is imported to the overlay. If no new-file-name is given, the file will be placed in the overlay at the same path as on the host. With the `--noupdate` flag you can block the rebuild of the overlays. + +List +---- .. code-block:: bash - # wwctl overlay build n00[00-10] - Building overlays for n0000: [wwinit, generic] - Building overlays for n0001: [wwinit, generic] - Building overlays for n0002: [wwinit, generic] - Building overlays for n0003: [wwinit, generic] - Building overlays for n0004: [wwinit, generic] - Building overlays for n0005: [wwinit, generic] - Building overlays for n0006: [wwinit, generic] - Building overlays for n0007: [wwinit, generic] - Building overlays for n0008: [wwinit, generic] - Building overlays for n0009: [wwinit, generic] - Building overlays for n0010: [wwinit, generic] + wwctl overlay list [--all,-a|--long,-l] [overlay-name] -Other Overlay Actions -===================== +With this command all existing overlays and files in them can be listed. Without any option only the overlay names and their number of files are listed. With the `--all` switch also the every file is shown. The `--long` option will also display the permissions, UID, and GID of each file. -Warewulf includes a number of overlay action commands to interact with the overlays in a programmatic and controlled manner. All of the commands use very similar usage structure and work as the above examples do. A summary of all of the overlay actions are as follows: +Show +---- -* **build**: (Re)build an overlay -* **chmod**: Change file permissions within an overlay -* **chown**: Change file ownership within an overlay -* **create**: Initialize a new Overlay -* **delete**: Delete Warewulf Overlay or files -* **edit**: Edit/Create a file within a Warewulf Overlay -* **import**: Import a file into a Warewulf Overlay -* **list**: List Warewulf Overlays and files -* **mkdir**: Create a new directory within an Overlay -* **show**: Show (cat) a file within a Warewulf Overlay \ No newline at end of file +.. code-block:: bash + + wwctl overlay show [--quiet,-q|--render,-r nodename] overlay-name file + +The content of the file for the given overlay is displayed with this command. With the `--render` option a template is rendered as it will be rendered for the given node. The node name is a mandatory argument to the `--render` flag. Additional information for the file can be suppressed with the `--quiet` option. diff --git a/userdocs/contents/profiles.rst b/userdocs/contents/profiles.rst index 2e9250d4..66c00a85 100644 --- a/userdocs/contents/profiles.rst +++ b/userdocs/contents/profiles.rst @@ -1,13 +1,13 @@ -############# +============= Node Profiles -############# +============= Profiles provide a way to scalably group node configurations together. Instead of redundant configurations for each node, you can put that into a profile and the nodes will inherit these configurations. This is very handy if you have groups of node specific customizations. For example, a few hundred nodes that are running a particular container or kernel, and another group of nodes that are running a different kernel or container. Any node configuration attributes can be applied to a profile, but there are always going to be some node configurations which must be specific to a node, like a network HW/MAC address or an IP address. An Introduction To Profiles -============================== +=========================== Every new node is automatically added to a profile called ``default``. You can view the configuration attributes of this profile by using the ``wwctl profile list`` command. Like the ``wwctl node list`` command, this will provide a summary, but you can see **all** configuration attributes by using the ``--all`` or ``-a`` flag as follows: @@ -75,7 +75,7 @@ Now that we've created a new profile, let's create a configuration attribute in .. code-block:: bash $ sudo wwctl profile set --cluster cluster01 test_profile - ? Are you sure you want to modify 1 profile(s)? [y/N] y█ + ? Are you sure you want to modify 1 profile(s)? [y/N] y $ sudo wwctl profile list -a test_profile | grep Cluster test_profile Cluster cluster01 @@ -159,4 +159,4 @@ There are a lot of ways to use profiles to facilitate the management of large cl But if you do wish to use profiles, the best way to use them is to manage "fixed" configurations of groups of cluster nodes. For example, if you have multiple sub-clusters in your cluster, it might be advantageous to have a ``cluster_name`` profile which includes things like network configurations, and/or a specific kernel, container, boot arguments, etc. -Node specific information, like HW/MAC addresses and IP addresses should always be put in a node configuration rather than a profile configuration. \ No newline at end of file +Node specific information, like HW/MAC addresses and IP addresses should always be put in a node configuration rather than a profile configuration. diff --git a/userdocs/contents/templating.rst b/userdocs/contents/templating.rst index e1ca2cd2..f728ba8f 100644 --- a/userdocs/contents/templating.rst +++ b/userdocs/contents/templating.rst @@ -10,8 +10,15 @@ In Warewulf, you can find templates both for the provisioning services (e.g. ``/ Examples ======== +Comment +------- +.. code-block:: go -range + {{ /* This comment won't show up in file, but an empty line /* }} + {{ /* No empty line, line break removed at end of this line /* -}} + {{- /* No empty line, line break removed at front of this line /* }} + +Range ----- iterate over elements of an array @@ -22,7 +29,7 @@ iterate over elements of an array # netdev = {{ $netdev.Hwaddr }} {{ end }} -increment variable in loop +Increment Variable In Loop ^^^^^^^^^^^^^^^^^^^^^^^^^^ iterate over elements of an array and increment ``i`` each loop cycle @@ -35,7 +42,7 @@ iterate over elements of an array and increment ``i`` each loop cycle {{ $i = inc $i }} {{ end }} -decrement +Decrement ^^^^^^^^^ iterate over elements of an array and decrement ``i`` each loop cycle @@ -46,4 +53,148 @@ iterate over elements of an array and decrement ``i`` each loop cycle {{ range $devname, $netdev := .NetDevs }} # netdev{{$i}} = {{ $netdev.Hwaddr }} {{ $i = dec $i }} - {{ end }} \ No newline at end of file + {{ end }} + +Access Tag +---------- +Acces the value of an individual tag `foo` + +.. code-block:: go + + foo: {{ index .Tags "foo" }} + {{ if eq (index .Tags "foo") "baar" -}} + foo: {{ index .Tags "foo" }} + {{ end -}} + +Create Multiple Files +--------------------- +The following template will create a file called `ifcfg-NETWORKNAME.xml` for every network present on the node + +.. code-block:: go + + {{- $host := .BuildHost }} + {{- $time := .BuildTime }} + {{- $source := .BuildSource }} + {{range $devname, $netdev := .NetDevs -}} + {{- $filename := print "ifcfg-" $devname ".xml" }} + {{- file $filename }} + + + {{$netdev.Device}} + {{ if $netdev.Type -}} + {{ $netdev.Type }} + {{ end -}} + + boot + + + + + true + true + + +
+ {{$netdev.IpCIDR}} +
+ {{ if $netdev.Gateway -}} + + + {{$netdev.Gateway}} + + + {{ end -}} + + + true + prefer-public + false + + {{ if $netdev.Ipaddr6 -}} + +
+ {{ $netdev.Ipaddr6 }} +
+ + {{ end -}} + + {{ end -}} + + +Special Commands +---------------- +Include +^^^^^^^ +A file from the host can be include with following template + +.. code-block:: go + + {{ Include file }} + +IncludeFrom +^^^^^^^^^^^ +With following snippet a file from a given container can be included + +.. code-block:: go + + {{ IncludeFrom container file }} + +IncludeBlock +^^^^^^^^^^^^ + +Includes a file up to the line where a abort string is found. This is useful, e.g., +for the hosts file, which can have local modifications which are not controlled +by warewulf. For this example the abort string is +"# Do not edit after this line" + +.. code-block:: go + + {{ IncludeBlock "/etc/hosts" "# Do not edit after this line" }} + # This block is autogenerated by warewulf + # Host: {{.BuildHost}} + # Time: {{.BuildTime}} + # Source: {{.BuildSource}} + + + # Warewulf Server + {{$.Ipaddr}} warewulf {{$.BuildHost}} + + {{- range $node := $.AllNodes}} {{/* for each node */}} + # Entry for {{$node.Id.Get}} + {{- range $devname, $netdev := $node.NetDevs}} {{/* for each network device on the node */}} + {{- if $netdev.Ipaddr.Defined}} {{/* if we have an ip address on this network device */}} + {{- /* emit the node name as hostname if this is the primary */}} + {{$netdev.Ipaddr.Get}} {{$node.Id.Get}}-{{$devname}} + {{- if $netdev.Device.Defined}} {{$node.Id.Get}}-{{$netdev.Device.Get}}{{end}} + {{- if $netdev.Primary.GetB}} {{$node.Id.Get}}{{end}} + {{- end}} {{/* end if ip */}} + {{- end}} {{/* end for each network device */}} + {{- end}} {{/* end for each node */}} + +Abort +^^^^^ +If ``{{ abort }}`` is found in a template, the resulting file isn't written. + +Nobackup +^^^^^^^^ + +If a file exists on the target, a backup file is written with the suffix +`.wwbackup`. This only happens for the `host` overlay, as e.g. the `/etc/hosts` +exists on the host. If this is not the intended behavior, the ``{{ nobackup }}`` +flag can be added to a template. + +Split +^^^^^ + +A given string can be split into substrings. + +.. code-block:: go + + {{ $x := "a:b:c" -}} + {{ $y := (split $x ":") -}} + {{ range $y }} {{.}} {{ end }}