docs: add module documenation

2025-07-10 02:07:55 -04:00 · 2025-07-10 02:07:55 -04:00 · 117f19bec7
commit 117f19bec7
parent 55ba4275ee
5 changed files with 471 additions and 25 deletions
--- a/roles/nfs_server/README.md
+++ b/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
--- a/roles/os_base/README.md
+++ b/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:
-      - sudo
-      - wheel
-    comment: 'Jzn42.net maintenance user'
-    create_home: true
-    sshkey_state: 'present'
+    groups: [sudo, wheel]
+    comment: "Maintenance user"
+    sshkey_state: present
    sshkeys:
-      - ssh-ed25519 AAA...
+      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... maint@jumpbox
    permissions: &maint_permissions
      - sudo
      - sudo_nopass
      - libvirt

-  - name: jez·
-    state: 'present'
+  - name: john
    uid: 1001
-    groups:
-      - sudo
-      - wheel
-    comment: 'Jzn42 admin'
-    create_home: true
-    sshkey_state: 'present'
+    groups: [sudo, wheel]
+    comment: "Primary admin"
    sshkeys:
-      - ssh-ed25519 AAA...
-      - ssh-ed25519 AAA...
+      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... john@laptop
+      - 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
 ```
--- a/roles/os_disks/README.md
+++ b/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:
- Provides a VM disk detection helper
+### Removing logical volumes
+```yaml
+disks_lv:
+  - lv: old_data
+    vg: data
+    size: 10G
+    state: absent  # Will unmount and destroy the LV
+```
--- a/roles/os_tweaks/README.md
+++ b/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]
--- a/roles/os_update/README.md
+++ b/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