1 files changed, 62 insertions, 0 deletions

diff --git a/roles/unix_users/subplot.md b/roles/unix_users/subplot.md
new file mode 100644
index 0000000..c7929e9
--- /dev/null
+++ b/roles/unix_users/subplot.md
@@ -0,0 +1,62 @@
+# Role `unix_users` – manage Unix users
+
+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
+  * `groups` – OPTIONAL: list of additional groups to which user
+    should be added
+  
+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
+given a host running Debian
+then the host has no user foo
+when I use role unix_users
+and I use variables from foo.yml
+and I run the playbook
+then the host has user foo
+and the user foo on host has encrypted password foopass
+and the user foo on host has shell /bin/true
+and the user foo on host has authorized_keys containing "ssh-rsa"
+and the user foo on host is in group operator
+~~~
+
+~~~{#foo.yml .file .yaml}
+unix_users_version: 2
+
+unix_users:
+- username: foo
+  comment: Foo Bar
+  shell: /bin/true
+  password: foopass
+  authorized_keys: |
+    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDKVaQfxzzwpwk763IcPBs308TpYYp6+NTOMvYaj3j3ewz8feYQg3lOlKo/5xaPug2ZywG6v6tpn/p0drovT5YAIPJitP7yJAfEzJe/gO7c9uwx0uIpe6cc8bwRG0XFdUVK0EneB6LpIec+3juj4zitGBm0ffIoLDhJ7J0daTzQN62rZaw/2SjSvgbfnu3a2BYRPz1NGiXdvOCbytVSLlUAR6SxNPrFdh/BJnS4umyDaBL/1j2yaw/WlkfZPn5Ni3USZLRcbHnBUUbo64iwBwJabhdpeh0xLGTqDkaeudUgZjlrRHFyCbwJTPtDzJsPLb5HKGGzdXPHP7Lk6PM2CIOz liw@exolobe1
+  groups: [operator]
+~~~