Appendix A. Template Writing Reference

Embedded Ruby (ERB) is a tool for generating text files based on templates that combine plain text with Ruby code. Red Hat Satellite uses ERB syntax in provisioning templates (Creating Provisioning Templates in the Provisioning Guide), remote execution job templates (Chapter 4, Running Jobs on Hosts), templates for partition tables (Creating Partition Tables in the Provisioning Guide), Smart Variables (Configuring Smart Variables in the Puppet Guide), and Smart Class Parameters (Configuring Smart Class Parameters in the Puppet Guide). This section provides an overview of Satellite specific functions and variables that can be used in ERB templates along with some usage examples. Note that the default templates provided by Red Hat Satellite (Hosts > Provisioning templates, Hosts > Job templates) also provide a good source of ERB syntax examples.

When provisioning a host or running a remote job, the code in the ERB is executed and the variables are replaced with the host specific values. This process is referred to as rendering. The Satellite Server has the safemode rendering option enabled by default, which prevents any harmful code being executed from templates.

A.1. Writing ERB Templates

The following points summarize the ERB syntax:

  • <% %> – marks enclosing Ruby code within the ERB template. The code is executed when the template is rendered. It can contain Ruby control flow structures as well as Satellite specific functions and variables. For example:

    <% if @host.operatingsystem.family == "Redhat" && @host.operatingsystem.major.to_i > 6 %>
    systemctl <%= input("action") %> <%= input("service") %>
    <% else %>
    service <%= input("service") %> <%= input("action") %>
    <% end -%>
  • <%= %> – the code output is inserted into the template. This is useful for variable substitution, for example:

    echo <%= @host.name %>
  • <% -%>, <%= -%> – by default, a newline character is inserted after a Ruby block if it is closed at the end of a line. To suppress this behavior, modify the enclosing mark. For example, the following template:

    curl <%= @host.ip -%>
    /mydir

    is rendered the same as:

    curl <%= @host.ip %>/mydir

    In practice, this is used to reduce the number of lines in rendered templates (where Ruby syntax permits).

  • <%# %> – marks enclosing a comment that will be ignored during template rendering:

    <%# A comment %>

A.2. Troubleshooting ERB Templates

The Satellite web UI provides two ways to verify the template rendering for a specific host:

  • Directly in the template editor – when editing a template (under Hosts > Partition tables, Hosts > Provisioning templates, or Hosts > Job templates), on the Template tab click Preview and select a host from the drop-down menu. The template then renders in the text field using the selected host’s parameters. Preview failures can help to identify issues in your template.
  • At the host’s details page – select a host at Hosts > All hosts and click the Templates tab to list templates associated with the host. Select Review from the drop-down menu next to the selected template to view it’s rendered version.

A.3. Satellite Specific Functions and Variables

This section lists Satellite specific functions and variables for ERB templates. Note that some of them can be used in any kind of template, others are limited, for example job templates accept only @host variables and variables from Table A.4, “Kickstart Specific Variables” are only applicable in Kickstart templates.

You can use the functions listed in the following table across all kinds of templates.

Table A.1. Generic Functions

NameDescription

indent(n)

Indents the block of code by n spaces, useful when using a snippet template that is not indented.

foreman_url(kind)

Returns the full URL to host-rendered templates of the given kind. For example, templates of the "provision" type usually reside at http://HOST/unattended/provision.

snippet(name)

Renders the specified snippet template. Useful for nesting provisioning templates.

snippets(file)

Renders the specified snippet found in the Foreman database, attempts to load it from the unattended/snippets/ directory if it is not found in the database.

snippet_if_exists(name)

Renders the specified snippet, skips if no snippet with the specified name is found.

Example A.1. Using the snippet and indent Functions

The following syntax imports the subscription_manager_registration snippet to the template and indents it by four spaces:

<%= indent 4 do
snippet 'subscription_manager_registration'
end %>

The following functions can be used in job templates. See Section 4.4.4, “Creating Advanced Templates” for usage examples.

Table A.2. Functions Specific to Job Templates

NameDescription

input(input_name)

Returns the value of the specified input on the job execution.

render_template(name, parameters)

Renders the specified template, similar to the generic snippet() function but enables passing arguments to the template.

The following variables enable using host data within templates.

Table A.3. Host Specific Variables and Functions

NameDescription

@host.architecture

The architecture of the host.

@host.bond_interfaces

Returns an array of all bonded interfaces. See Note.

@host.capabilities

The method of system provisioning, can be either build (for example kickstart) or image.

@host.certname

The SSL certificate name of the host.

@host.diskLayout

The disk layout of the host. Can be inherited from the operating system.

@host.domain

The domain of the host.

@host.environment

The Puppet environment of the host.

@host.facts

Returns a Ruby hash of facts from Facter. For example to access the 'ipaddress' fact from the output, specify @host.facts['ipaddress'].

@host.grub_pass

Returns the host’s GRUB password.

@host.hostgroup

The host group of the host.

host_enc['parameters']

Returns a Ruby hash containing information on host parameters. For example, use host_enc['parameters']['lifecycle_environment'] to get the life cycle environment of a host.

@host.image_build?

Returns true if the host is provisioned using an image.

