Project

General

Profile

TemplateWriting » History » Version 81

Franklin Piat, 12/16/2015 12:19 AM
escape wiki code

1 25 Paul Kelly
{{toc}}
2 26 Paul Kelly
3 1 Justin Sherrill
h1. Templates
4
5
6
7 16 Justin Sherrill
The following functions and macros can be used within templates.  These are guaranteed to work via the safemode rendering, to ensure a template can do nothing harmful. With safemode disabled other macros may work, but are not supported at this time.
8 15 Justin Sherrill
9 30 Martin Hovmöller
To enable safemode, set "safemode_render" to "true" in Settings -> Foreman settings.  Safemode rendering prevents templates from reading and writing files on the file system or modifying application data within foreman.  
10 1 Justin Sherrill
11
12 8 Justin Sherrill
h2. Accessing Templates
13 1 Justin Sherrill
14 10 Justin Sherrill
There are two ways to render a template, based on a single host, or based on a Hostgroup.  The host or hostgroup provides all the details with which to render the template.  
15 1 Justin Sherrill
16 10 Justin Sherrill
17 8 Justin Sherrill
h3. Host-based Rendering
18
19 13 Justin Sherrill
Only a single template of each type may be rendered for a system.  Foreman determines which template to use following these rules:
20 1 Justin Sherrill
21 13 Justin Sherrill
1. Only the templates of the appropriate kind and associated with the hosts operating system are considered
22
2. If a template has a hostgroup/environment combination that matches that of the host, use this template else
23
3. If a template is associated with the environment of the host, use this template, else
24
4. Use the first template found associated with the operating system associated with the host.
25 1 Justin Sherrill
26 13 Justin Sherrill
So essentially, the hostgroup/environment combination is used first, then just the environment, and finally just the operating system of the host.
27
28
29 1 Justin Sherrill
To access a template of a certain type simply use this url:
30
31 13 Justin Sherrill
@/unattended/KIND_NAME@
32 1 Justin Sherrill
33 13 Justin Sherrill
For example:    @/unattended/provision@
34 12 Justin Sherrill
would render the provisioning template.  The host will be based on the IP Address it is accessed from.  To spoof a template simply access the url in this manner:
35
36 13 Justin Sherrill
@/unattended/provision?spoof=192.168.0.1@
37 12 Justin Sherrill
38 70 Dominic Cleal
where 192.168.0.1 is the ip address of the system you want to spoof. This allows you to view a template for a particular system from anywhere.
39 1 Justin Sherrill
40 17 Justin Sherrill
h3. Hostgroup-based rendering
41 9 Justin Sherrill
42 70 Dominic Cleal
Allows any template to be rendered for any host group.  When rendering using a hostgroup, @host is actually the hostgroup instead of a defined host. The default values for the hostgroup are used for templated values.  This means if a value is not set in the hostgroup, you may get an error when rendering the template.  To access a template using a Hostgroup to render, simply use this URL:
43 8 Justin Sherrill
44
/unattended/template/Template Name/Hostgroup Name
45 1 Justin Sherrill
46
For example, a hostgroup of name Finance, and a template named WebServerKickstart could be rendered using the url:
47 8 Justin Sherrill
48
/unattended/template/WebServerKickstart/Finance
49 70 Dominic Cleal
50
When building the default PXE template (from the Provisioning Templates page), any host group with the operating system, installation media and architecture set, plus provisioning templates with the host group set on the Associations tab will be listed at the bottom of the menu.
51 1 Justin Sherrill
52 33 Ohad Levy
h3.  PXE Menus
53 10 Justin Sherrill
54 33 Ohad Levy
Pxe Menus can be deployed to smart proxies from the Config Templates list page (/config_templates).  All provision templates will be added with each of their hostgroup combinations(see above).  For example if the template "WebServerKickstart" is associated to the Hostgroup1/Production, Hostgroup2/Production, and Hostgroup2/Testing combinations, the template would only be added twice.  Once for WebServerKickstart-Hostgroup1 and WebServerKickstart-Hostgroup2.
55 8 Justin Sherrill
56
h2. Writing templates
57 17 Justin Sherrill
58
Templates can be written using common ERB style templating.  Here's an example on using a variable/function:
59
60 81 Franklin Piat
<pre>
61 46 Tomas Edwardsson
@rootpw --iscrypted <%= root_pass %>@
62 81 Franklin Piat
</pre>
63 17 Justin Sherrill
64
Using a simple conditional:
65
66 81 Franklin Piat
<pre>
67 46 Tomas Edwardsson
@<%= "selinux --disabled\n" if @osver != 3 -%>@
68 81 Franklin Piat
</pre>
69
70 17 Justin Sherrill
This would include a line to disable selinux if the operating system version is not 3 (since Selinux isn't supported on RHEL 3)
71
72
Another way to do conditional (with if/elsif/else):
73
74 18 Justin Sherrill
<pre>
75 46 Tomas Edwardsson
<% if @osver == 5 -%>
76 17 Justin Sherrill
 echo "uses yum"
77 46 Tomas Edwardsson
<% elsif @osver == 4 -%>
78 17 Justin Sherrill
 echo "uses up2date
79 46 Tomas Edwardsson
<% else -%>
80 17 Justin Sherrill
 echo "I'm not sure"
81 46 Tomas Edwardsson
<% end -%>
82 18 Justin Sherrill
</pre>
83 8 Justin Sherrill
84
h2. Functions and macros:
85
86 1 Justin Sherrill
|_.Name|_.Description|_.Example|
87
|root_pass  |The root password configured for the system| |
88
|ks_console |A string assembled using the port and baud of the host which can be added to a kernel line | ks_console => console=ttyS1,9600 |
89 19 Justin Sherrill
|snippet(name)   | Renders the specified snippet | |
90 24 Justin Sherrill
|foreman_url(kind)| Provides the full URL to a host-rendered template of the given kind  | foreman_url("provision") =>  http://HOST/unattended/provision |
91 38 Greg Sutcliffe
|@host.name                |The (full) name of the host| |
92 46 Tomas Edwardsson
|@host.shortname           |The (short) name of the host| |
93 39 Ben Hagen
|@host.certname            |The SSL certificate name of the host| |
94 71 Lukas Zapletal
|@host.domain           |The domain of the host| |
95 1 Justin Sherrill
|@host.ip                |The IP address of the host| |
96 81 Franklin Piat
|@host.hostgroup       |The hostgroup of the host| <notextile><% if @host.hostgroup.to_s == "Base/Application Servers" -%>...<% end -%></notextile>|
97 1 Justin Sherrill
|@host.mac                |The HW address of the host| |
98
|@host.diskLayout     |The disklayout of the host (could come from the operating system)| |
99 81 Franklin Piat
|@host.ptable        |The disklayout name | <notextile><% if @host.ptable.name == 'Kickstart RHEL default' %> .. <% end %></notextile> |
100 59 Arnold Bechtoldt
|@host.puppetmaster   |The puppetmaster the host should use | |
101 1 Justin Sherrill
|@host.environment  |The environment the host should use | |
102
|@host.location    |The location of the host | |
103 34 Frank Sweetser
|@host.architecture   |The arch of the host (i.e. x86_64)| |
104 79 Franklin Piat
|@host.operatingsystem.name|The operating system name| |
105 81 Franklin Piat
|@host.operatingsystem.major |The major version of the OS| <notextile><% if @host.operatingsystem.major.to_i < 7 %> .. <% end %></notextile> |
106
|@host.operatingsystem.minor |The minor version of the OS| <notextile><% if @host.operatingsystem.minor.to_i > 2 %> .. <% end %></notextile> |
107 77 Maurice Mouw
|@host.operatingsystem.family |The OS Family (I.e. Redhat, Debian, etc.)||
108 1 Justin Sherrill
|@host.os.medium_uri(@host) |The url for provisioning (path configured in installation media)|<%= @host.os.medium_uri(@host) %> => http://mirror.os.org/os/|
109 42 Trey Dockendorf
|@host.subnet.mask |The subnet mask of the host||
110
|@host.subnet.gateway |The gateway of the host||
111
|@host.subnet.dns_primary |The primary DNS of the host||
112
|@host.subnet.dns_secondary |The secondary DNS of the host||
113 81 Franklin Piat
|@host.subnet.dhcp|Boolean that render true if a dhcp proxy is configured for this host|<notextile><% if @host.subnet.dhcp %> .. <% else %> .. <% end %></notextile>|
114 21 Justin Sherrill
|@host.url_for_boot(:kernel) |Full url to the kernel associated with this host.||
115
|@host.url_for_boot(:initrd) |Full url to the initrd image associated with this host||
116 44 Siert Z.
|@host.sp_name|The name of the BMC interface ||
117
|@host.sp_ip|The IP address of the BMC interface ||
118
|@host.sp_mac|The HW address of the BMC interface ||
119
|@host.sp_subnet|Subnet of the BMC network ||
120 73 Marek Hulán
|@host.interfaces| Contains an array of all available host interfaces including primary (see networking notes below for changes between Foreman versions) ||
121 74 Marek Hulán
|@host.primary_interface| Returns host's primary interface (1.8+) |it existed in 1.7, returning primary_interface identifier based on imported facts, 1.8+ it returns interface object |
122
|@host.provision_interface| Returns host's provision interface (1.8+) | returns interface object, see notes below for more details |
123 73 Marek Hulán
|@host.bond_interfaces| Contains an array of all bonds (1.7+) ||
124
|@host.managed_interfaces| Limit the array to managed (non-BMC nor Bond) interfaces only which are set to be managed (1.7+) ||
125 1 Justin Sherrill
|@host.interfaces_with_identifier(['eth0', 'eth1']) | Returns array of interfaces with given identifier (1.7+)||
126
|@host.interfaces.managed| Limit the array to managed (non-BMC nor Bond) interfaces only (only works if safemode_render=false) ||
127
|@host.interfaces.bmc| Limit the array to BMC (non-managed) interfaces only (only works if safemode_render=false) ||
128
|@host.interfaces.size| Number of additional interfaces (either type interface or bmc) (only works if safemode_render=false) |size=1 means a host has two interfaces on 1.7, one interface on 1.8+|
129 73 Marek Hulán
|@host.interfaces.empty|If true host does not have ant interface (only works if safemode_render=false) ||
130 72 Dominic Cleal
|@host.facts| Contains a hash of facts from Facter/Ohai etc. (1.7.2+) ||
131
|@host.facts['ipaddress']| Accessing the 'ipaddress' fact for the host (1.7.2+) ||
132
|@host.facts_hash| Contains a hash of facts from Facter/Ohai etc. (only works if safemode_render=false) ||
133 66 Dominic Cleal
|@host.facts_hash['ipaddress']| Accessing the 'ipaddress' fact for the host (only works if safemode_render=false) ||
134 81 Franklin Piat
|@host.image_build?| Returns true if the host is provisioned using an image (1.5+)| <notextile><% if @host.image_build? %></notextile> |
135
|@host.pxe_build?| Returns true if the host is provisioned using the network/PXE (1.5+)| <notextile><% if @host.pxe_build? %></notextile> |
136
|@provisioning_type|Equal to 'host' or 'hostgroup' depending on type of provisioning (1.6+)| <notextile><% if @provisioning_type == 'hostgroup' %></notextile> |
137
|@static|Boolean value to determine if the network configuration is static or dynamic|Use <notextile><%= @static ? "static" : "dynamic" %></notextile> in templates|
138 1 Justin Sherrill
|@template_name|Name of the template being rendered (1.7+)| <%= @template_name %> |
139
140
*NOTE*: For *PXELinux* templates in 0.4 or older _only_ leave off the '@host.' from the above as it is currently generated slightly different from everything else. 
141 55 Stefan Lasiewski
142 53 Dominic Cleal
*NOTE*: The interface array can be parsed this way: <pre><% @host.interfaces.each do |i| %> key is <%= i.ip %> <% end %></pre>. To print information for the first interface in the array, try something like: <pre><% myinterface = @host.interfaces.first %> IP: <%= myinterface.ip %> Netmask: <%= myinterface.subnet.mask %> Gateway: <%= myinterface.subnet.gateway %></pre>
143 1 Justin Sherrill
144
*NOTE*: Some variables can't be accessed while safemode is enabled.  Disable via safemode_render in _More > Settings_, though be aware this enables arbitrary code to be added to templates.  Some are being whitelisted via #2948.
145
146 57 Benjamin Papillon
*NOTE*: You may need to add "&static=yes" to the foreman_url to use the @static parameter in templates (see [[KickstartStatic]]).
147 1 Justin Sherrill
148
*NOTE*: A lot of networking functions changed their meaning between 1.7 and 1.8 releases. In 1.7, primary interface used to be part of host object so it was not part of '@host.interfaces'. Also it could be detected by '@host.has_primary_interface?' which was removed in 1.8. For more advanced example of using networking functions, see kickstart_networking_setup.erb provisioning template snippet.
149 74 Marek Hulán
150
*NOTE*: If you get interface object as a returning value of some function (e.g. primary_interface or interfaces.first) it is evaluated to its DNS name by default. You can easily get to other attributes of such interface, e.g. @host.primary_interface.identifier or @host.primary_interface.mac. Valid attributes include: "managed?", "subnet" (returns subnet object), "virtual?", "physical?", "mac", "ip", "identifier", "attached_to", "link", "tag", "domain" (returns domain object), "vlanid", "bond_options", "attached_devices", "mode", "attached_devices_identifiers", "primary", "provision", "alias?", "inheriting_mac" (if it's virtual it inherits the mac from attached_to device)
151
152 21 Justin Sherrill
153 78 Stephen Benjamin
154 1 Justin Sherrill
h3. Kickstart only variables (Only available for provision templates and "RedHat" Family operating systems):
155
156 21 Justin Sherrill
|_.Name|_.Description|_.Example|
157
|@osver |The OS Major Version (Same as @host.operatingsystem.major)||
158
|@arch | The architecture (same as @host.architecture.name)  ||
159 46 Tomas Edwardsson
|@mediapath | The full kickstart line to provide the url command.|@mediapath => http://file.example.com/RHEL-5-Server/U5/x86_64/os/|
160
|@epel |A command which will automatically install the correct version of the epel-release rpm.  Use full in a %post script.|@epel => "su -c 'rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/x86_64/epel-release-5-4.noarch.rpm'"|
161 1 Justin Sherrill
|@dynamic |true if the parition table being used is a %pre script (has #Dynamic as the first line of the table)|<% if @dynamic -%>|
162 21 Justin Sherrill
163 6 Justin Sherrill
h3. Preseed attributes (Only available for provision templates and "Debian" Family operating systems)::
164 1 Justin Sherrill
165
|_.Name|_.Description|_.Example|
166
|@preseed_path |||
167 27 Alexander Rusa
|@preseed_server |||
168
169
h3. Host- or Hostgroup parameters
170 35 David M.
171
@host.params['parameter_name']
172 45 Mikael Fridh
173 75 Dominic Cleal
If you need to test if a parameter contains a boolean true/false value, there are two helpers that will help:
174
175
    @host.param_true?('parameter_name')
176
@host.param_false?('parameter_name')
177
178
These check the parameter is a true/false/on/off/1/0 string.
179
180 36 Adrian Bridgett
Hint: For Foreman older than 1.0 you have to disable Safemode-Rendering in More->Settings.
181 41 Ohad Levy
182
h3. Compute Resource Specific functions
183
184
see [[Compute Resources#Templates]]
185 36 Adrian Bridgett
186
h3. Settings
187
188
Setting.setting_name
189
190 1 Justin Sherrill
You will need to disable Safemode-Rendering in More->Settings.
191 78 Stephen Benjamin
192
h2. Ruby methods
193
194
The most common methods on Ruby's core classes should be allowed (split, gsub, to_i, blank?, etc).  A full list is in the Safemode Gem: https://github.com/svenfuchs/safemode/blob/master/lib/safemode/core_jails.rb#L33
195
196
To avoid turning off safemode, consider alternative ways of writing your ruby code. For example this would not work in the default Jail:
197
198
<pre>
199
@host.ip.rpartition('.')[-1]
200
</pre>
201
202
203
But this does:
204
205
<pre>
206
@host.ip.split('.').last
207
</pre>