warewulf/userdocs/overlays/templates.rst

.. _templates:

=========
Templates
=========

Templates (denoted in overlays with a ``.ww`` suffix) allow you to create
dynamic configuration specifically for the node that it is applied to. Templates
have access to all metadata from the node registry (``nodes.conf``) and much of
the server configuration (``warewulf.conf``), and can also reference and import
files from the server file system.

Warewulf uses the ``text/template`` engine to facilitate implementing dynamic
content. This template format is documented at `pkg.go.dev/text/template.
<https://pkg.go.dev/text/template>`_

.. note::

   When the template is rendered within a built overlay image, the ``.ww`` will
   be dropped, so ``/etc/hosts.ww`` will end up being ``/etc/hosts``.

Non-Overlay Templates
=====================

Most Warewulf templates are included in overlays, but there are a few
non-overlay templates as well.

* ``/etc/warewulf/ipxe/``: includes iPXE script templates to direct iPXE during
  the network boot process.
* ``/etc/warewulf/grub/``: includes GRUB script templates to direct GRUB during
  the network boot process.
* ``/usr/share/warewulf/bmc/``: includes templates to generate BMC control
  commands for the ``wwctl power``, ``wwctl sensor``, and ``wwctl console``
  commands.

Template functions
==================

Warewulf templates have access to a number of functions that assist in creating
more dynamic and expressive templates.

Default functions
-----------------

``text/template`` includes a number of `default functions
<https://pkg.go.dev/text/template#hdr-Functions>`_ that are available during
Warewulf template processing.

Sprig
-----

Supplementing the default functions, Warewulf templates also have access to
`Sprig functions.`_

.. _Sprig functions.: https://masterminds.github.io/sprig/

Include
-------

Reads content from the given file into the template. If the file does not begin
with ``/`` it is considered relative to ``Paths.Sysconfdir``.

.. code-block::

   {{ Include "/root/.ssh/authorized_keys" }}

IncludeFrom
-----------

Reads content from the given file from the given image into the template.

.. code-block::

   {{ IncludeFrom $.ImageName "/etc/passwd" }}

IncludeBlock
------------

Reads content from the given file into the template, stopping when the provided
abort string is found.

.. code-block::
  
   {{ IncludeBlock "/etc/hosts" "# Do not edit after this line" }}

.. _importLink:

ImportLink
----------

Causes the processed template file to become a symlink to the same target as the
referenced symlink.

.. code-block::

   {{ ImportLink "/etc/localtime" }}

basename
--------

Returns the base name of the given path.

.. code-block::

   {{- range $type, $name := $.Tftp.IpxeBinaries }}
    if option architecture-type = {{ $type }} {
        filename "/warewulf/{{ basename $name }}";
    }
   {{- end }}

file
----

Write the content from the template to the specified file name. May be specified
more than once in a template to write content to multiple files.

.. code-block::

   {{- range $devname, $netdev := .NetDevs }}
   {{- $filename := print "ifcfg-" $devname ".conf" }}
   {{ file $filename }}
   {{/* content here */}}
   {{- end }}

.. _softlink:

softlink
--------

Causes the processed template file to become a symlink to the referenced target.

.. code-block::
  
   {{ printf "%s/%s" "/usr/share/zoneinfo" .Tags.localtime | softlink }}

.. _readlink:

readlink
--------

Equivalent to ``filepath.EvalSymlinks``. Returns the target path of a named
symlink.

.. code-block::

   {{ readlink /etc/localtime }}

IgnitionJson
------------

Generates JSON suitable for use by Ignition to create partitions and file
systems, from the data stored in a node's native ``disks`` and ``filesystems``
fields.

.. code-block::

   {{ IgnitionJson }}

abort
-----

Immediately aborts processing the template and does not write a file.

.. code-block::
  
   {{ abort }}

nobackup
--------

   Disables the creation of a backup file when replacing files with the current
   template.

.. code-block::

   {{ nobackup }}

.. _UniqueField:

UniqueField
-----------

Returns a filtered version of a multi-line input string. input is expected to be
a field-separated format with one record per line (terminated by `\n`). Order of
lines is preserved, with the first matching line taking precedence.

For example, the following template snippet has been used in the ``syncuser`` overlay
to generate a combined ``/etc/passwd``.

.. code-block::

   {{
       printf "%s\n%s" 
           (IncludeFrom $.ImageName "/etc/passwd" | trim)
           (Include (printf "%s/%s" .Paths.Sysconfdir "passwd") | trim)
       | UniqueField ":" 0 | trim
   }}

SystemdEscape
-------------

Escapes a string for use in a systemd unit file.

Escape rules are documented at `systemd.unit. <https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#String%20Escaping%20for%20Inclusion%20in%20Unit%20Names>`_

SystemdEscapePath
-----------------

Escapes a path for use in a systemd unit file.

.. code-block::

   {{ file (print ($fs.path | SystemdEscapePath) ".mount") }}

Escape rules are documented at `systemd.unit. <https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#String%20Escaping%20for%20Inclusion%20in%20Unit%20Names>`_

Examples
========

Many example templates are included in the distribution overlays. The ``debug``
template also includes a ``tstruct.ww`` template that includes much of the
available metadata.

.. code-block:: shell

   wwctl overlay show debug tstruct.ww
   wwctl overlay show debug tstruct.ww --render=n1

Node-Specific Files
-------------------

Sometimes there is the need to have specific files for each cluster node which
can't be generated by a template (e.g., a per-node Kerberos keytab). You can
include these files with following template:

.. code-block::

   {{ Include (printf "/srv/%s/%s" .Id "payload") }}