community.general.binary_file lookup – Read binary file and return it Base64 encoded

Note

This lookup plugin is part of the community.general collection (version 11.2.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.binary_file.

New in community.general 11.2.0

Synopsis

  • This lookup returns the contents from a file on the Ansible controller’s file system.

  • The file is read as a binary file and its contents are returned Base64 encoded. This is similar to using ansible.builtin.file combined with ansible.builtin.b64encode, except that ansible.builtin.file does not support binary files as it interprets the contents as UTF-8, which can cause the wrong content being Base64 encoded.

Terms

Parameter

Comments

Terms

list / elements=string / required

Paths of the files to read.

Relative paths will be searched for in different places. See Ansible task paths for more details.

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('community.general.binary_file', key1=value1, key2=value2, ...) and query('community.general.binary_file', key1=value1, key2=value2, ...)

Parameter

Comments

not_exist

string

Determine how to react if the specified file cannot be found.

Choices:

  • "empty": Return an empty string for the file.

  • "empty_str": Return the string empty for the file.

    This cannot be confused with Base64 encoding due to the missing padding.

  • "error" (default): Raise an error.

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('community.general.binary_file', term1, term2, key1=value1, key2=value2) and query('community.general.binary_file', term1, term2, key1=value1, key2=value2)

  • This lookup does not understand ‘globbing’ - use the ansible.builtin.fileglob lookup instead.

See Also

See also

ansible.builtin.b64decode filter plugin

The b64decode filter can be used to decode Base64 encoded data. Note that Ansible cannot handle binary data, the data will be interpreted as UTF-8 text!

ansible.builtin.file lookup plugin

You can use this lookup plugin to read text files from the Ansible controller.

ansible.builtin.slurp

Also allows to read binary files Base64 encoded, but from remote targets. With delegate_to: localhost can be redirected to run on the controller, but you have to know the path to the file to read. Both this plugin and ansible.builtin.file use some search path logic to for example also find files in the files directory of a role.

Task paths

Search paths used for relative files.

Examples

---
- name: Output Base64 contents of binary files on screen
  ansible.builtin.debug:
    msg: "Content: {{ lookup('community.general.binary_file', item) }}"
  loop:
    - some-binary-file.bin

Return Value

Key

Description

Return value

list / elements=string

Base64 encoded content of requested files, or an empty string resp. the string empty, depending on the not_exist option.

This list contains one string per element of _terms in the same order as _terms.

Returned: success

Authors

  • Felix Fontein (@felixfontein)