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 5, 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.
Name | Description |
---|---|
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 5.4.4, “Creating Advanced Templates” for usage examples.
Name | Description |
---|---|
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.
Name | Description |
---|---|
@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.info['parameters'] | Returns a Ruby hash containing information on host parameters. For example, use @host.info['parameters']['lifecycle_environment'] to get the life cycle environment of a host. |
@host.image_build? |
Returns |
@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_false?(name) |
Returns |
@host.param_true?(name) |
Returns |
@host.params['parameter_name'] | Returns the value of specified parameters. |
@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 |
@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 |
@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 |
@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. |
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.
Name | Description |
---|---|
@arch | The host architecture name, same as @host.architecture.name. |
@dynamic |
Returns |
@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. |