The configuration part of a configuration template is a text document that is very similar to a regular device configuration.
When creating a configuration template, the recommended approach is to start from a configuration backup taken from a sample
device that is already configured with the features and settings that the template should enable. A configuration template
differs from a device configuration in that device-specific parameters – such as a hostname – are replaced with placeholders.
When you create a new device record, you are presented with a form allowing you to supply the correct values for each of the
placeholders in the configuration template. These values are merged with the configuration template to generate the actual
configuration that will be sent to the device.
Note
|
The placeholder values are merged with the configuration template when the configuration is being sent to the device. This
means the final device configuration may be different from that shown in the preview if any system variables change before
the device connects to the Manager.
|
Configurations are created as Mustache templates https://mustache.github.io/. Mustache allows a variety of placeholders – referred to as tags in the Mustache documentation – to be used, including:
-
Simple variables, where the placeholder is replaced with the value specified in the device record. A simple variable has the
form {{name}}.
-
Sections, where the placeholder encloses a block of configuration – optionally including other placeholders. The content of
the section may be excluded from the final configuration, included once or repeated several times.
The behavior of this type of placeholder is defined by the metadata in the template and the values that the user provides
when creating a device record.
A section has the form {{#name}}…{{/name}} where the first tag marks the beginning of the block and the second tag marks the end.
-
Comments can be used to document the configuration template. A comment has the form {{! This is a comment}}.
Following is an example of a simple template:
!
hostname {{hostname}}
!
{{! Insert a list of VLANs}}
{{#vlans}}
interface vlan {{vlan-id}}
name {{vlan-name}}
!
{{/vlans}}
In this example, there are several different placeholders:
-
{{hostname}} is a simple variable. It will be replaced by the value set for the hostname in the device record.
-
There is a comment placed just after the hostname configuration. The comment will not be included in the configuration sent
to the device.
-
{{#vlans}}…{{/vlans}} is a section that is used in this example to hold a list of individual VLANs. For each VLAN defined in the device record,
a copy of the contents of this container will be created in the device configuration.
-
{{vlan-id}} and {{vlan-name}} are both simple variables, but they are contained within the {{#vlans}} list. When the device record is created, you may
specify multiple values for {{vlan-id}} and {{vlan-name}} and they will be used to generate the configuration required to create each of those VLANs.
For more details on the Mustache syntax, consult the Mustache man page at https://mustache.github.io/mustache.5.html.
Template Metadata
Each configuration template contains metadata that describes how each placeholder should be presented to the user when device
records are being created. This metadata is generated when creating templates using the template editor.
When you create or edit a configuration template, the template editor is displayed with the configuration itself displayed
on the left and a form on the right that allows you to set the metadata for each placeholder.
Each placeholder in the configuration is shown on the right, along with the following controls:
-
A Required checkbox. This control determines whether the user must provide a value for this placeholder or not.
-
A Type drop-down list. This allows you to select the type of placeholder, which controls how that placeholder is displayed to the
user.
-
A Title. This may be used to provide a more user-friendly name for the parameter on the GUI. If a title is not specified for a placeholder,
then the placeholder itself with be displayed.
-
An Edit icon. Certain types have more settings available to control presentation. For example, a string placeholder may be further
refined to be an IP address or URL, and the input form will display an error if the text entered does have the correct format.
Certain types can also be set based on system information rather than user input. See System and Dynamic Variables below for
more details.
-
Move up/down controls. These arrows allow you to change the order in which placeholders are displayed to the user. Placeholders may be
grouped based on what makes the most sense to the user, rather than the order in which they appear in the configuration.
The template editor also provides a preview function which may be used to provide an example of how the placeholders form
will appear to the user when creating and editing device records.
Placeholder Types
The following placeholder types are available:
-
String – Placeholders of this type will be shown in the GUI as a simple text input box.
-
Integer – Integers are displayed as a text input box with controls to increase or decrease the value of the number displayed. Only
numbers may be entered into this field.
-
Boolean – A Boolean placeholder is displayed in the GUI as a checkbox. If the checkbox is checked, the placeholder be set to the
string value ‘true’. If the checkbox is unchecked, the value is ‘false’. A section may also be designated as a boolean, in
which case the configuration contained within the section will only be included when the checkbox for the section is checked.
-
Container – The Container type may be used to group other placeholders in the form.
-
List – A list is a container or section of configuration that may be repeated multiple times in a generated configuration file.
When form elements are generated for the placeholders inside a list, additional controls are added to add or remove elements
in the list.
In addition to the simple types listed above, string variables can be further refined by clicking the edit icon. Options available include:
-
Specifying a default value for the placeholder.
-
Setting the minimum and/or maximum length for string placeholders.
-
Specifying a pre-defined list of choices that may be selected (using the Enum option).
-
Constraining the format of a string to be one of a hostname, URI, IPv4 address or IPv6 address. A string may also be designated
as a text area if there is likely to be a significant amount of content to enter.
System and Dynamic Variables
Placeholders can not only take their values from user input, but can also take their values from parameters defined within
the system. System variables are parameters that have been defined for the Manager itself – such as the Manager IP address.
By setting a placeholder to take its value from a system variable, the Manager will insert that value into the configuration
without any user intervention. Some more complex deployments may require user input for the System Variables to work correctly.
See Managing Platform Settings for more details.
Dynamic variables are similar to System variables, but the values generated dynamically are based on information such as the
logged in user, or the device group the device belongs to. System and Dynamic variables are used to allow templates to be
more portable between devices and systems.