docs: add module documenation

roles/nfs_client/tasks/main.yml

@@ -2,9 +2,10 @@
 
 - name: Display nfs_client role
   ansible.builtin.debug:
-    var: base_config
+    var: role_config
+    verbosity: 0
   vars:
-    base_config:
+    role_config:
       nfs_mounts: "{{ nfs_mounts }}"
       tasks:
         - Ensure nfs-client packages are installed

roles/nfs_server/README.md

@@ -0,0 +1,106 @@
+# NFS Server Role
+
+This role configures an NFS server on Debian-based systems. It installs the necessary packages, configures NFS exports, and manages the NFS service.
+
+## What it does
+
+- Installs NFS server packages (`nfs-common`, `nfs-kernel-server`)
+- Configures `/etc/exports` with templated NFS shares
+- Restarts the NFS kernel server when configuration changes
+- Provides debug output showing the configuration being applied
+
+## Variables
+
+### Required Variables
+
+| Variable | Type | Description | Example |
+|----------|------|-------------|---------|
+| `nfs_shares` | list | List of NFS share configurations | See examples below |
+
+### NFS Share Configuration
+
+Each item in `nfs_shares` should be a dictionary with the following keys:
+
+| Key | Type | Required | Description | Example |
+|-----|------|----------|-------------|---------|
+| `path` | string | Yes | Local filesystem path to export | `/srv/nfs4` |
+| `allow` | string | Yes | Client access specification | `192.168.1.0/24` |
+| `options` | string | Yes | NFS export options | `rw,sync,no_subtree_check` |
+| `desc` | string | No | Description comment for the export | `Home directories` |
+
+## Examples
+
+### Basic NFS Server Setup
+
+```yaml
+- hosts: nfs_servers
+  roles:
+    - nfs_server
+  vars:
+    nfs_shares:
+      - path: /srv/nfs4
+        allow: 192.168.1.0/24
+        options: rw,sync,no_subtree_check
+        desc: "Main NFS share"
+```
+
+### Multiple Shares with Different Access
+
+```yaml
+- hosts: nfs_servers
+  roles:
+    - nfs_server
+  vars:
+    nfs_shares:
+      - path: /srv/nfs4/homes
+        allow: 192.168.1.0/24
+        options: rw,sync,no_subtree_check
+        desc: "User home directories"
+      - path: /srv/nfs4/public
+        allow: 192.168.1.0/24
+        options: ro,sync,no_subtree_check
+        desc: "Public read-only share"
+      - path: /srv/nfs4/backup
+        allow: 10.0.0.5
+        options: rw,sync,no_subtree_check
+        desc: "Backup server access"
+```
+
+### NFSv4 with Kerberos Authentication
+
+```yaml
+- hosts: nfs_servers
+  roles:
+    - nfs_server
+  vars:
+    nfs_shares:
+      - path: /srv/nfs4
+        allow: gss/krb5i
+        options: rw,sync,fsid=0,crossmnt,no_subtree_check
+        desc: "NFSv4 with Kerberos authentication"
+```
+
+## Generated Configuration
+
+The role generates an `/etc/exports` file with entries like:
+
+```
+# Managed by Ansible
+# /etc/exports: the access control list for filesystems which may be exported
+#               to NFS clients.  See exports(5).
+
+# Main NFS share
+/srv/nfs4  192.168.1.0/24(rw,sync,no_subtree_check)
+
+# User home directories
+/srv/nfs4/homes  192.168.1.0/24(rw,sync,no_subtree_check)
+```
+
+## Dependencies
+
+- Debian-based system (Ubuntu, Debian, etc.)
+- Ansible 2.9+
+
+## Tags
+
+- `config_show`: Shows the configuration being applied

roles/os_base/README.md

@@ -1,37 +1,107 @@
-# OS Base
+# OS Base Role
 
