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
|
||||
|
||||
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
|
||||
|
||||
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,
|
||||
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.
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
Requirements: `python 3`, `pykeepass==4.0.3`
|
||||
|
@ -48,4 +47,16 @@ Use `ansible-vault encrypt_string` to encrypt it and use it like below
|
|||
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') }}"
|
||||
|
||||
More examples see in [/doc/examples](/doc/examples).
|
||||
- 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 [/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
|
||||
# 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
|
||||
# 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
|
||||
# mutually exclusive with 'license'
|
||||
|
@ -36,6 +36,7 @@ license_file: 'LICENSE'
|
|||
tags:
|
||||
- keepass
|
||||
- lookup
|
||||
- module
|
||||
- plugin
|
||||
|
||||
# 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