Templates

https://warewulf.org/docs/main/overlays/templates.html

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.

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 documentation Templates can include documentation to be included in the output of wwctl overlay info.

{{/* wwdoc: Your documentation text */}} Template variables Overlay templates have access to a number of variables that provide information about the server configuration, the node being provisioned, and all nodes in the cluster. An example of the variables available, and their use, is included with Warewulf in the tstruct.ww template of the debug overlay.

Variables used in an overlay template can be documented by adding a comment to the template with the form {{/* .My.Var: Your help text */}}. Variable help text defined in a comment replaces that variable’s default help text in the output of wwctl overlay info.

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 that are available during Warewulf template processing.

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

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

{{ Include “/root/.ssh/authorized_keys” }} IncludeFrom Reads content from the given file from the given image into the template.

{{ IncludeFrom $.ImageName “/etc/passwd” }} IncludeBlock Reads content from the given file into the template, stopping when the provided abort string is found.

{{ IncludeBlock “/etc/hosts” “# Do not edit after this line” }} ImportLink Causes the processed template file to become a symlink to the same target as the referenced symlink.

{{ ImportLink “/etc/localtime” }} When paired with file, ImportLink can create multiple symlinks from a single template.

{{ file “/tmp/test-link1”}} {{ softlink “/tmp/test-target1” }} {{ file “/tmp/test-link2”}} {{ softlink “/tmp/test-target2” }} basename Returns the base name of the given path.

{{- 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.

{{- range $devname, $netdev := .NetDevs }} {{- $filename := print “ifcfg-“ $devname “.conf” }} {{ file $filename }} {{/* content here */}} {{- end }} softlink Causes the processed template file to become a symlink to the referenced target.

{{ printf “%s/%s” “/usr/share/zoneinfo” .Tags.localtime | softlink }} When paired with file, softlink can create multiple symlinks from a single template.

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

{{ 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.

{{ IgnitionJson }} abort Immediately aborts processing the template and does not write a file.

{{ abort }} nobackup Disables the creation of a backup file when replacing files with the current template.

{{ nobackup }} 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.

{{ 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.

SystemdEscapePath Escapes a path for use in a systemd unit file.

{{ file (print ($fs.path | SystemdEscapePath) “.mount”) }} Escape rules are documented at systemd.unit.

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.

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: