win_template – Template a file out to a remote server — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_template – Template a file out to a remote server

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Return Values
- Status

## Synopsis

- Templates are processed by the Jinja2 templating language.
- Documentation on the template formatting can be found in the Template Designer Documentation.
- Additional variables listed below can be used in templates.
- `ansible_managed` (configurable via the `defaults` section of `ansible.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` is the numeric user id of the owner.
- `template_path` is the 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.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
backup boolean added in 2.8 | Choices: no ← yes | 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 | Choices: no yes ← | Determine when the file is being transferred if the destination already exists. When set to `yes`, replace the remote file when contents are different than the source. When set to `no`, the file will only be transferred if the destination does not exist.
lstrip_blocks boolean added in 2.6 | Choices: no ← yes | Determine when leading spaces and tabs should be stripped. When set to `yes` leading spaces and tabs are stripped from the start of a line to a block. This functionality requires Jinja 2.7 or newer.
newline_sequence string added in 2.4 | Choices: \n \r \r\n ← | Specify the newline sequence to use for templating files.
output_encoding string added in 2.7 | Default: "utf-8" | Overrides the encoding used to write the template file defined by `dest`. It defaults to `utf-8`, but any encoding supported by python can be used. The source template file must always be encoded using `utf-8`, for homogeneity.
src path / required |  | Path of a Jinja2 formatted template on the Ansible controller. This can be a relative or an absolute path. The file must be encoded with `utf-8` but output_encoding can be used to control the encoding of the output template.
trim_blocks boolean added in 2.4 | Choices: no yes ← | Determine when newlines should be removed from blocks. When 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

- 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.
- You can use the win_copy module with the `content:` option if you prefer the template inline, as part of the playbook.
- For Linux you can use template which uses ‘\n’ as `newline_sequence` by default.
- Including a string that uses a date in the template will result in the template being marked ‘changed’ each time.
- Since Ansible 0.9, templates are loaded with `trim_blocks=True`.
- 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: False` 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.
- Using raw/endraw in Jinja2 will not work as you expect because templates in Ansible are recursively evaluated.
- To find Byte Order Marks in files, use `Format-Hex <file> -Count 16` on Windows, and use `od -a -t x1 -N 16 <file>` on Linux.

## See Also

See also

win_copy – Copies files to remote locations on windows hosts
  The official documentation on the win_copy module.
copy – Copy files to remote locations
  The official documentation on the copy module.
template – Template a file out to a remote server
  The official documentation on the template 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 backward compatible 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.