update documentation

README.md

@@ -7,49 +7,49 @@ It addresses the issues of non-responding keyservers in general by repeating att
 ### examples
 
 ```YAML
-tasks:
-  - name: Install GPG key
-    gpg_import: key_id="0x3804BB82D39DC0E3"
-```
-or
-```YAML
-tasks:
-  - name: Install GPG key
-    gpg_import: key_id="0x3804BB82D39DC0E3"
-      bin_path: '/usr/loca/bin/gpg'
-```
-or
-```YAML
-tasks:
-  - name: Install or update GPG key
-    gpg_import:
-      key_id: "0x3804BB82D39DC0E3"
-      state: latest
-      servers:
-        - 'hkp://no.way.ever'
-        - 'keys.gnupg.net'
-        - 'hkps://hkps.pool.sks-keyservers.net'
-```
-or
-```YAML
-tasks:
-  - name: Install or fail with fake and not fake GPG keys
-    gpg_import:
-      key_id: "{{ item }}"
-      tries: 2
-    with_items:
-      - "0x3804BB82D39DC0E3"
-      - "0x3804BB82D39DC0E4" # fake key fails
+- name: Install GPG key
+  gpg_import: key_id="0x3804BB82D39DC0E3" state=present
+
+- name: Install GPG key
+  gpg_import:
+    key_id: "0x3804BB82D39DC0E3"
+    bin_path: '/usr/local/bin/gpg'
+
+- name: Install or update GPG key
+  gpg_import:
+    key_id: "0x3804BB82D39DC0E3"
+    state: latest
+    servers:
+      - 'hkp://no.way.ever'
+      - 'keys.gnupg.net'
+      - 'hkps://hkps.pool.sks-keyservers.net'
+
+- name: Install or fail with fake and not fake GPG keys
+  gpg_import:
+    key_id: "{{ item }}"
+    tries: 2
+  with_items:
+    - "0x3804BB82D39DC0E3"
+    - "0x3804BB82D39DC0E4" # fake key fails
+
+- name: import a file-based public key
+  gpg_import: key_type=public state=present key_file=/etc/customer-key/customer.pubkey
+
+- name: import a file-based private key
+  gpg_import: key_type=private state=present key_file=/etc/customer-key/customer.privatekey
 ```
 
 ### options
 name         | default            | description
 -------------|:------------------:|-------------
-state        | 'present'          | desired state 'present', 'latest', 'refreshed' or 'absent' ('refreshed' == 'latest')
-servers      | [ keys.gnupg.net ] | list of hostnames (or `hkp://`/`hkps://` urls) to try
-tries        |   3                | number of attempts per *server*
-delay        |  0.5               | delay between retries
-gpg_timeout  | 5                  | `gpg --keyserver-options timeout=5 ...`
+key_id       | null               | The id of the key to be fetched and imported. Only applicable to public keys. Either key_file or key_id is required.
+key_file     | null               | Filename of key to be imported. Must be on remote machine, not local. Either key_file or key_id is required.
+key_type     | 'private'          | What type of key to import. Only applicable to key_file
 bin_path     | /usr/bin/gpg       | Location of gpg binary
+state        | 'present'          | Desired state 'present', 'latest', 'refreshed' or 'absent' ('refreshed' == 'latest')
+servers      | [ keys.gnupg.net ] | List of hostnames (or `hkp://`/`hkps://` urls) to try
+tries        | 3                  | Number of attempts per *server*
+delay        | 0.5                | Delay between retries
+gpg_timeout  | 5                  | Timeout parameter for gpg
 
 [Strange behaviors](https://gist.github.com/tnt/eedaed9a6cc75130b9cb) occur when used with [insane keys](https://gist.github.com/tnt/70b116c72be11dc3cc66). But this is a gpg-problem.

gpg_import.py

@@ -18,19 +18,19 @@
 options:
   key_id:
     description:
-      - The id of the key to be fetched and imported. Only applicable to private keys (for now). Either key_file or key_id is required.
+      - The id of the key to be fetched and imported. Only applicable to public keys. Either key_file or key_id is required.
     required: false
     default: null
 
   key_file:
     description:
-      - Filename of key to be imported. Must be on remote machine, not local. Only applicable to public keys (for now). Either key_file or key_id is required.
+      - Filename of key to be imported. Must be on remote machine, not local. Either key_file or key_id is required.
     required: false
     default: null
 
   key_type:
     description:
-      - What type of key to import.
+      - What type of key to import. Only applicable to key_file
     required: true
     choices: [ "private", "public" ]
     default: "private"
@@ -81,6 +81,12 @@
 EXAMPLES = '''
 - name: Install GPG key
   gpg_import: key_id="0x3804BB82D39DC0E3" state=present
+
+- name: Install GPG key
+  gpg_import:
+    key_id: "0x3804BB82D39DC0E3"
+    bin_path: '/usr/local/bin/gpg'
+
 - name: Install or update GPG key
   gpg_import:
     key_id: "0x3804BB82D39DC0E3"
@@ -89,8 +95,14 @@
       - 'hkp://no.way.ever'
       - 'keys.gnupg.net'
       - 'hkps://hkps.pool.sks-keyservers.net'
+
 - name: Install or fail with fake and not fake GPG keys
   gpg_import:
+    key_id: "{{ item }}"
+    tries: 2
+  with_items:
+    - "0x3804BB82D39DC0E3"
+    - "0x3804BB82D39DC0E4" # fake key fails
 
 - name: import a file-based public key
   gpg_import: key_type=public state=present key_file=/etc/customer-key/customer.pubkey