-Example config:
+Configures fundamental system settings for Debian-based systems including hostname, user accounts, SSH keys, package management, and sudo access.
+
+## What it does
+
+This role performs the following system configuration tasks:
+
+- **System Identity**: Sets hostname, domain, and FQDN
+- **User Management**: Creates system and regular users with specified UIDs, groups, and home directories
+- **SSH Access**: Deploys authorized SSH keys for users
+- **Package Management**: Configures APT preferences and installs base packages
+- **Sudo Configuration**: Sets up wheel group with passwordless sudo access
+- **Security Groups**: Ensures wheel and sudo groups exist
+
+## Variables
+
+### Required Variables
+
+| Variable | Type | Description | Default |
+|----------|------|-------------|---------|
+| `system_accounts` | list | List of user accounts to create | `[]` |
+| `system_packages` | list | List of packages to install | `[]` |
+
+### Optional Variables
+
+| Variable | Type | Description | Default |
+|----------|------|-------------|---------|
+| `system_hostname` | string | System hostname | `inventory_hostname` first part |
+| `system_domain` | string | System domain name | `inventory_hostname` remaining parts |
+| `system_fqdn` | string | Full qualified domain name | `system_hostname.system_domain` |
+| `system_packages_norecommend` | bool | Disable APT recommended packages | `false` |
+| `system_packages_nosuggest` | bool | Disable APT suggested packages | `false` |
+
+### System Account Configuration
+
+Each account in `system_accounts` supports these properties:
+
+| Property | Type | Description | Default |
+|----------|------|-------------|---------|
+| `name` | string | Username (required) | - |
+| `state` | string | User state: present/absent | `present` |
+| `system` | bool | Create as system user | `false` |
+| `uid` | int | User ID | auto-assigned |
+| `groups` | list | User groups | `[]` |
+| `comment` | string | User description | - |
+| `shell` | string | Login shell | `/bin/bash` |
+| `home` | string | Home directory | `/home/{{ name }}` |
+| `create_home` | bool | Create home directory | `true` |
+| `sshkey_state` | string | SSH key state: present/absent | `present` |
+| `sshkeys` | list | List of SSH public keys | `[]` |
+| `permissions` | list | Special permissions | `[]` |
+
+### Supported Permissions
+
+- `sudo`: Add user to sudo group (password required)
+- `sudo_nopass`: Add user to wheel group (passwordless sudo)
+- `libvirt`: Add user to libvirt group
+
+## Examples
+
+### Basic Configuration
+
+```yaml
+system_accounts:
+  - name: admin
+    uid: 1000
+    groups: [sudo, wheel]
+    comment: "System Administrator"
+    sshkeys:
+      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... admin@workstation
+
+system_packages:
+  - htop
+  - vim
+  - git
+  - curl
 ```
+
+### Advanced User Setup
+
+```yaml
 system_accounts:
   - name: sysmaint
-    state: 'present'
+    state: present
     system: true
     uid: 1000
-    groups:
+    groups: [sudo, wheel]
-      - sudo
+    comment: "Maintenance user"
-      - wheel
+    sshkey_state: present
-    comment: 'Jzn42.net maintenance user'
-    create_home: true
-    sshkey_state: 'present'
     sshkeys:
-      - ssh-ed25519 AAA...
+      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... maint@jumpbox
     permissions: &maint_permissions
       - sudo
       - sudo_nopass
       - libvirt
 
-  - name: jez·
+  - name: john
-    state: 'present'
     uid: 1001
-    groups:
+    groups: [sudo, wheel]
-      - sudo
+    comment: "Primary admin"
-      - wheel
-    comment: 'Jzn42 admin'
-    create_home: true
-    sshkey_state: 'present'
     sshkeys:
-      - ssh-ed25519 AAA...
+      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... john@laptop
-      - ssh-ed25519 AAA...
+      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... john@desktop
     permissions: *maint_permissions
 
 system_packages:
@@ -43,4 +113,27 @@ system_packages:
   - rsync
   - bash
 
+system_packages_norecommend: true
+system_packages_nosuggest: true
+```
+
+### Custom Hostname Configuration
+
+```yaml
+system_hostname: "webserver"
+system_domain: "example.com"
+system_fqdn: "webserver.example.com"
+
+system_accounts:
+  - name: webadmin
+    uid: 1000
+    groups: [sudo]
+    comment: "Web server administrator"
+    sshkeys:
+      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... webadmin@deploy
+
+system_packages:
+  - nginx
+  - certbot
+  - fail2ban
 ```

roles/os_base/defaults/main.yml

@@ -9,3 +9,8 @@ system_packages__default: []
 system_accounts: "{{ vars | dict2items | selectattr('key', 'match', '^system_accounts__.*') | map(attribute='value') |     list | flatten | unique }}"
 system_packages: "{{ vars | dict2items | selectattr('key', 'match', '^system_packages__.*') | map(attribute='value') |     list | flatten | unique }}"
 
