<commit_before>Using Lookups
=============

.. contents::
   :depth: 2

Lookup plugins allow access of data in Ansible from outside sources.  This can include the filesystem
but also external datastores.  These values are then made available using the standard templating system
in Ansible, and are typically used to load variables or templates with information from those systems.

.. note:: This is considered an advanced feature, and many users will probably not rely on these features.  

.. _getting_file_contents:

Intro to Lookups: Getting File Contents
```````````````````````````````````````

The file lookup is the most basic lookup type.

Contents can be read off the filesystem as follows::

    - hosts: all
      vars:
         contents: "{{ lookup('file', '/etc/foo.txt') }}"
      tasks:
         - debug: msg="the value of foo.txt is {{ contents }}"

.. _password_lookup:

The Password Lookup
```````````````````

``password`` generates a random plaintext password and store it in
a file at a given filepath.  Support for crypted save modes (as with vars_prompt) is pending.  If the
file exists previously, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set
up random passwords per host (what simplifies password management in 'host_vars' variables).

Generated passwords contain a random mix of upper and lowercase ASCII letters, the
numbers 0-9 and punctuation (". , : - _"). The default length of a generated password is 30 characters.
This length can be changed by passing an extra parameter::

    ---
    - hosts: all

      tasks:

        # create a mysql user with a random password:
        - mysql_user: name={{ client }}
                      password="{{ lookup('password', 'credentials/' + client + '/' + tier + '/' + role + '/mysqlpassword length=15') }}"
                      priv={{ client }}_{{ tier }}_{{ role }}.*:ALL

        (...)

.. _more_lookups:
<commit_msg>Fix some information in the docsite for the password lookup plugin<commit_after>Using Lookups
=============

.. contents::
   :depth: 2

Lookup plugins allow access of data in Ansible from outside sources.  This can include the filesystem
but also external datastores.  These values are then made available using the standard templating system
in Ansible, and are typically used to load variables or templates with information from those systems.

.. note:: This is considered an advanced feature, and many users will probably not rely on these features.  

.. _getting_file_contents:

Intro to Lookups: Getting File Contents
```````````````````````````````````````

The file lookup is the most basic lookup type.

Contents can be read off the filesystem as follows::

    - hosts: all
      vars:
         contents: "{{ lookup('file', '/etc/foo.txt') }}"
      tasks:
         - debug: msg="the value of foo.txt is {{ contents }}"

.. _password_lookup:

The Password Lookup
```````````````````

``password`` generates a random plaintext password and store it in
a file at a given filepath.  Support for crypted save modes (as with vars_prompt) is pending.  If the
file exists previously, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set
up random passwords per host (what simplifies password management in 'host_vars' variables).

Generated passwords contain a random mix of upper and lowercase ASCII letters, the
numbers 0-9 and punctuation (". , : - _"). The default length of a generated password is 20 characters.
This length can be changed by passing an extra parameter::

    ---
    - hosts: all

      tasks:

        # create a mysql user with a random password:
        - mysql_user: name={{ client }}
                      password="{{ lookup('password', 'credentials/' + client + '/' + tier + '/' + role + '/mysqlpassword length=15') }}"
                      priv={{ client }}_{{ tier }}_{{ role }}.*:ALL

        (...)

.. note:: If the file already exists, no data will be written to it. If the file has contents, those contents will be read in as the password. Empty files cause the password to return as an empty string        

.. _more_lookups:

{'fraction_non_alphanumeric': 0.1131189861534851, 'fraction_numerical': 0.0032856137057028865, 'mean_word_length': 3.2920443101711983, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1343993', 'n_tokens_mistral': 1136, 'n_tokens_neox': 1056, 'n_words': 532}