docs: Update docs and refactor doc to docs
This commit is contained in:
parent
ef15128536
commit
10f4a191fe
19
README.md
19
README.md
|
@ -1,15 +1,14 @@
|
||||||
# Ansible KeePass Lookup Plugin
|
# Ansible KeePass Lookup Plugin
|
||||||
|
|
||||||
This collection provides a plugin that allows to read data from KeePass file (modifying is not supported)
|
This collection provides plugins that allows to read data from KeePass file (modifying is not supported)
|
||||||
|
|
||||||
## How it works
|
## How it works
|
||||||
|
|
||||||
The plugin opens a UNIX socket with decrypted KeePass file.
|
The lookup plugin opens a UNIX socket with decrypted KeePass file.
|
||||||
For performance reasons, decryption occurs only once at socket startup,
|
For performance reasons, decryption occurs only once at socket startup,
|
||||||
and the KeePass file remains decrypted as long as the socket is open.
|
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.
|
The UNIX socket file is stored in a temporary folder according to OS.
|
||||||
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
Requirements: `python 3`, `pykeepass==4.0.3`
|
Requirements: `python 3`, `pykeepass==4.0.3`
|
||||||
|
@ -47,5 +46,17 @@ Use `ansible-vault encrypt_string` to encrypt it and use it like below
|
||||||
ansible_become_pass : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'password') }}"
|
ansible_become_pass : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'password') }}"
|
||||||
custom_field : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'custom_properties', 'a_custom_property_name') }}"
|
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') }}"
|
attachment : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'attachments', 'a_file_name') }}"
|
||||||
|
|
||||||
|
- 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 }}"
|
||||||
|
|
||||||
More examples see in [/doc/examples](/doc/examples).
|
More examples see in [/docs/examples](/docs/examples).
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
See docs/contributing.
|
|
@ -0,0 +1,29 @@
|
||||||
|
# Contributing
|
||||||
|
|
||||||
|
1. Create ansible.cfg in cloned directory:
|
||||||
|
|
||||||
|
```
|
||||||
|
[defaults]
|
||||||
|
COLLECTIONS_PATHS = ./collections
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Create requirements.yml in cloned directory:
|
||||||
|
|
||||||
|
```
|
||||||
|
---
|
||||||
|
collections:
|
||||||
|
- name: namespace.collection_name
|
||||||
|
source: /where/is/your/clone
|
||||||
|
type: dir
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
3. To install the collection _locally_ in your cloned directory, just install it through ansible-galaxy
|
||||||
|
```shell
|
||||||
|
rm -rf ./collections && ansible-galaxy install -r requirements.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Note: Any change on your clone imply to reinstall the collection.
|
||||||
|
|
||||||
|
|
||||||
|
Tip: You can place a ansible.cfg with `COLLECTIONS_PATHS = ../../collections` in the examples dictory if you want to run the example on local collection in your cloned directory.
|
|
@ -0,0 +1,5 @@
|
||||||
|
# Example
|
||||||
|
|
||||||
|
`ansible-playbook example-playbook.yml --ask-vault-pass -vvv`
|
||||||
|
|
||||||
|
Password: `spamham`
|
|
@ -0,0 +1,54 @@
|
||||||
|
---
|
||||||
|
- name: Example
|
||||||
|
hosts: 127.0.0.1
|
||||||
|
connection: local
|
||||||
|
vars:
|
||||||
|
spam_login: "{{ lookup('viczem.keepass.keepass', 'spam', 'username') }}"
|
||||||
|
spam_password: "{{ lookup('viczem.keepass.keepass', 'spam', 'password') }}"
|
||||||
|
ham_login: "{{ lookup('viczem.keepass.keepass', 'example/ham', 'username') }}"
|
||||||
|
ham_password: "{{ lookup('viczem.keepass.keepass', 'example/ham', 'password') }}"
|
||||||
|
slash_login: "{{ lookup('viczem.keepass.keepass', 'slash\\/group/slash\\/title', 'username') }}"
|
||||||
|
slash_url: "{{ lookup('viczem.keepass.keepass', 'slash\\/group/slash\\/title', 'url') }}"
|
||||||
|
pork_custom_property: "{{ lookup('viczem.keepass.keepass', 'example/pork', 'custom_properties', 'pork_custom_property')}}"
|
||||||
|
attachment: "{{ lookup('viczem.keepass.keepass', 'example/pork', 'attachments', 'test.txt')}}"
|
||||||
|
keepass_attachment_1_name: "attachment_1.txt"
|
||||||
|
keepass_attachment_2_name: "attachment_2.zip"
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
- debug:
|
||||||
|
msg: "fetch entry: '/spam'; username: '{{ spam_login }}'; password: '{{ spam_password }}'"
|
||||||
|
|
||||||
|
- debug:
|
||||||
|
msg: "fetch entry: '/examples/ham'; username: '{{ ham_login }}'; password: '{{ ham_password }}'"
|
||||||
|
|
||||||
|
- debug:
|
||||||
|
msg: "fetch entry: '/examples/port'; attachments: 'text.txt' - '{{ attachment }}'"
|
||||||
|
|
||||||
|
- name: pause to emulate long time operation (greater than keepass_ttl)
|
||||||
|
pause:
|
||||||
|
seconds: 5
|
||||||
|
|
||||||
|
- debug:
|
||||||
|
msg: "fetch entry: '/examples/pork'; custom_properties: 'pork_custom_property' - '{{ pork_custom_property }}'"
|
||||||
|
|
||||||
|
- debug:
|
||||||
|
msg: "fetch entry: '/slash\\/group/slash\\/title'; username: '{{ slash_login }}'; url: '{{ slash_url }}'"
|
||||||
|
|
||||||
|
- debug: "{{ lookup('viczem.keepass.keepass', 'close') }}"
|
||||||
|
|
||||||
|
- name: "Export file: {{ keepass_attachment_1_name }}"
|
||||||
|
viczem.keepass.attachment:
|
||||||
|
database: "{{ keepass_dbx }}"
|
||||||
|
password: "{{ keepass_psw }}"
|
||||||
|
entrypath: example/attachments
|
||||||
|
attachment: "{{ keepass_attachment_1_name }}"
|
||||||
|
dest: "{{ keepass_attachment_1_name }}"
|
||||||
|
|
||||||
|
- name: "Export file: {{ keepass_attachment_2_name }}"
|
||||||
|
viczem.keepass.attachment:
|
||||||
|
database: "{{ keepass_dbx }}"
|
||||||
|
password: "{{ keepass_psw }}"
|
||||||
|
entrypath: example/attachments
|
||||||
|
attachment: "{{ keepass_attachment_2_name }}"
|
||||||
|
dest: "{{ keepass_attachment_2_name }}"
|
||||||
|
mode: 0600
|
Binary file not shown.
|
@ -0,0 +1,9 @@
|
||||||
|
keepass_ttl: 3
|
||||||
|
keepass_dbx: "./example.kdbx"
|
||||||
|
keepass_psw: !vault |
|
||||||
|
$ANSIBLE_VAULT;1.1;AES256
|
||||||
|
30656633313531336265353862356135373963636339376266373137376136636634393932623961
|
||||||
|
6138656232363861333932373066636237626232623566380a313964313733643532373139313636
|
||||||
|
62303365393630383037356334363332306239316566383061336263383134353139663161643331
|
||||||
|
3736316666613761380a646333353163633236323835313965313034373163343031616531393336
|
||||||
|
6538
|
|
@ -21,11 +21,11 @@ authors:
|
||||||
|
|
||||||
### OPTIONAL but strongly recommended
|
### OPTIONAL but strongly recommended
|
||||||
# A short summary description of the collection
|
# A short summary description of the collection
|
||||||
description: The collection provides a lookup plugin that allow to read data from KeePass file.
|
description: The collection provides plugins that allow to read data from KeePass file.
|
||||||
|
|
||||||
# Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only
|
# Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only
|
||||||
# accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file'
|
# accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file'
|
||||||
license: []
|
license: [MIT]
|
||||||
|
|
||||||
# The path to the license file for the collection. This path is relative to the root of the collection. This key is
|
# The path to the license file for the collection. This path is relative to the root of the collection. This key is
|
||||||
# mutually exclusive with 'license'
|
# mutually exclusive with 'license'
|
||||||
|
@ -36,6 +36,7 @@ license_file: 'LICENSE'
|
||||||
tags:
|
tags:
|
||||||
- keepass
|
- keepass
|
||||||
- lookup
|
- lookup
|
||||||
|
- module
|
||||||
- plugin
|
- plugin
|
||||||
|
|
||||||
# Collections that this collection requires to be installed for it to be usable. The key of the dict is the
|
# Collections that this collection requires to be installed for it to be usable. The key of the dict is the
|
||||||
|
|
Loading…
Reference in New Issue