From 656eeea2d6637b61712d6b3456a083de40d58744 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Tue, 21 Feb 2023 22:38:25 -0700 Subject: [PATCH] Completed a copy-editing pass of the docUpdate PR Signed-off-by: Jonathon Anderson --- userdocs/contents/configuration.rst | 19 +++++--- userdocs/contents/containers.rst | 21 ++++----- userdocs/contents/ipmi.rst | 2 +- userdocs/contents/nodeconfig.rst | 6 ++- userdocs/contents/overlays.rst | 70 ++++++++++++++--------------- userdocs/contents/profiles.rst | 6 +-- userdocs/contents/templating.rst | 9 ++-- 7 files changed, 73 insertions(+), 60 deletions(-) diff --git a/userdocs/contents/configuration.rst b/userdocs/contents/configuration.rst index 6542a4ff..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 @@ -132,7 +132,14 @@ command. defaults.conf ============= -In this file the defaults for which will present for **every** are configured. The values for the network ``dummy`` are applied to everyu network. If this file doesn't exist, following values (which is also installed as ``defaults.conf``) are used: +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 @@ -155,10 +162,12 @@ In this file the defaults for which will present for **every** are configured. T type: ethernet netmask: 255.255.255.0 -There should never be a need to change this file. +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. +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 264a85da..e1b63234 100644 --- a/userdocs/contents/containers.rst +++ b/userdocs/contents/containers.rst @@ -68,19 +68,20 @@ The above is just an example. Consideration should be done before doing it this Syncuser -------- -At import time warewulf checks if the names of the users on the host matches 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 advice 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. +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 -..code-block:: bash +A check if the users of the host and container matches can be triggered with the ``syncuser`` command. - wwctl container syncuser container-name +.. code-block:: bash -command. With the ``--write`` flag it will update the container to match the user database of the host as described above. + wwctl container syncuser container-name -Exclude -------- +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 =============================== @@ -121,7 +122,7 @@ 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`` where updated, there will be an additional check if the users are in sync as described in Syncuser section. +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 ================================ @@ -176,7 +177,7 @@ You can use these as starting points and adding any additional steps you want in 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. Follwoing steps will create a openSUSE leap container and import it to warewulf +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 diff --git a/userdocs/contents/ipmi.rst b/userdocs/contents/ipmi.rst index 725206a1..8f37cc0b 100644 --- a/userdocs/contents/ipmi.rst +++ b/userdocs/contents/ipmi.rst @@ -9,7 +9,7 @@ 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` and the write process happens at every boot of the node through the script ``/warewulf/init.d/50-ipmi`` in the **system** overlay. +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. diff --git a/userdocs/contents/nodeconfig.rst b/userdocs/contents/nodeconfig.rst index bb78ad87..3d643925 100644 --- a/userdocs/contents/nodeconfig.rst +++ b/userdocs/contents/nodeconfig.rst @@ -27,7 +27,8 @@ Creating a new node is as simple as running the following command: Adding several nodes -------------------- -Several nodes can be added with a siingle command if a node range is given. An + +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 @@ -45,6 +46,7 @@ additional IP address will incremented. So the command n004 default -- 172.16.1.14 -- (eth0) has added 4 nodes with the incremented IP addresses. + Node Names ---------- @@ -156,7 +158,7 @@ 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 actual kernel from a openSUSE Tumbleweed release +To illustrate this, we import the most recent kernel from a openSUSE Tumbleweed release .. code-block:: bash diff --git a/userdocs/contents/overlays.rst b/userdocs/contents/overlays.rst index ea8be1e7..7b5193af 100644 --- a/userdocs/contents/overlays.rst +++ b/userdocs/contents/overlays.rst @@ -6,23 +6,21 @@ 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. A node and profile can install this overlays at two times: +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: -* Before boot, these overlays are called **system overlay** or **wwinit overlay** -* After boot into the running system which are the **runtime overlay** or **generic overlay**. +* 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**. -The default profile of warewulf has this two profiles enabled. +The default profile has both a **wwinit** and a **runtime** overlay configured. - - -Overlays are compiled for each compute node individually and should not contain static files. +Overlays are compiled for each compute node individually. Defined Overlays ================ System or wwinit overlay ------------------------ -This overlay contains all the nesscesary scripts for a warewulf installation. Its available before the `systemd` 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 +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 @@ -30,6 +28,7 @@ This overlay contains all the nesscesary scripts for a warewulf installation. It 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 @@ -37,28 +36,28 @@ Before the `systemd` init is called, the overlay loops through the scripts in `/ Runtime Overlay or generic Overlay ---------------------------------- -The runtime overlay is updated by the `wwclient` service on a regular base (every minute per default). 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 recommended to use this overlay for dynamic configuration files like `slurm.conf`. +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 ------------ -In the host overlay the configuration files used for the configuration of the provision service are stored. In opposite the other overlays, it *must* have the name `host` and is stored under `/usr/share/warewulf/overlays/host/`. Existing file on the host are copied to backup file with `wwbackup` suffix at the first run. Subsequent builds of the host overlay won't overwrite the `wwbackup` file. +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.) -Following services get configuration files via templates +The following services get configuration files via the host overlay: -* ssh for which are keys created with the scrips `ssh_setup.sh` and `ssh_setup.csh` +* 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 Overlay -================= +Combining Overlays +================== -For changes in the overlays its recommended no to change them, but 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 profile is then combined with the existing **wwinit** overlay. +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 @@ -87,8 +86,9 @@ Using Overlays Warewulf includes a command group for manipulating overlays (``wwctl overlay``). With this you can add, edit, remove, change ownership, permissions, etc. -..note:: - There is now possibility to delete files with an overlay! +.. + note:: + There is now possibility to delete files with an overlay! [example needed] Build ----- @@ -97,8 +97,8 @@ Build wwctl overlay build [-H,--hosts|-N,--nodes|-o,--output directory|-O,--overlay-name] nodepattern -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 last argument. -With the `-H` flag only the host overlay is built, the `-N` flags restricts the build process to the compute nodes. Specific overlays can be selected with `-O` flag. For debugging purposes the templates can b written to a directory given via the `-o` flag. +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 Warewulf will build/update and cache overlays as needed (configurable in the `warewulf.conf`). @@ -109,8 +109,8 @@ Chmod wwctl overlay chmod overlay-name filename mode -This subcommand the permissions of a single file within an overlay. -You can use any mode format supported by the chmod command. +This subcommand changes the permissions of a single file within an +overlay. You can use any mode format supported by the chmod command. Chown ----- @@ -119,8 +119,9 @@ Chown wwctl overlay chown overlay-name filename UID [GID] -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 +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 ------ @@ -138,15 +139,15 @@ Delete wwctl overlay delete [-f,--force] overlay-name [File [File ...]] -Either the given overlay is delete (must be empty or use the `--force flag`) or the file within the overlay is deleted. With the `--parents` flag also the directory of the delete file is removed, if no other file is in the directory. +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. Edit ---- .. code-block:: bash - wwctl overlay edit [--mode,-m MODE|--parents,p]` overlay-name file + wwctl overlay edit [--mode,-m MODE|--parents,p] overlay-name file -Use this command to edit an existing or a new template in the given overlay. If a the new file a `.ww` suffix an appropriate header is added to the file. With the `--parents` flag necessary parent directories for a new file are created. +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 ------ @@ -154,23 +155,22 @@ Import wwctl overlay import [--mode,-m|--noupdate,-n] overlay-name file-name [new-file-name] -The given file is imported to the overlay to the same place as it is on the host if no new file name is given. With the `--nodeupdate` flag you can block the rebuild of the overlays +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 list [--all,a|--long,-l] [overlay-name`] + wwctl overlay list [--all,-a|--long,-l] [overlay-name] -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 and UID,GID of a file. +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. Show ---- .. 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 render 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 supressed vai the `--quiet` option. + 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 32bf382d..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: diff --git a/userdocs/contents/templating.rst b/userdocs/contents/templating.rst index 0d25d221..f728ba8f 100644 --- a/userdocs/contents/templating.rst +++ b/userdocs/contents/templating.rst @@ -146,7 +146,8 @@ With following snippet a file from a given container can be included IncludeBlock ^^^^^^^^^^^^ -Includes a file up to the line where a abort string is found. This useful e.g + +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" @@ -177,7 +178,7 @@ by warewulf. For this example the abort string is Abort ^^^^^ -Is ``{{ abort }}`` found in a template, the resulting file isn't written to the template. +If ``{{ abort }}`` is found in a template, the resulting file isn't written. Nobackup ^^^^^^^^ @@ -185,12 +186,12 @@ 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 temlate. +flag can be added to a template. Split ^^^^^ -A given string can be splitted into substrings. +A given string can be split into substrings. .. code-block:: go