add docs

roles/users/README.md

@@ -0,0 +1,109 @@
+# Users
+Ansible roles to create/configure users on Linux/FreeBSD.
+
+## Variables 
+| user_groups  |                                               |                |
+| ---:         |---                                            |---             |
+| name         | name of the group                             | Data type      |
+| gid          | Optionally set the group ID                   | int            |
+| state        | whether the group shoud be created or removed | present/absent |
+
+
+| users            |   |    |
+| ---:             |---| ---|
+| _variable name_  | Description                                   | Data type       | 
+| name             | username                                      | string          |
+| state            | whether the user should be created or removed | present/absent  |
+| password         | string of an encrypted value(1)               | string          |
+| groups           | additional groups the user should belong to   | list            |
+| uid              | optionally specify a user id                  | int             |
+| keys             | list of dictionaries                          | list            |
+| shell_lines      | list of dictionaries                          | list            |
+
+(1) https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-generate-crypted-passwords-for-the-user-module
+## Default variables
+The default shells depending on the OS are:
+
+- Linux: `/bin/bash`
+- FreeBSD: `/bin/cshrc`
+
+This is defined in the `defaults` section of the **users** role
+
+
+## Example inventory
+```
+user_groups:
+  - name: mygroup
+    gid: 700
+
+
+users:
+  - name: remember
+    state: present
+    password: "blabla"
+    groups:
+      - mygroup
+    uid: 1100
+    keys:
+      - file: key1
+        state: present
+    shell_lines:
+      - line: "export SSH_AUTH_SOCK=$HOME/.gnupg/S.gpg-agent.ssh"
+        state: present
+      - line: "alias ls='ls lah'"
+        state: present
+  - name: test
+    keys:
+      - file: key2
+        state: absent
+    shell_lines:
+      - line: "export SSH_AUTH_SOCK=$HOME/.gnupg/S.gpg-agent.ssh"
+        state: absent
+```
+## Using the Role
+### Example Playbook
+```
+---
+- name: Manage user configuration
+  hosts: all
+  remote_user: root
+  roles:
+    - users
+```
+### Configure a user's ssh keys
+For every user a directory matching the username should be created under the _keys_ folder in the role's _files_ folder. In this folder the user's ssh keys can be stored.
+
+```
+├── files
+│   └── keys
+│       ├── remember
+│       │   └── key1.pub
+│       └── test
+│           └── key2.pub
+```
+The name of the file holding the key should match the name in the _users_ variable
+
+```
+    keys:
+      - file: key1
+        state: present
+```
+
+### Configure a user's shell
+This role allows you to add or remove lines to a user's `.bashrc` or `cshrc` file. Since this is not based on a template that overwrites the complete file, users can still add their own configuration too.
+
+Add items to the **shell_lines** key in the **users** variable. Each item exists of a _line_ and _state_ key.
+
+Example:
+```
+shell_lines:
+  - line: "testline"
+    state: absent
+  - line: "export SSH_AUTH_SOCK=$HOME/.gnupg/S.gpg-agent.ssh"
+    state: present
+  - line: "alias ls='ls lah'"
+    state: present
+```
+
+
+

roles/users/tasks/users.yml

@@ -16,7 +16,7 @@
     uid: "{{ item.uid | default(omit) }}"
     shell: "{{ item.shell | default(default_shell) }}"
     append: yes
-    #no_log: True
+    no_log: True
   with_items: "{{ users }}"