2013-06-10 18:08:14 -04:00
---
2015-07-22 22:31:00 -04:00
layout: docs
2017-03-25 18:13:52 -04:00
sidebar_current: docs-templates-engine
page_title: Template Engine - Templates
description: |-
All strings within templates are processed by a common Packer templating
engine, where variables and functions can be used to modify the value of a
configuration parameter at runtime.
---
2013-06-10 18:08:14 -04:00
2017-03-25 18:13:52 -04:00
# Template Engine
2013-06-10 18:08:14 -04:00
2015-07-22 22:31:00 -04:00
All strings within templates are processed by a common Packer templating engine,
where variables and functions can be used to modify the value of a configuration
parameter at runtime.
2013-08-08 19:56:09 -04:00
2015-07-22 22:31:00 -04:00
For example, the `{{timestamp}}` function can be used in any string to generate
the current timestamp. This is useful for configurations that require unique
2017-05-15 14:52:25 -04:00
keys, such as AMI names. By setting the AMI name to something like `My Packer
AMI {{timestamp}}`, the AMI name will be unique down to the second. If you
need greater than one second granularity, you should use `{{uuid}}` , for
example when you have multiple builders in the same template.
2013-08-08 19:56:09 -04:00
2017-05-15 14:31:58 -04:00
In addition to globally available functions like `{{timestamp}}` , some
2017-05-15 15:41:27 -04:00
configurations have special template variables that are available only
for that configuration. Template variables are recognizable because
they're prefixed by a period, such as `{{.Name}}` .
-> **Note:** In addition to template variables, you can specify your own user variables. See the [user variable ](/docs/templates/user-variables.html ) documentation for more information on user variables.
2013-08-08 19:56:09 -04:00
2015-07-22 22:31:00 -04:00
The complete syntax is covered in the next section, followed by a reference of
globally available functions.
2013-06-10 18:08:14 -04:00
## Syntax
2017-05-09 14:37:49 -04:00
The syntax of templates uses the following conventions:
2017-05-15 14:31:58 -04:00
* Anything template related happens within double-braces: `{{ }}` .
2017-05-15 15:41:27 -04:00
* Template variables are prefixed with a period and capitalized, such as
`{{.Variable}}` .
2017-05-15 14:31:58 -04:00
* Functions are directly within the braces, such as `{{timestamp}}` .
2013-08-08 19:56:09 -04:00
2017-05-15 15:41:27 -04:00
Here is an example from the VMware VMX template that shows template
variables in action:
2013-06-10 18:08:14 -04:00
2017-03-25 18:13:52 -04:00
```liquid
2013-06-10 18:08:14 -04:00
.encoding = "UTF-8"
displayName = "{{ .Name }}"
guestOS = "{{ .GuestOS }}"
2014-10-20 13:55:16 -04:00
```
2013-06-10 18:08:14 -04:00
2017-05-15 15:41:27 -04:00
In this case, the "Name" and "GuestOS" template variables will be
replaced, potentially resulting in a VMX template that looks like this:
2013-06-10 18:08:14 -04:00
2017-03-25 18:13:52 -04:00
```liquid
2013-06-10 18:08:14 -04:00
.encoding = "UTF-8"
displayName = "packer"
guestOS = "otherlinux"
2014-10-20 13:55:16 -04:00
```
2013-08-08 19:56:09 -04:00
## Global Functions
2017-05-15 15:41:27 -04:00
While some configuration settings have template variables specific to only that
2015-07-22 22:31:00 -04:00
configuration, a set of functions are available globally for use in *any string*
2013-08-08 19:56:09 -04:00
in Packer templates. These are listed below for reference.
2017-03-25 18:13:52 -04:00
- `build_name` - The name of the build being run.
- `build_type` - The type of the builder being used currently.
- `isotime [FORMAT]` - UTC time, which can be
2016-01-14 15:31:19 -05:00
[formatted ](https://golang.org/pkg/time/#example_Time_Format ). See more
2015-07-22 23:25:58 -04:00
examples below.
2017-03-25 18:13:52 -04:00
- `lower` - Lowercases the string.
- `pwd` - The working directory while executing Packer.
- `template_dir` - The directory to the template for the build.
- `timestamp` - The current Unix timestamp in UTC.
- `uuid` - Returns a random UUID.
- `upper` - Uppercases the string.
2017-05-15 14:31:58 -04:00
- `user` - Specify a user variable.
2013-09-07 21:50:01 -04:00
2014-05-07 02:51:33 -04:00
### isotime Format
2014-09-05 19:21:30 -04:00
2015-07-22 22:31:00 -04:00
Formatting for the function `isotime` uses the magic reference date **Mon Jan 2
15:04:05 -0700 MST 2006**, which breaks down to the following:
2014-05-07 02:51:33 -04:00
2014-10-20 13:55:16 -04:00
< table class = "table table-bordered table-condensed" >
2017-03-25 18:13:52 -04:00
< thead >
< tr >
< th >
< / th >
< th align = "center" >
Day of Week
< / th >
< th align = "center" >
Month
< / th >
< th align = "center" >
Date
< / th >
< th align = "center" >
Hour
< / th >
< th align = "center" >
Minute
< / th >
< th align = "center" >
Second
< / th >
< th align = "center" >
Year
< / th >
< th align = "center" >
Timezone
< / th >
< / tr >
< / thead >
< tr >
< th >
Numeric
< / th >
< td align = "center" >
-
< / td >
< td align = "center" >
01
< / td >
< td align = "center" >
02
< / td >
< td align = "center" >
03 (15)
< / td >
< td align = "center" >
04
< / td >
< td align = "center" >
05
< / td >
< td align = "center" >
06
< / td >
< td align = "center" >
-0700
< / td >
< / tr >
< tr >
< th >
Textual
< / th >
< td align = "center" >
Monday (Mon)
< / td >
< td align = "center" >
January (Jan)
< / td >
< td align = "center" >
-
< / td >
< td align = "center" >
-
< / td >
< td align = "center" >
-
< / td >
< td align = "center" >
-
< / td >
< td align = "center" >
-
< / td >
< td align = "center" >
MST
< / td >
< / tr >
2014-10-20 13:55:16 -04:00
< / table >
2015-07-22 22:31:00 -04:00
*The values in parentheses are the abbreviated, or 24-hour clock values*
2014-09-05 19:21:30 -04:00
2016-03-08 12:35:06 -05:00
Note that "-0700" is always formatted into "+0000" because `isotime` is always UTC time.
2015-07-22 22:31:00 -04:00
Here are some example formated time, using the above format options:
2014-09-05 19:21:30 -04:00
2017-03-25 18:13:52 -04:00
```liquid
2014-05-07 02:51:33 -04:00
isotime = June 7, 7:22:43pm 2014
{{isotime "2006-01-02"}} = 2014-06-07
2015-04-09 16:43:12 -04:00
{{isotime "Mon 1504"}} = Sat 1922
2015-06-06 16:43:06 -04:00
{{isotime "02-Jan-06 03\_04\_05"}} = 07-Jun-2014 07\_22\_43
2014-05-07 02:51:33 -04:00
{{isotime "Hour15Year200603"}} = Hour19Year201407
2014-10-20 13:55:16 -04:00
```
2014-05-07 02:51:33 -04:00
2016-02-16 16:49:38 -05:00
Please note that double quote characters need escaping inside of templates (in this case, on the `ami_name` value):
2015-01-17 04:20:19 -05:00
2017-03-25 18:13:52 -04:00
```json
2015-01-17 04:20:19 -05:00
{
"builders": [
{
"type": "amazon-ebs",
"access_key": "...",
"secret_key": "...",
"region": "us-east-1",
2016-03-16 22:28:10 -04:00
"source_ami": "ami-fce3c696",
2016-01-13 16:52:17 -05:00
"instance_type": "t2.micro",
2015-01-17 04:20:19 -05:00
"ssh_username": "ubuntu",
"ami_name": "packer {{isotime \"2006-01-02\"}}"
}
]
}
```
2017-03-25 18:13:52 -04:00
-> **Note:** See the [Amazon builder ](/docs/builders/amazon.html ) documentation for more information on how to correctly configure the Amazon builder in this example.
2016-02-16 16:49:38 -05:00
2013-09-07 21:50:01 -04:00
## Amazon Specific Functions
Specific to Amazon builders:
2017-03-25 18:13:52 -04:00
- `clean_ami_name` - AMI names can only contain certain characters. This
function will replace illegal characters with a '-" character. Example usage
since ":" is not a legal AMI name is: `{{isotime | clean_ami_name}}` .