From 9d124e65605a9ac106baeac19617278f3c7d464d Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Sat, 17 Feb 2024 01:12:25 -0700 Subject: [PATCH] Fix sphinx warnings Signed-off-by: Jonathon Anderson --- userdocs/conf.py | 4 +- userdocs/contents/disks.rst | 6 +- userdocs/contents/example-templates.rst | 25 --- userdocs/contents/ipmi.rst | 42 ++--- userdocs/contents/provisioning.rst | 7 +- userdocs/contents/stateless.rst | 4 +- userdocs/contents/templating.rst | 23 ++- userdocs/contributing/debugging.rst | 4 +- .../development-environment-kvm.rst | 2 +- .../development-environment-vagrant.rst | 40 +++-- .../development-environment-vbox.rst | 2 +- userdocs/index.rst | 2 +- userdocs/quickstart/el7.rst | 165 ------------------ 13 files changed, 68 insertions(+), 258 deletions(-) delete mode 100644 userdocs/contents/example-templates.rst delete mode 100644 userdocs/quickstart/el7.rst diff --git a/userdocs/conf.py b/userdocs/conf.py index 1b0f004f..419b04d9 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 = '2023, Warewulf Project Contributors' +copyright = '2024, Warewulf Project Contributors' author = 'Warewulf Project Contributors' release = 'main' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.autosectionlabel','sphinx.ext.graphviz'] +extensions = ['sphinx.ext.graphviz'] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] diff --git a/userdocs/contents/disks.rst b/userdocs/contents/disks.rst index 36152178..5f56d36b 100644 --- a/userdocs/contents/disks.rst +++ b/userdocs/contents/disks.rst @@ -1,4 +1,4 @@ -=============== +/Exa=============== Disk Management =============== @@ -61,8 +61,8 @@ required by the enabled `ww4-disks.target`. Entries in `/etc/fstab` are created with the `no_auto` option so that file systems can be easily mounted. -Example -======= +Example disk configuration +========================== The following command will create a `/scratch` file system on the node `n01` diff --git a/userdocs/contents/example-templates.rst b/userdocs/contents/example-templates.rst deleted file mode 100644 index 5188346a..00000000 --- a/userdocs/contents/example-templates.rst +++ /dev/null @@ -1,25 +0,0 @@ -================ -Useful templates -================ - -The examples directory contains some useful examples for day to day cluster admninstration. - -Genders -======= - -The file `genders.ww` can be placed as `/etc/genders.ww` which will create a genders database which containts all nodes with their profile as key. Also for every user defined 'key' the 'tah' will be added. - -.. Note: - -A arbitrary tag with a key can be added to a node with - -.. code-block:: bash - wwctl node set --tagadd key=value n01 - wwctl node set --tagadd key2='foo=baar' n01 - -will result in genders file with following line - - -.. code-block:: bash - n01: value,foo=baar - diff --git a/userdocs/contents/ipmi.rst b/userdocs/contents/ipmi.rst index 86378156..43083206 100644 --- a/userdocs/contents/ipmi.rst +++ b/userdocs/contents/ipmi.rst @@ -25,27 +25,27 @@ 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 | -+--------------------+---------+------+--------------------+---------------+ -| ``--ipmiescapechar | true | true | single character | ~ | -+--------------------+---------+------+--------------------+---------------+ ++----------------------+---------+------+--------------------+---------------+ +| 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 | ++----------------------+---------+------+--------------------+---------------+ +| ``--ipmiescapechar`` | true | true | single character | ~ | ++----------------------+---------+------+--------------------+---------------+ Reviewing Settings diff --git a/userdocs/contents/provisioning.rst b/userdocs/contents/provisioning.rst index 371ac484..58a708db 100644 --- a/userdocs/contents/provisioning.rst +++ b/userdocs/contents/provisioning.rst @@ -62,10 +62,9 @@ occur: a unified root file system #. Warewulf bootstraps the initialization of cluster node's operating system - #. File System (re)configuration - #. SELinux - #. ``wwclient`` is called as a background daemon and sleeps - until network is ready + #. File System (re)configuration + #. SELinux + #. ``wwclient`` is called as a background daemon and sleeps until network is ready #. The Warewulf bootstrap execs the container's ``/sbin/init`` #. Container: #. The container now boots exactly as any operating system would diff --git a/userdocs/contents/stateless.rst b/userdocs/contents/stateless.rst index a6e0b84c..c08c9418 100644 --- a/userdocs/contents/stateless.rst +++ b/userdocs/contents/stateless.rst @@ -43,8 +43,8 @@ available when Warewulf was created and while these tools absolutely helped, there was even more optimization to be had. Stateless computing. -Stateless Provisioning -====================== +Why Stateless Provisioning +========================== The next step past automated installs is to just skip the installation completely; boot directly into the runtime operating system without diff --git a/userdocs/contents/templating.rst b/userdocs/contents/templating.rst index 6fa4ee4e..11543834 100644 --- a/userdocs/contents/templating.rst +++ b/userdocs/contents/templating.rst @@ -19,7 +19,7 @@ Examples Comment ------- -.. code-block:: go +.. code-block:: {{ /* This comment won't show up in file, but an empty line /* }} {{ /* No empty line, line break removed at end of this line /* -}} @@ -30,7 +30,7 @@ Range iterate over elements of an array -.. code-block:: go +.. code-block:: {{ range $devname, $netdev := .NetDevs }} # netdev = {{ $netdev.Hwaddr }} @@ -41,7 +41,7 @@ Increment Variable In Loop iterate over elements of an array and increment ``i`` each loop cycle -.. code-block:: go +.. code-block:: {{ $i := 0 }} {{ range $devname, $netdev := .NetDevs }} @@ -54,7 +54,7 @@ Decrement iterate over elements of an array and decrement ``i`` each loop cycle -.. code-block:: go +.. code-block:: {{ $i := 10 }} {{ range $devname, $netdev := .NetDevs }} @@ -67,7 +67,7 @@ Access Tag Acces the value of an individual tag ``foo`` -.. code-block:: go +.. code-block:: foo: {{ index .Tags "foo" }} {{ if eq (index .Tags "foo") "baar" -}} @@ -80,7 +80,7 @@ Create Multiple Files The following template will create a file called ``ifcfg-NETWORKNAME.xml`` for every network present on the node -.. code-block:: go +.. code-block:: {{- $host := .BuildHost }} {{- $time := .BuildTime }} @@ -143,7 +143,7 @@ Include A file from the host can be include with following template -.. code-block:: go +.. code-block:: {{ Include file }} @@ -152,7 +152,7 @@ IncludeFrom With following snippet a file from a given container can be included -.. code-block:: go +.. code-block:: {{ IncludeFrom container file }} @@ -164,7 +164,7 @@ 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 +.. code-block:: {{ IncludeBlock "/etc/hosts" "# Do not edit after this line" }} # This block is autogenerated by warewulf @@ -206,7 +206,7 @@ Split A given string can be split into substrings. -.. code-block:: go +.. code-block:: {{ $x := "a:b:c" -}} {{ $y := (split $x ":") -}} @@ -220,8 +220,7 @@ Sometimes there is the need to have specific files for every node which can't be generated by a template. You can include these files with following template: -.. code-block:: go +.. code-block:: {{- $filename := print "/root/" .Id "-payload" }} {{ Include $filename }} - diff --git a/userdocs/contributing/debugging.rst b/userdocs/contributing/debugging.rst index d8d0e056..8d66d36d 100644 --- a/userdocs/contributing/debugging.rst +++ b/userdocs/contributing/debugging.rst @@ -120,8 +120,8 @@ Read about other commands available within delve using the ``help`` command. -Example -------- +Example debugging session +------------------------- .. code-block:: console diff --git a/userdocs/contributing/development-environment-kvm.rst b/userdocs/contributing/development-environment-kvm.rst index 0e6e267b..c35ce668 100644 --- a/userdocs/contributing/development-environment-kvm.rst +++ b/userdocs/contributing/development-environment-kvm.rst @@ -59,7 +59,7 @@ Turn off default network dhcp on server master1 Build and install Warewulf on wwdev =================================== -.. code-block:: bash +.. code-block:: ssh wwdev diff --git a/userdocs/contributing/development-environment-vagrant.rst b/userdocs/contributing/development-environment-vagrant.rst index b9fca8d1..73d5a928 100644 --- a/userdocs/contributing/development-environment-vagrant.rst +++ b/userdocs/contributing/development-environment-vagrant.rst @@ -1,20 +1,22 @@ -============================= +================================= Development Environment (Vagrant) -============================= +================================= Create Rocky Linux 9 virtual machine for Warewulf testbed using Vagrant + Host system requirements -===================== +======================== #. CPU supports H/W virtualization. #. KVM kernel module available and loaded. CPU H/W Virtualization support --------------------------------- +------------------------------ -Check CPU virtualization capability using following command. If your system has Intel CPU, you will see :code:`Intel VT` here, and if your system has AMD CPU, you will see :code:`AMD-V` here. +Check CPU virtualization capability using following command. +If your system has Intel CPU, you will see :code:`Intel VT` here, and if your system has AMD CPU, you will see :code:`AMD-V` here. .. code-block:: bash @@ -23,9 +25,8 @@ Check CPU virtualization capability using following command. If your system has Virtualization type: full - KVM kernel module ---------------------- +----------------- .. code-block:: bash @@ -36,10 +37,10 @@ KVM kernel module Setup development environment on Rocky Linux 9 -============================================================== +============================================== Install QEMU, libvirt ------------------------ +--------------------- .. code-block:: bash @@ -54,8 +55,9 @@ Install QEMU, libvirt # Add user to libvirt group sudo usermod -aG libvirt rocky + Install Cockpit (Optional) ------------------ +-------------------------- .. code-block:: bash @@ -65,8 +67,9 @@ Install Cockpit (Optional) # Enable and start cockpit (http://localhost:9090) sudo systemctl enable --now cockpit.socket + Install Vagrant, vagrant-libvirt plug-in and vagrant-reload plug-in ---------------------------------------------------------------------- +------------------------------------------------------------------- .. code-block:: bash @@ -82,10 +85,10 @@ Install Vagrant, vagrant-libvirt plug-in and vagrant-reload plug-in Vagrant box and Vagrantfile for Warewulf sandbox -=================================================== +================================================ Create Rocky Linux 9.2 vagrant box ------------------------------------- +---------------------------------- .. code-block:: bash @@ -109,8 +112,9 @@ Create Rocky Linux 9.2 vagrant box vagrant box add box-metadata.json + Vagrantfile ------------- +----------- .. code-block:: bash @@ -251,8 +255,9 @@ Vagrantfile end EOF + Spin up head node -=================== +================= .. code-block:: bash @@ -260,9 +265,7 @@ Spin up head node Spin up compute nodes -======================= - - +===================== .. code-block:: bash @@ -271,4 +274,3 @@ Spin up compute nodes # Wait until n0001 becomes ready vagrant up n0002 - diff --git a/userdocs/contributing/development-environment-vbox.rst b/userdocs/contributing/development-environment-vbox.rst index 39e27f91..d960e407 100644 --- a/userdocs/contributing/development-environment-vbox.rst +++ b/userdocs/contributing/development-environment-vbox.rst @@ -36,7 +36,7 @@ I have VirtualBox running on my desktop. 3. Build and install Warewulf on wwdev -.. code-block:: console +.. code-block:: # Login to wwdev VM and install @development group and go language diff --git a/userdocs/index.rst b/userdocs/index.rst index cf0f642d..0d8d7249 100644 --- a/userdocs/index.rst +++ b/userdocs/index.rst @@ -27,12 +27,12 @@ Welcome to the Warewulf User Guide! Disk Management Security Templating + dnsmasq .. toctree:: :maxdepth: 2 :caption: Quickstart - EL7 (CentOS and RHEL) EL8 (Rocky Linux and RHEL) EL9 (Rocky Linux and RHEL) openSUSE Leap and SLES 15 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!