ansible-keepass/README.md

86 lines
3.0 KiB
Markdown
Raw Normal View History

2019-03-13 16:09:06 +01:00
# Ansible KeePass Lookup Plugin
This collection provides plugins that allows to read data from KeePass file (modifying is not supported)
## How it works
The lookup plugin opens a UNIX socket with decrypted KeePass file.
For performance reasons, decryption occurs only once at socket startup,
and the KeePass file remains decrypted as long as the socket is open.
The UNIX socket file is stored in a temporary folder according to OS.
2019-03-13 16:09:06 +01:00
## Installation
2022-08-09 00:50:25 +02:00
Requirements: `python 3`, `pykeepass==4.0.3`
2022-08-09 00:50:25 +02:00
pip install 'pykeepass==4.0.3' --user
2022-08-09 13:39:08 +02:00
ansible-galaxy collection install viczem.keepass
2019-03-13 16:09:06 +01:00
## Variables
2019-05-05 00:48:52 +02:00
- `keepass_dbx` - path to KeePass file
- `keepass_psw` - *Optional*. Password (required if `keepass_key` is not set)
- `keepass_key` - *Optional*. Path to keyfile (required if `keepass_psw` is not set)
- `keepass_ttl` - *Optional*. Socket TTL (will be closed automatically when not used).
Default 60 seconds.
2019-03-21 11:49:33 +01:00
## Environment Variables
2023-01-10 06:38:08 +01:00
If you want to use ansible-keepass with continuous integration, it could be helpful not to use ansible variables but Shell environment variables.
- `ANSIBLE_KEEPASS_PSW` Password
- `ANSIBLE_KEEPASS_KEY` Path to keyfile
- `ANSIBLE_KEEPASS_TTL` Socket TTL
- `ANSIBLE_KEEPASS_SOCKET` Path to Keepass Socket
2023-01-10 06:38:08 +01:00
The environment variables will only be used, if no ansible variable is set.
2023-01-10 06:38:08 +01:00
You can than start the socket in another background process like this
```sh
export ANSIBLE_KEEPASS_PSW=mySecret
export ANSIBLE_KEEPASS_SOCKET=/home/build/.my-ansible-sock.${CI_JOB_ID}
export ANSIBLE_TTL=600 # 10 Minutes
/home/build/ansible-pyenv/bin/python3 /home/build/.ansible/roles/ansible_collections/viczem/keepass/plugins/lookup/keepass.py /path-to/my-keepass.kdbx &
ansible-playbook -v playbook1.yml
ansible-playbook -v playbook2.yml
```
2020-05-05 12:46:37 +02:00
## Usage
2019-03-21 11:49:33 +01:00
`ansible-doc -t lookup keepass` to get description of the plugin
2019-03-21 11:49:33 +01:00
> **WARNING**: For security reasons, do not store KeePass passwords in plain text.
Use `ansible-vault encrypt_string` to encrypt it and use it like below
2019-03-21 11:49:33 +01:00
# file: group_vars/all
keepass_dbx: "~/.keepass/database.kdbx"
keepass_psw: !vault |
$ANSIBLE_VAULT;1.1;AES256
...encrypted password...
2019-03-13 16:09:06 +01:00
2022-08-20 13:47:07 +02:00
### Examples
More examples see in [/docs/examples](/docs/examples).
#### Lookup
2019-03-13 16:09:06 +01:00
ansible_user : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'username') }}"
ansible_become_pass : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'password') }}"
2022-08-13 15:04:52 +02:00
custom_field : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'custom_properties', 'a_custom_property_name') }}"
attachment : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'attachments', 'a_file_name') }}"
2022-08-20 13:47:07 +02:00
#### Module
- name: "Export file: attachment.txt"
viczem.keepass.attachment:
database: "{{ keepass_dbx }}"
password: "{{ keepass_psw }}"
entrypath: example/attachments
attachment: "attachment.txt"
dest: "{{ keepass_attachment_1_name }}"
## Contributing
2019-03-13 16:09:06 +01:00
2022-08-20 13:47:07 +02:00
See [/docs/contributing](docs/contributing).