unix_users: drop obsolete authkeys_dir variable, bump version

Also, document the variables in the subplot.

1 files changed, 30 insertions, 1 deletions

diff --git a/roles/unix_users/subplot.md b/roles/unix_users/subplot.md
index 78a7a48..2fde3e7 100644
--- a/roles/unix_users/subplot.md
+++ b/roles/unix_users/subplot.md
@@ -2,6 +2,35 @@
 
 This role creates or updates Unix users.
 
+## Configuration
+
+This role makes use of the following variables:
+
+* `unix_users_version` – MANDATORY: The playbook should set this
+  to the version of the role it expects to use.
+
+* `unix_users` – OPTIONAL: A list of Unix accounts to create.
+  Defaults to the empty list. Each item in the list is a dict with the
+  following keys:
+
+  * `username` – MANDATORY: the username of the account
+  * `comment` – OPTIONAL: the real name (or GECOS field) of the
+    new account
+  * `shell` – OPTIONAL: the login shell
+  * `system` – OPTIONAL: boolean, is this a system user?
+  * `sudo` – OPTIONAL: boolean, should the account have password-less sudo?
+  * `ssh_key` – OPTIONAL: text of key to install as `~/.ssh/id_rsa`
+  * `ssh_key_pub` – OPTIONAL: text of key to install as `~/.ssh/id_rsa.pub`
+  * `authorized_keys` – OPTIONAL: text of contents of
+    `~/.ssh/authorized_keys`
+  * `password` – OPTIONAL: encrypted password
+  
+Create the encrypted password with something like:
+
+~~~yaml
+password: "{{ lookup('pipe', 'pass show foo | mkpasswd --method=sha-512 --stdin') }}"
+~~~
+
 ## Create normal user with unix_users
 
 ~~~scenario
@@ -17,7 +46,7 @@ and the user foo on host has authorized_keys containing "ssh-rsa"
 ~~~
 
 ~~~{#foo.yml .file .yaml}
-unix_users_version: 0
+unix_users_version: 1
 
 unix_users:
 - username: foo