docs(README): add further details

README.md

@@ -1,22 +1,186 @@
-# unix_users
+# volker-raschek.unix-users
 
-[![Ansible Role](https://img.shields.io/ansible/role/d/59132)](https://galaxy.ansible.com/volker_raschek/unix_users)
+![Ansible Role](https://img.shields.io/ansible/role/d/volker-raschek/unix-users)
 
-With following role can be unix users and groups configured.
+The ansible role `volker-raschek.unix-users` create and manage users on Linux based distributions. For example for Arch
+Linux, Fedora and Ubuntu. Furthermore, the role can also be used to create groups, `~/.forward`, `~/.netrc` and to
+manage the `~/.ssh` directory.
 
-## Supported distributions
+## Examples
 
-- Arch Linux
-- Ubuntu 20.04
+> [!NOTE]
+> A complete list of all parameters can be found [below](#parameters).
 
-## Features
+### User and group
 
-- Setting up unix users and groups
-- Setting up private and public ssh keys
-- Setting up private and public gpg keys
-- Setting up .forward file for postfix
+The following example create the user `toor` and group `toor`. Booth with a specific id.
 
-## Configuring
+```yaml
+unix_groups:
+  toor:
+    gid: "1001"
+    state: present
 
-In the default directory are examples how to configure the role. Copy the
-defaults into your `host_vars` or `group_vars` and adapt the examples.
+unix_users:
+  toor:
+    state: present
+    name: Toor
+    uid: "1000"
+    home: /home/toor
+    shell: /bin/bash
+    password: toor
+    group: toor
+```
+
+### Btrfs home dir
+
+Optionally, the home directory of a user can also be created as dedicated btrfs subvolume. This make it possible to
+create snapshots of the home directory, for example via `btrbk`.
+
+```yaml
+unix_users:
+  toor:
+    state: present
+    name: Toor
+    uid: "1000"
+    home: /home/toor
+    btrfs: true
+    shell: /bin/bash
+    password: toor
+    group: toor
+```
+
+### .netrc
+
+The ansible role supports the creation and management of the `.netrc` file in a user's home directory. The `.netrc` file
+for the user `toor` is created below. This contains entries for GitHub.
+
+```yaml
+unix_users:
+  toor:
+    state: present
+    name: Toor
+    uid: "1000"
+    home: /home/toor
+    netrc:
+    - machine: github.com
+      login: octocat
+      password: pat_12345
+    - machine: api.github.com
+      login: octocat
+      password: pat_12345
+    shell: /bin/bash
+    password: toor
+    group: toor
+```
+
+### .ssh
+
+The SSH client directory `~/.ssh` can also be managed via the Ansible role. This supports the creation and management of
+`~/.ssh/config`, `~/.ssh/authorized_keys` as well as the maintenance of private and public SSH keys.
+
+The following example create two entries in `~/.ssh/authorized_keys`. One normal SSH access for `claire`. If `bob`
+establish a SSH connection the command `/usr/local/bin/upload-file.sh` will be executed and exited.
+
+The private key `toor@toor-pc.ed25519.key` must be stored in `ssh/private_keys`. The public key will be automatically
+extracted from the private key.
+
+The public keys `claire@claire-pc.pub` as well as `bob@bob-pc.pub` must be stored in `ssh/authorized_keys`.
+
+```yaml
+unix_users:
+  toor:
+    state: present
+    name: Toor
+    uid: "1000"
+    home: /home/toor
+    ssh:
+      config:
+      - Host: "*"
+        StrictHostKeyChecking: "no"
+        UserKnownHostFile: /dev/null
+      authorized_keys:
+      - filename: claire@claire-pc.pub
+      - command: /usr/local/bin/upload-file.sh
+        filename: bob@bob-pc.pub
+      private_keys:
+      - toor@toor-pc.ed25519.key
+    shell: /bin/bash
+    password: toor
+    group: toor
+```
+
+### .forward
+
+If on the system is postfix installed, postfix will respect the `~/.forward`
+[file](https://www.postfix.org/local.8.html). This allows to forward local emails to external email addresses. The
+following example create the `~/.forward` file for `toor` to forward emails to `toor@company.example.local`.
+
+```yaml
+unix_users:
+  toor:
+    state: present
+    name: Toor
+    uid: "1000"
+    home: /home/toor
+    email: toor@company.example.local
+    shell: /bin/bash
+    password: toor
+    group: toor
+```
+
+### shell_rc files
+
+The role also supports the creation of bashrc drop-in files. These are created in `~/.bashrc.d` and included by
+`~/.bashrc` via `source`.
+
+Program-related configurations can be made via a drop-in file. For example, the configuration of the bash history via
+the environment variables `HISTCONTROL` or `HISTFILE`. In addition to environment variables, aliases and complete
+functions can also be defined.
+
+```yaml
+unix_users:
+  toor:
+    state: present
+    name: Toor
+    uid: "1000"
+    home: /home/toor
+    email: toor@company.example.local
+    shell: /bin/bash
+    shell_rc_files:
+    - file: "/home/toor/.bashrc.d/10-docker.bashrc" # absolute or relative path to home dir
+      aliases:
+      - key: "dcd"
+        value: "docker-compose down"
+      envs:
+      - export: true
+        key: "PATH"
+        value: "/home/toor/workspace/docker-compose/bin:${PATH}" # Add local compiled docker-compose into $PATH
+      functions:
+      - name: "foo"
+        value: |
+          if ! which docker 1> /dev/null; then
+            echo "ERROR: docker not found" 1>&2
+            exit 1
+          fi
+    password: toor
+    group: toor
+```
+
+## Further ansible roles
+
+This ansible role is used in combination with other ansible roles of `volker-raschek`. You can search for the other
+ansible roles via the following command.
+
+```bash
+$ ansible-galaxy role search --author "volker-raschek"
+
+Found roles matching your search:
+
+ Name                      Description
+ ----                      -----------
+ volker-raschek.bind9      Role to install and configure bind9 on different distributions
+ volker-raschek.dhcpd      Role to install and configure dhcpd on different distributions
+ volker-raschek.renovate   Role to configure renovate as container image
+ ...
+```

meta/main.yml

@@ -1,5 +1,5 @@
 galaxy_info:
-  namespace: volker_raschek
+  namespace: volker-raschek
   role_name: "unix_users"
   author: "Markus Pesch"
   description: "Role to create and configure unix users and groups"