@host.interfaces

Contains an array of all available host interfaces including the primary interface. See Note.

@host.interfaces_with_identifier('IDs')

Returns array of interfaces with given identifier. You can pass an array of multiple identifiers as an input, for example @host.interfaces_with_identifier(['eth0', 'eth1']). See Note.

@host.ip

The IP address of the host.

@host.location

The location of the host.

@host.mac

The MAC address of the host.

@host.managed_interfaces

Returns an array of managed interfaces (excluding BMC and bonded interfaces). See Note.

@host.medium

The assigned operating system installation medium.

@host.name

The full name of the host.

@host.operatingsystem.family

The operating system family.

@host.operatingsystem.major

The major version number of the assigned operating system.

@host.operatingsystem.minor

The minor version number of the assigned operating system.

@host.operatingsystem.name

The assigned operating system name.

@host.operatingsystem.boot_files_uri(@host.medium,@host.architecture)

Full path to the kernel and initrd, returns an array.

@host.os.medium_uri(@host)

The URI used for provisioning (path configured in installation media).

host_param('parameter_name')

Returns the value of the specified host parameter.

host_param_false?('parameter_name')

Returns false if the specified host parameter evaluates to false.

host_param_true?('parameter_name')

Returns true if the specified host parameter evaluates to true.

@host.primary_interface

Returns the primary interface of the host.

@host.provider

The compute resource provider.

@host.provision_interface

Returns the provisioning interface of the host. Returns an interface object.

@host.ptable

The partition table name.

@host.puppetmaster

The Puppet master the host should use.

@host.pxe_build?

Returns true if the host is provisioned using the network or PXE.

@host.shortname

The short name of the host.

@host.sp_ip

The IP address of the BMC interface.

@host.sp_mac

The MAC address of the BMC interface.

@host.sp_name

The name of the BMC interface.

@host.sp_subnet

The subnet of the BMC network.

@host.subnet.dhcp

Returns true if a DHCP proxy is configured for this host.

@host.subnet.dns_primary

The primary DNS server of the host.

@host.subnet.dns_secondary

The secondary DNS server of the host.

@host.subnet.gateway

The gateway of the host.

@host.subnet.mask

The subnet mask of the host.

@host.url_for_boot(:initrd)

Full path to the initrd image associated with this host. Not recommended, as it does not interpolate variables.

@host.url_for_boot(:kernel)

Full path to the kernel associated with this host. Not recommended, as it does not interpolate variables, prefer boot_files_uri.

@provisioning_type

Equals to 'host' or 'hostgroup' depending on type of provisioning.

@static

Returns true if the network configuration is static.

@template_name

Name of the template being rendered.

grub_pass

Returns the GRUB password wrapped in md5pass argument, that is --md5pass=#{@host.grub_pass}.

ks_console

Returns a string assembled using the port and the baud rate of the host which can be added to a kernel line. For example console=ttyS1,9600.

root_pass

Returns the root password configured for the system.

Note

Host variables related to network interfaces, such as @host.interfaces or @host.bond_interfaces return interface data grouped in an array. To extract a parameter value of a specific interface, use Ruby methods to parse the array. For example, to get information about the first interface from an array and use it in a kickstart template:

<% myinterface = @host.interfaces.first %>
IPADDR="<%= myinterface.ip %>"
NETMASK="<%= myinterface.subnet.mask %>"
GATEWAY="<%= myinterface.subnet.gateway %>"

You can iterate over the interface array, for example to extract an array of interface names use:

<% ifnames = []
@host.interfaces.each do |i|
  ifnames.push(i.name)
end %>

Example A.2. Using Host Specific Variables

The following example checks if the host has Puppet and the Puppetlabs repository enabled:

<%
pm_set = @host.puppetmaster.empty? ? false : true
puppet_enabled = pm_set || host_param_true?('force-puppet')
puppetlabs_enabled = host_param_true?('enable-puppetlabs-repo')
%>

The following example shows how to capture the minor and major version of the host’s operating system, which can be used for package related decisions:

<%
os_major = @host.operatingsystem.major.to_i
os_minor = @host.operatingsystem.minor.to_i
%>

<% if ((os_minor < 2) && (os_major < 14)) -%>
...
<% end -%>

The following example imports the 'kickstart_networking_setup' snippet if the host’s subnet has the DHCP boot mode enabled:

<% subnet = @host.subnet %>
<% if subnet.respond_to?(:dhcp_boot_mode?) -%>
<%= snippet 'kickstart_networking_setup' %>
<% end -%>

The majority of common Ruby methods can be applied on host specific variables. For example, to extract the last segment of the host’s IP address, you can use:

<% @host.ip.split('.').last %>

The following variables are designed to be used within kickstart provisioning templates.

Table A.4. Kickstart Specific Variables

NameDescription

@arch

The host architecture name, same as @host.architecture.name.

@dynamic

Returns true if the partition table being used is a %pre script (has the #Dynamic option as the first line of the table).

@epel

A command which will automatically install the correct version of the epel-release rpm. Use in a %post script.

@mediapath

The full kickstart line to provide the URL command.

@osver

The operating system major version number, same as @host.operatingsystem.major.