docs(README): remove dead link

.gitea/workflows/ansible-linters.yaml

@@ -14,7 +14,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Run ansible-lint
-      uses: ansible/ansible-lint@v25.4.0
+      uses: ansible/ansible-lint@v25.6.1
       with:
         args: "--config-file .ansible-lint"
         setup_python: "true"

.gitea/workflows/markdown-linters.yaml

@@ -13,6 +13,6 @@ jobs:
     - ubuntu-latest
     steps:
     - uses: actions/checkout@v4.2.2
-    - uses: DavidAnson/markdownlint-cli2-action@v19.1.0
+    - uses: DavidAnson/markdownlint-cli2-action@v20.0.0
       with:
         globs: '**/*.md'

.yamllint.yaml

@@ -1,3 +1,5 @@
+---
+
 #
 # Documentation:
 # https://yamllint.readthedocs.io/en/stable/

README.md

@@ -1,23 +1,183 @@
-# unix_users
+# volker-raschek.unix-users
 
-[![Build Status](https://drone.cryptic.systems/api/badges/volker.raschek/unix_users-role/status.svg)](https://drone.cryptic.systems/volker.raschek/unix_users-role)
+![Ansible Role](https://img.shields.io/ansible/role/d/volker-raschek/unix-users)
-[![Ansible Role](https://img.shields.io/ansible/role/d/59132)](https://galaxy.ansible.com/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
+### User and group
-- Ubuntu 20.04
 
-## Features
+The following example create the user `toor` and group `toor`. Booth with a specific id.
 
-- Setting up unix users and groups
+```yaml
-- Setting up private and public ssh keys
+unix_groups:
-- Setting up private and public gpg keys
+  toor:
-- Setting up .forward file for postfix
+    gid: "1001"
+    state: present
 
-## Configuring
+unix_users:
+  toor:
+    state: present
+    name: Toor
+    uid: "1000"
+    home: /home/toor
+    shell: /bin/bash
+    password: toor
+    group: toor
+```
 
-In the default directory are examples how to configure the role. Copy the
+### Btrfs home dir
-defaults into your `host_vars` or `group_vars` and adapt the examples.
+
+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
+ ...
+```

defaults/default.yml

@@ -25,6 +25,10 @@ unix_users: {}
 #       - alice@alice-pc.ed25519.key
 #     home: /home/alice
 #     btrfs: false
+#     netrc:
+#     - machine: hostame.local
+#       login: username
+#       password: password
 #     shell: /bin/bash
 #     shell_rc_files:
 #     - file: "/home/alice/.bashrc.d/docker.bashrc" # absolute or relative path to home dir

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"

tasks/create_unix_user.yml

@@ -195,3 +195,12 @@
   - "{{ unix_user.value.shell_rc_files }}"
   loop_control:
     loop_var: shell_rc_file
+
+- name: "Create .netrc file"
+  when: unix_user.value.netrc is defined and unix_user.value.netrc | length > 0
+  ansible.builtin.template:
+    src: netrc.j2
+    dest: "{{ user_user_home }}/.netrc"
+    owner: "{{ unix_user.key }}"
+    group: "{{ unix_user.value.group | default('users') }}"
+    mode: "0600"

templates/netrc.j2

@@ -0,0 +1,3 @@
+{% for netrc in unix_user.value.netrc %}
+machine {{ netrc.maschine }} login {{ netrc.login }} password {{ netrc.password }}
+{% endfor %}