diff --git a/userdocs/contents/containers.rst b/userdocs/contents/containers.rst index 206125be..c8b0a5d3 100644 --- a/userdocs/contents/containers.rst +++ b/userdocs/contents/containers.rst @@ -6,7 +6,7 @@ Since the inception of Warewulf over 20 years ago, Warewulf has used the model of the "Virtual Node File System" (VNFS) as a template image for the compute nodes. This is similar to a golden master image, except that the node file system exists within a directory on the -Warewulf control node (e.g. a `chroot()`). +Warewulf control node (e.g. a ``chroot()``). In hindsight, we've been using containers all along, but the buzzword just didn't exist. Over the last 5-6 years, the enterprise has created @@ -249,7 +249,7 @@ into Warewulf can be done with the following steps: Building A Container Using Podman --------------------------------- -You can also build a container using podman via a `Dockerfile`. For +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: diff --git a/userdocs/contents/initialization.rst b/userdocs/contents/initialization.rst index c0011044..4d54d13e 100644 --- a/userdocs/contents/initialization.rst +++ b/userdocs/contents/initialization.rst @@ -25,7 +25,7 @@ properly. Here are the things it will do: * **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. + 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 @@ -49,7 +49,7 @@ Systemd service: # systemctl enable --now warewulfd -You can also check and control the Warewulf service using the `wwctl` +You can also check and control the Warewulf service using the ``wwctl`` command line program as follows: .. code-block:: console diff --git a/userdocs/contents/installation.rst b/userdocs/contents/installation.rst index bd3c7bbb..be5bc598 100644 --- a/userdocs/contents/installation.rst +++ b/userdocs/contents/installation.rst @@ -2,12 +2,16 @@ Warewulf Installation ##################### -There are multiple methods to install Warewulf, this page describes the installation process of multiple methods: +There are multiple methods to install Warewulf, this page describes +the installation process of multiple methods: Binary RPMs =========== -While the Warewulf project does not build binary RPMs, you can obtain them from `CIQ `_ and use them for non-production use from their public YUM and DNF repositories at: `https://repo.ctrliq.com `_ +While the Warewulf project does not build binary RPMs, you can obtain +them from `CIQ `_ and use them for +non-production use from their public YUM and DNF repositories at: +`https://repo.ctrliq.com `_ This is the easiest method to install Warewulf and can be done as follows: @@ -16,27 +20,42 @@ This is the easiest method to install Warewulf and can be done as follows: # yum install -y https://repo.ctrliq.com/rhel/8/ciq-release.rpm # yum install -y warewulf -> note: as mentioned, these binaries are part of CIQ's commercial support offering but they can be used for non-production and testing uses. If you are interested in using these binaries for production, please contact CIQ at: `info@ctrliq.com `_. +> note: as mentioned, these binaries are part of CIQ's commercial +support offering but they can be used for non-production and testing +uses. If you are interested in using these binaries for production, +please contact CIQ at: `info@ctrliq.com `_. Compiled Source code ==================== -Before you build the Warewulf source code you will first need to install the build dependencies: +Before you build the Warewulf source code you will first need to +install the build dependencies: -* ``make``: This should be available via your Linux distribution's package manager (e.g. ``dnf install make``) -* ``go``: Golang is also available on most current Linux distributions, but if you wish to install the most recent version, you can find that here: `https://golang.org/dl/ `_ -* Depending on your Linux Distribution, you may need to install other development packages. Typically it is recommended to install the entire development group like ``dnf groupinstall "Development Tools"`` +* ``make``: This should be available via your Linux distribution's + package manager (e.g. ``dnf install make``) +* ``go``: Golang is also available on most current Linux + distributions, but if you wish to install the most recent version, + you can find that here: `https://golang.org/dl/ + `_ +* Depending on your Linux Distribution, you may need to install other + development packages. Typically it is recommended to install the + entire development group like ``dnf groupinstall "Development + Tools"`` -Once these dependencies are installed, you can obtain and build the source code as follows: +Once these dependencies are installed, you can obtain and build the +source code as follows: Release Tarball --------------- -When the Warewulf project releases stable versions, they are available via source form here: +When the Warewulf project releases stable versions, they are available +via source form here: `https://github.com/hpcng/warewulf/tags `_ -Select the version you wish to install and download the tarball to any location on the server, then follow these directions making the appropriate substitutions: +Select the version you wish to install and download the tarball to any +location on the server, then follow these directions making the +appropriate substitutions: .. code-block:: bash diff --git a/userdocs/contents/ipmi.rst b/userdocs/contents/ipmi.rst index 78d552d5..8c8fdec5 100644 --- a/userdocs/contents/ipmi.rst +++ b/userdocs/contents/ipmi.rst @@ -10,8 +10,8 @@ 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. +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 @@ -22,8 +22,8 @@ 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 which is -the same as the parameter that can be used when running `wwctl profile -set` or `wwctl node set`. +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 | @@ -175,4 +175,6 @@ Console If your node is setup to use serial over lan (SOL), Warewulf can connect a console to the node. -``sudo wwctl node console n001`` +.. code-block:: console + + # wwctl node console n001 diff --git a/userdocs/contents/overlays.rst b/userdocs/contents/overlays.rst index ff346b7e..fc53a5f8 100644 --- a/userdocs/contents/overlays.rst +++ b/userdocs/contents/overlays.rst @@ -37,7 +37,7 @@ 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 +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 @@ -47,9 +47,9 @@ network configurations for * 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 +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 @@ -58,34 +58,35 @@ which will setup 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. +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.) +*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` +* 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` + ``exports.ww`` +* the dhcpd service is configured with ``dhcpd.conf.ww`` Combining Overlays ================== @@ -94,11 +95,11 @@ 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. +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:: console @@ -155,14 +156,14 @@ 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. +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`). +(configurable in the ``warewulf.conf``). Chmod ----- @@ -201,10 +202,10 @@ Delete wwctl overlay delete [-f,--force] overlay-name [File [File ...]] -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. +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 ---- @@ -213,8 +214,8 @@ Edit wwctl overlay edit [--mode,-m MODE|--parents,p] overlay-name file 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 +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 @@ -225,8 +226,8 @@ Import 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. +the host. With the ``--noupdate`` flag you can block the rebuild of +the overlays. List ---- @@ -237,9 +238,9 @@ List 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. +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 ---- @@ -249,7 +250,7 @@ Show 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. +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/templating.rst b/userdocs/contents/templating.rst index 578b84e2..692adcbc 100644 --- a/userdocs/contents/templating.rst +++ b/userdocs/contents/templating.rst @@ -65,7 +65,7 @@ iterate over elements of an array and decrement ``i`` each loop cycle Access Tag ---------- -Acces the value of an individual tag `foo` +Acces the value of an individual tag ``foo`` .. code-block:: go @@ -78,7 +78,7 @@ Create Multiple Files --------------------- The following template will create a file called -`ifcfg-NETWORKNAME.xml` for every network present on the node +``ifcfg-NETWORKNAME.xml`` for every network present on the node .. code-block:: go @@ -196,9 +196,10 @@ 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. +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 ^^^^^ diff --git a/userdocs/quickstart/el7.rst b/userdocs/quickstart/el7.rst index 18323d5c..a82445cd 100644 --- a/userdocs/quickstart/el7.rst +++ b/userdocs/quickstart/el7.rst @@ -62,9 +62,9 @@ address of your cluster's private network interface: .. 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`. + 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 ===================================== @@ -91,7 +91,7 @@ instructions. 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 + to run ``restorecon -Rv /var/lib/tftpboot/`` if there are errors with TFTP still. Pull and build the VNFS container and kernel