+# system_hostname: "{{ ansible_hostname }}"
+system_hostname: "{{ inventory_hostname | split('.') | first }}"
+system_domain: "{{ (inventory_hostname | split('.'))[1:] | join('.') }}"
+# system_domain: "lan.test"
+system_fqdn: "{{ system_hostname }}.{{ system_domain }}"

roles/os_base/tasks/main.yml

@@ -2,12 +2,17 @@
 
 - name: Display os_base role
   ansible.builtin.debug:
-    var: base_config
+    var: role_config
+    verbosity: 1
   vars:
-    base_config:
+    role_config:
       system_accounts: "{{ system_accounts }}"
       system_packages: "{{ system_packages }}"
+      system_hostname: "{{ system_hostname }}"
+      system_domain: "{{ system_domain }}"
+      system_fqdn: "{{ system_fqdn }}"
       tasks:
+        - "Configure system hostname, domain and fqdn"
         - Ensure system security groups are present
         - Create system users from system_accounts
         - Ensure ssh keys are correctly deployed
@@ -17,6 +22,23 @@
   tags:
     - config_show
 
+# Configure system fqdn
+# ==========================
+- name: Configure system hostname in /etc/hosts
+  ansible.builtin.lineinfile:
+    path: /etc/hosts
+    regexp: '^127\.0\.1\.1 '
+    line: '127.0.1.1 {{ system_fqdn }} {{ system_hostname }}'
+    state: present
+  register: machine_name_changed
+
+- name: "Apply system hostname (changed={{ machine_name_changed.changed }})"
+  ansible.builtin.shell:
+    cmd: "test '{{ ansible_check_mode|lower }}' == true || hostnamectl set-hostname {{ system_fqdn }}"
+  when: machine_name_changed.changed
+  changed_when: true
+  check_mode: false
+
 
 # Configure groups and users
 # ==========================
@@ -29,6 +51,8 @@
   loop:
     - wheel
     - sudo
+  loop_control:
+    label: "Install package: {{ item }}"
 
 - name: Create users
   user:
@@ -37,26 +61,33 @@
     groups: "{{ item.groups | default([]) }}"
     state: "{{ item.state | default('present') }}"
     shell: "{{ item.shell | default('/bin/bash') }}"
-    system: "{{ item.system | default(False) }}"
+    system: "{{ _system }}"
     comment: "{{ item.comment | default(omit) }}"
     createhome: true
     home: "{{ item.home | default('/home/' + item.name ) }}"
     uid: "{{ item.uid | default(omit) }}"
   loop: "{{ system_accounts }}"
+  loop_control:
+    label: "Create {{ _system | ternary('system', 'regular')  }} user: {{ item.name }} ({{ item.uid }}, {{item.comment|d('No comments')}}"
+  vars:
+    _system: "{{ item.system | default(False) }}"
 
 - name: Deploy all ssh keys
   ansible.posix.authorized_key:
-    user: "{{ user_name }}"
+    user: "{{ _user_name }}"
-    state: "{{ sshkey_state }}"
+    state: "{{ _sshkey_state }}"
-    key: "{{ sshkey }}"
+    key: "{{ _sshkey }}"
     follow: true
-    path: "{{ home_dir }}/.ssh/authorized_keys"
+    path: "{{ _home_dir }}/.ssh/authorized_keys"
   loop: "{{ system_accounts|selectattr('sshkeys', 'defined') | subelements('sshkeys') }}"
+  loop_control:
+    label: "Deploy '{{ _user_name }}' public key: {{ _sshkey_comment }}"
   vars:
-    user_name: "{{ item.0.name }}"
+    _user_name: "{{ item.0.name }}"
-    home_dir: "{{ item.0.home | default('/home/' + item.0.name ) }}"
+    _home_dir: "{{ item.0.home | default('/home/' + item.0.name ) }}"
-    sshkey_state: "{{ item.0.sshkey_state | default('present') }}"
+    _sshkey_state: "{{ item.0.sshkey_state | default('present') }}"
-    sshkey: "{{ item.1 }}"
+    _sshkey: "{{ item.1 }}"
+    _sshkey_comment: "{{ _sshkey | split(' ') | last }}"
 
 
 # Configure package manager
@@ -73,6 +104,8 @@
     - name: 02-suggest
       content: |
         APT::Install-Suggests "{{ system_packages_nosuggest | bool | ternary(0, 1) }}";
