community.general.passwordstore – manage passwords with passwordstore.org’s pass utility

Note

This plugin is part of the community.general collection (version 3.8.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.passwordstore.

Synopsis

  • Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility. It also retrieves YAML style keys stored as multilines in the passwordfile.

Parameters

Parameter Choices/Defaults Configuration Comments
_terms
string / required
query key.
backup
boolean
    Choices:
  • no ←
  • yes
Used with overwrite=yes. Backup the previous password in a subkey.
create
boolean
    Choices:
  • no ←
  • yes
Create the password if it does not already exist. Takes precedence over missing.
directory
string
env:PASSWORD_STORE_DIR
The directory of the password store.
length
integer
Default:
16
The length of the generated password.
missing
string
added in 3.1.0 of community.general
    Choices:
  • error ←
  • warn
  • empty
  • create
List of preference about what to do if the password file is missing.
If create=true, the value for this option is ignored and assumed to be create.
If set to error, the lookup will error out if the passname does not exist.
If set to create, the passname will be created with the provided length length if it does not exist.
If set to empty or warn, will return a none in case the passname does not exist. When using lookup and not query, this will be translated to an empty string.
nosymbols
boolean
    Choices:
  • no ←
  • yes
use alphanumeric characters.
overwrite
boolean
    Choices:
  • no ←
  • yes
Overwrite the password if it does already exist.
passwordstore
string
Default:
"~/.password-store"
location of the password store.
returnall
boolean
    Choices:
  • no ←
  • yes
Return all the content of the password, not only the first line.
subkey
string
Default:
"password"
Return a specific subkey of the password. When set to password, always returns the first line.
umask
string
added in 1.3.0 of community.general
env:PASSWORD_STORE_UMASK
Sets the umask for the created .gpg files. The first octed must be greater than 3 (user readable).
Note pass' default value is '077'.
userpass
string
Specify a password to save, instead of a generated one.

Examples

# Debug is used for examples, BAD IDEA to show passwords on screen
- name: Basic lookup. Fails if example/test doesn't exist
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.passwordstore', 'example/test')}}"

- name: Basic lookup. Warns if example/test does not exist and returns empty string
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.passwordstore', 'example/test missing=warn')}}"

- name: Create pass with random 16 character password. If password exists just give the password
  ansible.builtin.debug:
    var: mypassword
  vars:
    mypassword: "{{ lookup('community.general.passwordstore', 'example/test create=true')}}"

- name: Create pass with random 16 character password. If password exists just give the password
  ansible.builtin.debug:
    var: mypassword
  vars:
    mypassword: "{{ lookup('community.general.passwordstore', 'example/test missing=create')}}"

- name: Prints 'abc' if example/test does not exist, just give the password otherwise
  ansible.builtin.debug:
    var: mypassword
  vars:
    mypassword: "{{ lookup('community.general.passwordstore', 'example/test missing=empty') | default('abc', true) }}"

- name: Different size password
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.passwordstore', 'example/test create=true length=42')}}"

- name: Create password and overwrite the password if it exists. As a bonus, this module includes the old password inside the pass file
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.passwordstore', 'example/test create=true overwrite=true')}}"

- name: Create an alphanumeric password
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.passwordstore', 'example/test create=true nosymbols=true') }}"

- name: Return the value for user in the KV pair user, username
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.passwordstore', 'example/test subkey=user')}}"

- name: Return the entire password file content
  ansible.builtin.set_fact:
    passfilecontent: "{{ lookup('community.general.passwordstore', 'example/test returnall=true')}}"

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key Returned Description
_raw
list / elements=string
success
a password


Authors

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/passwordstore_lookup.html