kelvin/warewulf
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Fix sphinx warnings

Browse Source 
Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2024-02-17 01:12:25 -07:00
parent 72c1b868ad
commit 9d124e6560
13 changed files with 68 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
userdocs/conf.py
View File

@@ -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']

6
userdocs/contents/disks.rst
View File

@@ -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`

25
userdocs/contents/example-templates.rst
View File

@@ -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

42
userdocs/contents/ipmi.rst
View File

@@ -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

7
userdocs/contents/provisioning.rst
View File

@@ -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

4
userdocs/contents/stateless.rst
View File

@@ -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

23
userdocs/contents/templating.rst
View File

@@ -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 }}

4
userdocs/contributing/debugging.rst
View File

@@ -120,8 +120,8 @@ Read about other commands available within delve using the ``help``
command.
Example
-------
Example debugging session
-------------------------
.. code-block:: console

2
userdocs/contributing/development-environment-kvm.rst
View File

@@ -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

40
userdocs/contributing/development-environment-vagrant.rst
View File

@@ -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

2
userdocs/contributing/development-environment-vbox.rst
View File

@@ -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

2
userdocs/index.rst
View File

@@ -27,12 +27,12 @@ Welcome to the Warewulf User Guide!
Disk Management <contents/disks>
Security <contents/security>
Templating <contents/templating>
dnsmasq <contents/dnsmasq>
.. toctree::
:maxdepth: 2
:caption: Quickstart
EL7 (CentOS and RHEL) <quickstart/el7>
EL8 (Rocky Linux and RHEL) <quickstart/el8>
EL9 (Rocky Linux and RHEL) <quickstart/el9>
openSUSE Leap and SLES 15 <quickstart/suse15>

165
userdocs/quickstart/el7.rst
View File

@@ -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!