+  loop_control:
+    label: "Ensure APT preference: {{ item.content }}"
 
 - name: Install base tools
   package:
@@ -98,6 +131,8 @@
     groups:
       - sudo
   with_items: "{{ system_accounts }}"
+  loop_control:
+    label: "Add user to sudo group: {{ item.name }}"
   when: "'sudo' in perm"
   vars:
     perm: "{{ item.permissions | default([]) }}"

roles/os_disks/README.md

@@ -1,20 +1,98 @@
-# OS Disk
+# OS Disk Role
 
-Prepare LVM disks. Configuration example:
+Manages LVM (Logical Volume Management) setup for Debian systems, including volume groups, logical volumes, filesystem creation, and mounting.
 
+## What it does
+
+This role:
+- Installs LVM2 and parted packages
+- Deploys a disk detection script (`setup_lvm_devices.sh`) for automatic device initialization
+- Creates and manages volume groups (VGs) from physical devices
+- Creates logical volumes (LVs) with specified sizes
+- Formats logical volumes with filesystems
+- Mounts logical volumes and adds entries to `/etc/fstab`
+
+## Variables
+
+### `disks_vg` (list)
+List of volume group configurations.
+
+**Structure:**
+```yaml
+disks_vg:
+  - vg: string          # Volume group name
+    state: string       # present (default) | absent
+    devices_dev: list   # List of device paths (e.g., ['/dev/vda', '/dev/vdb'])
 ```
+
+### `disks_lv` (list)
+List of logical volume configurations.
+
+**Structure:**
+```yaml
+disks_lv:
+  - lv: string          # Logical volume name
+    vg: string          # Volume group name (must exist in disks_vg)
+    size: string        # Size with unit (e.g., '20G', '500M')
+    state: string       # present (mounted) | absent (destroyed)
+    fstype: string      # Filesystem type (default: ext4)
+```
+
+**Notes:**
+- Mount path is automatically derived from LV name: `/{{ lv | replace('_', '/') }}`
+- Example: LV name `var_lib_docker` mounts to `/var/lib/docker`
+
+## Examples
+
+### Basic LVM setup with single volume group
+```yaml
+disks_vg:
+  - vg: data
+    devices_dev:
+      - /dev/vda
+      - /dev/vdb
+
+disks_lv:
+  - lv: var_lib_docker
+    vg: data
+    size: 20G
+    fstype: ext4
+  - lv: var_log
+    vg: data
+    size: 5G
+    fstype: xfs
+```
+
+### Multiple volume groups with different states
+```yaml
 disks_vg:
   - vg: data
     state: present
     devices_dev:
       - /dev/vda
+  - vg: backup
+    state: present
+    devices_dev:
+      - /dev/vdc
+
 disks_lv:
   - lv: var_lib_docker
     vg: data
     size: 20G
-    state: # present (mounted), absent (destroyed)
+    state: present
+    fstype: ext4
+  - lv: backup_storage
+    vg: backup
+    size: 100G
+    state: present
     fstype: ext4
 ```
 
-Note:
+### Removing logical volumes
-- Provides a VM disk detection helper
+```yaml
+disks_lv:
+  - lv: old_data
+    vg: data
+    size: 10G
+    state: absent  # Will unmount and destroy the LV
+```

roles/os_disks/tasks/main.yml

@@ -2,9 +2,10 @@
 
 - name: Display os_disks role
   ansible.builtin.debug:
-    var: disk_config
+    var: role_config
+    verbosity: 0
   vars:
-    disk_config:
+    role_config:
       disks_vg: "{{ disks_vg }}"
       disks_lv: "{{ disks_lv }}"
       tasks:

roles/os_systemd_networkd/tasks/main.yml

@@ -3,6 +3,7 @@
 - name: Display os_systemd_networkd role
   ansible.builtin.debug:
     var: role_config
+    verbosity: 1
   vars:
     role_config:
       systemd_networkd_conf_directory: "{{ systemd_networkd_conf_directory }}"

roles/os_tweaks/README.md

