add docs

README.md

@@ -1,57 +1,9 @@
-# Users
+# Users and ssh-configAnsible roles
-Ansible role to create/configure users on Linux/FreeBSD 
+This repo contains 2 roles:
 
-## Variables
+- **users**: Add users and configure `.bashrc` and `authorized_keys`
-| user_groups |   |
+- **ssh-config**: Configures a user's `~/.ssh/config`
-| ---         |---| 
-| name        | name of the group                             |
-| gid         | group ID                                      |   
-| state       | whether the group shoud be created or removed |
-| users       |
 
-## Default variables
+Both roles make use of the same _users_ variable and are created to give users the freedom to add their own configuration outside of Ansible.
-The default shells depending on the OS are:
 
-- Linux: `/bin/bash`
+Detailed configuration can be found in the README files inside the role's folders.
-- FreeBSD: `/bin/cshrc`
-
-This is defined in the `defaults` section of the **users roles**
-
-
-## Example Playbook
-
-```
-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
-### Adding user
-
-### Configure users' shell
-
-https://github.com/stationgroup/ansible-experiments/issues/9

group_vars/all

@@ -33,6 +33,3 @@ users:
     shell_lines:
       - line: "export SSH_AUTH_SOCK=$HOME/.gnupg/S.gpg-agent.ssh"
         state: present
-#    ssh_config:
-#      - host: "{{ ansible_hostname }}"
-#        hostname: "{{ ansible_hostname }}"

roles/ssh-config/README.md

@@ -0,0 +1,89 @@
+# ssh-config
+Ansible role to configure a user's `~/.ssh/config` file. This will add a
+configuration in the ssh config file for each host in the inventory.
+
+**NOTE: this role works in conjunction with the _users_ variable**
+
+## Variables 
+
+| _variable name_   | Description                                   | 
+| ---:            |---                                            |
+| ssh_short_name  | host identifier name in the ssh config.<br>This should be added to the _host variables_  |
+| ssh_config      | name of the key in the *users* variable. Contains a list of
+key/value items| 
+
+## Example:
+
+**Host inventory**
+```
+10.106.116.157 ssh_short_name=host1
+10.106.116.139 ssh_short_name=host2
+```
+
+**Variables**
+populate the *ssh_config* key.
+```
+users:
+  - name: remember
+    state: present
+    password: "blabla"
+    groups:
+      - mygroup
+    uid: 1100
+    keys:
+      - file: key1
+        state: present
+    shell_lines:
+      - line: "testline"
+        state: present
+      - line: "export SSH_AUTH_SOCK=$HOME/.gnupg/S.gpg-agent.ssh"
+        state: present
+      - line: "alias ls='ls lah'"
+        state: present
+    ssh_config:
+      - ServerAliveInterval: 10
+```
+
+**Result:**
+```
+# BEGIN ANSIBLE MANAGED BLOCK
+Host host1
+    Hostname 10.106.116.157
+    RemoteForward /home/remember/.gnupg/S.gpg-agent $HOME/.gnupg/S.gpg-agent
+    RemoteForward /home/remember/.gnupg/S.gpg-agent.ssh $HOME/.gnupg/S.gpg-agent.ssh
+    ServerAliveInterval 10
+Host host2
+    Hostname 10.106.116.139
+    RemoteForward /home/remember/.gnupg/S.gpg-agent $HOME/.gnupg/S.gpg-agent
+    RemoteForward /home/remember/.gnupg/S.gpg-agent.ssh $HOME/.gnupg/S.gpg-agent.ssh
+    ServerAliveInterval 10
+# END ANSIBLE MANAGED BLOCK
+
+```
+
+**Break down**
+
+The host identifier is populated with the `ssh_short_name` host variable.
+```
+Host host1
+```
+
+The `Hostname` is populated with the `inventory_hostname` variable
+```
+Hostname 10.106.116.139
+```
+
+These lines are added by default:
+```
+RemoteForward /home/remember/.gnupg/S.gpg-agent $HOME/.gnupg/S.gpg-agent
+RemoteForward /home/remember/.gnupg/S.gpg-agent.ssh $HOME/.gnupg/S.gpg-agent.ssh
+```
+
+Everything below this is populated with the key/values defined in the
+`ssh_config` list of the `users` variable
+
+```
+ServerAliveInterval 10
+```
+
+

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 }}"