From 10f4a191fed554a4c44737b9874ac773e911df82 Mon Sep 17 00:00:00 2001
From: Jimisola Laursen <jimisola@jimisola.com>
Date: Mon, 15 Aug 2022 00:57:21 +0200
Subject: [PATCH] docs: Update docs and refactor doc to docs

---
 README.md                          |  19 +++++++---
 docs/contributing/README.md        |  29 ++++++++++++++++
 docs/examples/README.md            |   5 +++
 docs/examples/example-playbook.yml |  54 +++++++++++++++++++++++++++++
 docs/examples/example.kdbx         | Bin 0 -> 3605 bytes
 docs/examples/group_vars/all       |   9 +++++
 galaxy.yml                         |   5 +--
 7 files changed, 115 insertions(+), 6 deletions(-)
 create mode 100644 docs/contributing/README.md
 create mode 100644 docs/examples/README.md
 create mode 100644 docs/examples/example-playbook.yml
 create mode 100644 docs/examples/example.kdbx
 create mode 100644 docs/examples/group_vars/all

diff --git a/README.md b/README.md
index 971ed4e..ed2c6ae 100644
--- a/README.md
+++ b/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`
@@ -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') }}"
     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') }}"
+    
+    - 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.
\ No newline at end of file
diff --git a/docs/contributing/README.md b/docs/contributing/README.md
new file mode 100644
index 0000000..1007513
--- /dev/null
+++ b/docs/contributing/README.md
@@ -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.
diff --git a/docs/examples/README.md b/docs/examples/README.md
new file mode 100644
index 0000000..ade8370
--- /dev/null
+++ b/docs/examples/README.md
@@ -0,0 +1,5 @@
+# Example
+
+`ansible-playbook example-playbook.yml --ask-vault-pass -vvv`
+ 
+Password: `spamham`
\ No newline at end of file
diff --git a/docs/examples/example-playbook.yml b/docs/examples/example-playbook.yml
new file mode 100644
index 0000000..6d27a23
--- /dev/null
+++ b/docs/examples/example-playbook.yml
@@ -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
\ No newline at end of file
diff --git a/docs/examples/example.kdbx b/docs/examples/example.kdbx
new file mode 100644
index 0000000000000000000000000000000000000000..127e279a7db0e59747e4f56d90961cfdf772f448
GIT binary patch
literal 3605
zcmV+w4(jm(*`k_f`%AR|00aO65C8xGF~RcYzi~rQzE}kzYW!ON0|Wp70096100bZa
z002^j1d{xR-BuB=;F>iQDrfj$Oq02T@!sI5g{_EjZRrOP0002VJ8~sShAhtFmdG@C
z$~o=}ivR!s00BY;0000aRaHqu5C8xG?_+J>j44D*k@u;j1LFz|1pxp607(b{000gE
z00000000F60000@2mk;800004000001OWg508j(~00062002S(0000}AOHXW0%&ME
zZZH-Tzy$>_hr~TN!!b1i7}uo}OQFadBM^s71OWg509FJ5000vJ000001ONa44GIkk
ze2BjAL}>f7bVx*-TZenJ*Ko-AGs-0~kaiNp*>BQ_WX2m;SW&}~25794k6lN>0wy&7
ztB?`${pFcL2;wveo$-P?-TxC9aLV5eOt$<^4s%QS<Moa*ebNS>BhhMrkPH9-+Tg4a
zYd6^L($VcM|9AWEZXOx?;>%}%fzdX*D6m!;&aUVr1k`IrrOQ7)k>P?cUepe&dBT-u
z?2D#l_yCi<LrJb8;ondLGi8Av@(EBRre`Jrq>=Z&)vl#iAN@G=g_+MLLJ^jOQNlWM
z5%F#Qwb?%8MP;<n#;mGJWh*g>a)*@r*6mN2FA>xSV(c<nBWOo4R(i}CpLnAH{m9gL
zh?!Zx3!g~*QTyhPGE9%k74-KQs_wZ$^aV`$rgE-{f%@G7(ku^o46I*&IKNHq=+R=h
zg^j%h)n)MUv>g0ib(3hI^7x~~GP4MQA-2E9tkN5R#c*LolualoP*?4o(*JMXso}Xh
z%v5+#`o+VlyvcR%+cGS=Sx?2GaQ!0T4SlNJ!g}DVPZ3kLdz};fN^i;*+9wEGj1yMt
z(3v%mSAJbOchRkeesi^`5Gs&JBQG<lbhUM|boN@Ae?tmqQ0L>wM6IQWPz^LO!MI)D
zc4VZZO7suUT++*X0ZoYp)WUiK^mqCZ-<j73!fMABs*L_xSIQuwa7J;qM!JqvKS0SO
zL)p=Eu(liE+nSlW&kc$0UOHTD4lp-C%=0SFEXi}XQMk~XIUkL3(>-`(_%U2C$Q$#M
z+d>mXdJK)K9w6J`p<NOis|;sAdltC2qPew9*DY8;Gb3faJPKl^Lc}%^QbR!x`V6qU
zO5v39JTV~9k4%IiLlgjdA!b{6?s&-G6Pi$nl*a{);;O``PHN_PonBL<?jgaMO<f%f
zwtRsM=U~=xJ4KLMND+a*{;*$P<R&L`!QK<)Y<ieu-68$d2!RxoG5kk`sHo%Z<EfQm
zi7x;$K8%t+Xnwlb?3@9w8TDbwGOmppo(C_9Z{~i24dc>BA9`h9ARF*&2+qq51Eucs
zye<91LYt^k4mV0P`PY&Qx7GS>iKfIt&yEoWtHSy%&XHc_DKHpRe-dy?!di_n!9GM?
z>VHv|P2)!Yl*xm$imGWACvAm3{-&jGOqAlBo(BYBOV`;wcANSJkw;_#6hxqD*^#U}
zxZWeYRHsZ98T@H32Qg>U)5uJdrI+yEwMu15Uok5#EJ16V+EyVEV?SlRPEVMa=#AVU
zGaUV74<Az&D_`KQ79M3EEodT66C<P(#7=#MZNFBzVYv5stO)JSa|0dJRHgfjP(kB*
z`*c#730oSWGFKnk>LF9k?+zv2eoR~$Z_8fTPKkt?_wVFA&1?qAd`&;F|5I)m0fazD
zF`9FK)h<4Pce*qHYTRx&a>+j^Bgm))pcaZ*CnPH}=NID0d3LKMwv#Qk=I+}NmQB~0
zS+;zH;syN!3*GXC)pC63itsy55{FYb`T{AwG;z?LQFSNk!^XspzJFgB1W@R?X|`!6
ze%LR9?uh!87~%tHalf3VnOGBS=@DwMIESVQ`Wo=_oaA-owzFJ0?!ISq8m`p@SdATt
zg>&p(hNC6GL2&d<<WL5_M$Fy-m~8xJN2P1_U1A}if1w~+GEJgCwnLQ@a?>E{DMJTL
z<B1kawLhgrEAHI3V>Qv@j^}x8Cyj$q&0H$U_m|o5WSv3?q>p?HaJg>qP-#3XK6{%H
z?LV~4`$<tJn;6#F9`oG_kp*jn!bO<1k9BqtkyWO8Fob>3W2IMdLO6HZV~{374OhxD
zuyEQW_p4B<nMsMPv#1~C;IK&>thuw7DX)<{;Z~y_vBPsp38kJbr$R0+|Fwo-o$LAv
z!DbfF`Li+vBl!qpMLNPi66fvTjuzx`i%YtcwXwz=ahbIOoCKsck9@E&>vbQf&ey!o
z?SfD>+fnsDMv@%cXzKKY!(?}m5AS!b*qW0AM$?>-ix<G0*QC05vv!NkAXcxtH6w$6
zJIuqdWi#j&hk{coE(KeK3>j)*t|Lim=M3<oG#=`+KN-zD`72ZO!mp@DZ$2)v^eJ0S
z;H;n_av5<Q&h7G!e<m2)hSl7wGV$&Xx76flyxoM%%_I)@bfXh|aUwk7@Fzpm7z@h$
z>iTo~=l%9jE?Mf7lrH(>vL7pSi#;bqZhTAOcb_6LCE)QKaQ`qo67UZiW;+GG&8c=B
zBL2ge>Y&$5QsbXRlMTEPB1>Ya2&xyep2~cZ91t)$;6|6Vkg_W|e<JT;&}t)L{DbYM
z>FtrsgZ<`FbO9Zt@E;J0z+(gd6;sWP)sPHC^&JVfmO<T&-)d3y=ZXx6r}Y+7EdC_l
zkBP_vIz-1UzIB|hM9<(8?*o#@4A%9ZawOjUxb@b>xLa$a$@j=iD3u<c3-W4IL3z!;
zXmhm2cLp(H_pYxM`F*C|Z3iiLbB?tSV_q6YrX5Y^V7BzwdEN;$NGx=$8pBYE#_{Xc
z4OXA1n^cF@;TT~P93dURU|N;-MyT&cmPp^2&gX%Qn^;w1TEaIBSI-n>)HlH5Y|3Uk
zF7R-cBw;HKVri^9yK4FaTFza;c|enlS{C`^=~7SliD=jQ<dbY_Bb-MhS$rHQDlWc~
zuwj^!df;dau`$|_?e3}R^bWHPcx*aaJ{2f0j9P{AtH}xu&lDa=5A({QX!6DPoO0>2
z1M}r<?r??vu(}58ksR-{jQQ_&NDY8(u>wr<=a-LHE+oOhyjkLpq0T?k4LZ@7XG~QP
z)vo_#Lu9Zv%x_I}qN+aFi2c(arVPqpeZ!bX0LEx1;nfrjJ~Cjort|ZnDVsSexpXh=
zc(XlnJ`{9}AiqU;J%lZ@WF3a>$6gX9^i71+pNK^XXy-+bbm)}ewlVL0%cM*7KNzJq
zoxk*AiikDU)&WcF`OvKfE(8#01Xe0?06hF}_ahCSOe*`LMbrrZoTq@}6wi_-jaCT@
zSobsfM^0-p0|T{hYHfJlGmfv?5!LK5fRogN7a&w*g!fjRxe5IH{(mSBB@R>zvWy+1
z*0}!#sv8!{{|DxcN|`2&^#BLgCd405`fSG?0*U`ath;*qil5tM3N{UHSrY9{F0^WE
ze~=0U)tHQV8o>l>1HCIlwv*yX_{kixqJT+H{iwLkQ2Xt0U)r=ZrOg^hTE8~@5vL;L
zADcIiylj!j7~=SFUNP$U8i6ub)^KDNJRApM#D;TfflI1lC!3|2OU%Dff<pW*Jpz3;
z{^TO}vIQ%nzk%G;_JPqgNy(c?Xzm>;Q=G4RCW=Q>i45=FE27+>rZ&#!W!d7HBU<M5
zz+?O{;I_3CXJy)Ot73_>Zjv<<0b=L}Rgx{7CtN&FB|^*6Y|iobA7jr7fH>t?JL><Y
z2vtLOW8-0=61(KiWECRNfo;L6>(J%LS^s;^_XdrjRnCME;Ze5=MhhFl$Pq(QEIy`w
zcFqh?rF^t<uynhY3bFc7G$!Q#_g?1U3+N?lkMY;=WlUU<UOmO;>NN~LOA~xH6+{bJ
zB6U6#a)`OoMY?eF2|L_Ztez&@4H<qIli*CY!=o7oL-uOT0BBK}Uwp~hqV7^1Ct%}l
zlTe$Rzns|fT@JFxz^*JjJX^m))M5^d*sob`O1MGpU%oCbW`0s#u&xqax_kjh5WA7H
z9r?K;L-tDkG9avOmx~5?5}+3gP+eKSI*H0gSW_E90hyG_NoO$F+E8M+VFAngN3IF>
zE`bYv`JhTR_&5f0Ky|%&ej26?kteuOj2oArj%Ii-lMm$W40O_re-}NvVLHV&<K9d>
z#rGp79t>gW#nl?=K9*9F00?42SzfHr=<ApbEI2_m5ZcOWM<LAiJd$R*k{s_xv}At&
z$}b7|KWBOKTye#w!>LoO-(l(RYlBJ>YqnFC6>+;phVQ0o3#2DDqW*Sh?2IH<I)y_e
z#7h8=SosDyKlg45JJ$v(;j$r=77W}Cd*}ucxh#iFnhDIqNOVD`V+X)#C*J?r?3ym2
zq5Z>Jkmz8!#{rpG2k52O0@dw+vP)HwyK1zi8UfP>`luP})vDwlq7;>szWSV~c7fg}
zx2*%PSydo6_~d%qc#Q4zUPFn#+CC<Fuy%!OQJKA6Y8G0u&LbJsRRHz#e!mI=iZ0L3
zky;}O1LUE9GpZ}RVTXE{N|Q_h$ANY#K3Sc2D|j#DdL@Rg;~EC3#S-(JAZF9Se-BLy
zgvyhI<cg@*`7;0-m42*hszb@ao}Bjvcb@&dbo@v#V}8}|_7#ryBgLuSkdHw4U$2%B
z0i7`F?GZKllIm3YvzrC~J#yhe6Ni?uV2rgy;Q(qv)}uuHQJ=zUoFg=9e)EQ~`i(AI
z)DF_!jW<$e5Mg5|X5%jzkje-P{NltIT-H~*>>Jkmp-8~Ip4Kpxb=Xf44tN^&AIMdR
bp`wKSv&}I@A6Zgf!h(}iPvlNK00000kNvgN

literal 0
HcmV?d00001

diff --git a/docs/examples/group_vars/all b/docs/examples/group_vars/all
new file mode 100644
index 0000000..679e175
--- /dev/null
+++ b/docs/examples/group_vars/all
@@ -0,0 +1,9 @@
+keepass_ttl: 3
+keepass_dbx: "./example.kdbx"
+keepass_psw: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          30656633313531336265353862356135373963636339376266373137376136636634393932623961
+          6138656232363861333932373066636237626232623566380a313964313733643532373139313636
+          62303365393630383037356334363332306239316566383061336263383134353139663161643331
+          3736316666613761380a646333353163633236323835313965313034373163343031616531393336
+          6538
diff --git a/galaxy.yml b/galaxy.yml
index cd8af3e..7e12847 100644
--- a/galaxy.yml
+++ b/galaxy.yml
@@ -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