@@ -0,0 +1,95 @@
+# OS Tweaks Role
+
+Configures essential system tools and development environment settings on Debian-based systems.
+
+## Description
+
+This role installs and configures common development and system administration tools with optimized settings:
+
+- **System packages**: vim, htop, iftop, iotop, bash-completion
+- **Bash configuration**: Enhanced prompt with colors, aliases, and useful functions
+- **Git configuration**: Global git settings with aliases and color schemes
+- **Vim configuration**: Basic editor settings with syntax highlighting and proper indentation
+
+## Variables
+
+This role doesn't define any variables. All configurations are applied using predefined files.
+
+## Files Deployed
+
+| File | Purpose | Location |
+|------|---------|----------|
+| `bash_profile` | Enhanced bash environment with colored prompt, aliases, and utility functions | `/etc/profile.d/bash_tweaks.sh` |
+| `gitconfig` | Global git configuration with aliases and color schemes | `/etc/gitconfig` |
+| `vimrc` | Vim editor settings with syntax highlighting and proper indentation | `/etc/vim/vimrc.local` |
+
+## Examples
+
+### Basic Usage
+
+```yaml
+- name: Apply OS tweaks
+  hosts: all
+  roles:
+    - mrjk.debian.os_tweaks
+```
+
+### With Tags
+
+```yaml
+- name: Apply OS tweaks with specific tags
+  hosts: all
+  roles:
+    - role: mrjk.debian.os_tweaks
+      tags:
+        - config_show
+        - os_tweaks
+```
+
+### In a Playbook
+
+```yaml
+- name: Configure development environment
+  hosts: dev_servers
+  become: yes
+  roles:
+    - mrjk.debian.os_tweaks
+  tasks:
+    - name: Verify bash configuration
+      command: source /etc/profile.d/bash_tweaks.sh
+      changed_when: false
+```
+
+## Features
+
+### Bash Enhancements
+- Colored prompt with disk usage indicators
+- Useful aliases and functions
+- Regex patterns for common text matching
+- Enhanced history and completion
+
+### Git Configuration
+- Color-coded output
+- Common aliases (st, br, co, etc.)
+- URL shortcuts (gh:, gist:, bb:)
+- Credential caching (24h)
+
+### Vim Settings
+- Syntax highlighting
+- Proper indentation (2 spaces)
+- Dark background theme
+- Disabled mouse support
+
+## Requirements
+
+- Debian-based system
+- Ansible 2.9+
+- Root or sudo privileges
+
+## Dependencies
+
+None.
+
+## License
+
+[Add your license information here]

roles/os_update/README.md

@@ -0,0 +1,74 @@
+# OS Update Role
+
+This role manages system updates on Debian-based systems using the `apt` package manager. It provides controlled system maintenance operations including package updates, upgrades, and cleanup.
+
+## What it does
+
+The role performs the following operations based on configuration:
+
+- **Autoremove**: Removes unused packages and dependencies
+- **Update**: Updates the package list and upgrades all packages to their latest versions
+- **Upgrade**: Performs a distribution upgrade (equivalent to `apt upgrade`)
+
+Each operation is controlled by boolean variables, allowing you to selectively enable or disable specific maintenance tasks.
+
+## Variables
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `os_apt_autoremove` | boolean | `false` | Whether to remove unused packages and dependencies |
+| `os_apt_update` | boolean | `true` | Whether to update package list and upgrade all packages |
+| `os_apt_upgrade` | boolean | `false` | Whether to perform a distribution upgrade |
+
+## Examples
+
+### Basic usage (update only)
+```yaml
+- name: Update system packages
+  hosts: debian_servers
+  roles:
+    - os_update
+```
+
+### Full system maintenance
+```yaml
+- name: Complete system maintenance
+  hosts: debian_servers
+  vars:
+    os_apt_autoremove: true
+    os_apt_update: true
+    os_apt_upgrade: true
+  roles:
+    - os_update
+```
+
+### Cleanup only
+```yaml
+- name: Clean up unused packages
+  hosts: debian_servers
+  vars:
+    os_apt_autoremove: true
+    os_apt_update: false
+    os_apt_upgrade: false
+  roles:
+    - os_update
+```
+
+### Distribution upgrade only
+```yaml
+- name: Perform distribution upgrade
+  hosts: debian_servers
+  vars:
+    os_apt_autoremove: false
+    os_apt_update: false
+    os_apt_upgrade: true
+  roles:
+    - os_update
+```
+
+## Notes
+
+- The role uses `apt` module which requires root privileges
+- `os_apt_update` performs both `apt update` and `apt upgrade` operations
+- `os_apt_upgrade` performs a distribution upgrade (equivalent to `apt upgrade`)
+- Operations are executed conditionally based on the boolean variables