win_template – Templates a file out to a remote server¶
Synopsis¶
- Templates are processed by the Jinja2 templating language (http://jinja.pocoo.org/docs/) - documentation on the template formatting can be found in the Template Designer Documentation (http://jinja.pocoo.org/docs/templates/).
- Additional variables can be used in templates:
ansible_managed
(configurable via thedefaults
section ofansible.cfg
) contains a string which can be used to describe the template name, host, modification time of the template file and the owner uid. template_host
contains the node name of the template’s machine.template_uid
the owner.template_path
the absolute path of the template.template_fullpath
is the absolute path of the template.template_destpath
is the path of the template on the remote system (added in 2.8).template_run_date
is the date that the template was rendered.- Note that including a string that uses a date in the template will result in the template being marked ‘changed’ each time.
- For other platforms you can use template which uses ‘n’ as
newline_sequence
.
Parameters¶
Parameter | Choices/Defaults | Comments |
---|---|---|
backup
boolean
added in 2.8 |
|
Determine whether a backup should be created.
When set to
yes , create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. |
block_end_string
string
added in 2.4 |
Default: "%}"
|
The string marking the end of a block.
|
block_start_string
string
added in 2.4 |
Default: "{%"
|
The string marking the beginning of a block.
|
dest
path
/ required
|
Location to render the template to on the remote machine.
|
|
force
boolean
added in 2.4 |
|
If
yes , will replace the remote file when contents are different from the source.If
no , the file will only be transferred if the destination does not exist. |
newline_sequence
string
added in 2.4 |
|
Specify the newline sequence to use for templating files.
|
src
path
/ required
|
Path of a Jinja2 formatted template on the local server. This can be a relative or absolute path.
|
|
trim_blocks
boolean
added in 2.4 |
|
If this is set to
yes the first newline after a block is removed (block, not variable tag!). |
variable_end_string
string
added in 2.4 |
Default: "}}"
|
The string marking the end of a print statement.
|
variable_start_string
string
added in 2.4 |
Default: "{{"
|
The string marking the beginning of a print statement.
|
Notes¶
Note
- Templates are loaded with
trim_blocks=yes
. - Beware fetching files from windows machines when creating templates because certain tools, such as Powershell ISE, and regedit’s export facility add a Byte Order Mark as the first character of the file, which can cause tracebacks.
- To find Byte Order Marks in files, use
Format-Hex <file> -Count 16
on Windows, and useod -a -t x1 -N 16 <file>
on Linux. - Also, you can override jinja2 settings by adding a special header to template file. i.e.
#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: no
which changes the variable interpolation markers to [% var %] instead of {{ var }}. This is the best way to prevent evaluation of things that look like, but should not be Jinja2. raw/endraw in Jinja2 will not work as you expect because templates in Ansible are recursively evaluated. - You can use the win_copy module with the
content:
option if you prefer the template inline, as part of the playbook.
See Also¶
See also
- template – Template a file out to a remote server
- The official documentation on the template module.
- win_copy – Copies files to remote locations on windows hosts
- The official documentation on the win_copy module.
Examples¶
- name: Create a file from a Jinja2 template
win_template:
src: /mytemplates/file.conf.j2
dest: C:\Temp\file.conf
- name: Create a Unix-style file from a Jinja2 template
win_template:
src: unix/config.conf.j2
dest: C:\share\unix\config.conf
newline_sequence: '\n'
backup: yes
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
backup_file
string
|
if backup=yes |
Name of the backup file that was created.
Sample:
C:\Path\To\File.txt.11540.20150212-220915.bak
|
Status¶
- This module is guaranteed to have no backward incompatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support¶
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors¶
- Jon Hawkesworth (@jhawkesworth)
Hint
If you notice any issues in this documentation you can edit this document to improve it.