docs: update README with full documentation
Add legacy-to-Ansible mapping table, host-class conditionals reference, AWX setup instructions, and configuration variable reference. 🤖 Generated with [Crush](https://github.com/charmassociates/crush) Assisted-by: GLM-5 via Crush <crush@charm.land>
This commit is contained in:
@@ -1,3 +1,121 @@
|
||||
# KNELConfigMgmt-Ansible
|
||||
# KNELConfigMgmt-Ansible (KNELIAC)
|
||||
|
||||
KNEL Configuration Management Collection Ansible
|
||||
Ansible configuration-management collection for the Known Element Enterprises
|
||||
fleet. This is the Ansible port of the legacy bash provisioning system that
|
||||
lives in `PFVCluster/provisioning/`, and is the project that **AWX**
|
||||
(`tsys-awx.knel.net`) syncs and executes.
|
||||
|
||||
**Target hosts:** Debian-family only (Debian, Ubuntu Server, Kali, Raspberry Pi OS).
|
||||
|
||||
---
|
||||
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
KNELIAC/
|
||||
├── ansible.cfg # ansible settings (roles_path, inventory, become)
|
||||
├── requirements.yml # external collections (currently none)
|
||||
├── inventory/
|
||||
│ ├── hosts.yml # host inventory (physical_hosts / virtual_guests / raspberry_pi)
|
||||
│ └── group_vars/all.yml # all tunable variables (mirrors hard-coded bash values)
|
||||
├── playbooks/
|
||||
│ ├── hello_world.yml # AWX smoke-test playbook
|
||||
│ └── setup_new_system.yml # full host build (port of SetupNewSystem.sh)
|
||||
└── roles/
|
||||
├── preflight # host-class detection (physical/raspi/virt/ubuntu/kali)
|
||||
├── oam # LibreNMS / check_mk agent
|
||||
├── packages # up2date, install fleet toolset, remove unwanted pkgs
|
||||
├── system_config # postfix, resolv, snmp, ntp, dhcp, lldpd, cockpit, zsh, shells
|
||||
├── security_ssh # sshd_config, authorized_keys, ssh-audit hardening
|
||||
├── security_wazuh # wazuh-agent install + hold
|
||||
├── security_scap_stig # GRUB perms, modprobe blacklist, banners, cron/at perms
|
||||
├── security_2fa # TOTP 2FA for SSH / Cockpit / Webmin
|
||||
└── security_audit # auditd, journald, logrotate
|
||||
```
|
||||
|
||||
## Legacy → Ansible mapping
|
||||
|
||||
| Legacy bash | KNELIAC role |
|
||||
|------------------------------------------------------|-------------------------|
|
||||
| `SetupNewSystem.sh` (runner) | `playbooks/setup_new_system.yml` |
|
||||
| `Project-Includes/PreflightCheck.sh` + `pi-detect.sh`| `roles/preflight` |
|
||||
| `Modules/OAM/oam-librenms.sh` | `roles/oam` |
|
||||
| `global-installPackages` + `scripts/up2date.sh` | `roles/packages` |
|
||||
| `global-systemServiceConfigurationFiles` + `global-postPackageConfiguration` | `roles/system_config` |
|
||||
| `Modules/Security/secharden-ssh.sh` | `roles/security_ssh` |
|
||||
| `Modules/Security/secharden-wazuh.sh` | `roles/security_wazuh` |
|
||||
| `Modules/Security/secharden-scap-stig.sh` | `roles/security_scap_stig` |
|
||||
| `Modules/Security/secharden-2fa.sh` | `roles/security_2fa` |
|
||||
| `Modules/Security/secharden-audit-agents.sh` | `roles/security_audit` |
|
||||
|
||||
## Getting started with AWX
|
||||
|
||||
1. **Create a Project** in AWX pointing at this git repo.
|
||||
2. **Create an Inventory** (either maintain hosts in AWX directly, or sync from
|
||||
`inventory/hosts.yml`).
|
||||
3. **Create a Job Template**:
|
||||
- Playbook: `playbooks/hello_world.yml`
|
||||
- Run it against any host to confirm AWX can reach, become root, and gather
|
||||
facts. A green run = the pipeline works.
|
||||
4. For the full build, create a second Job Template with playbook
|
||||
`playbooks/setup_new_system.yml`. Each phase is gated by a `run_*` toggle
|
||||
(see `inventory/group_vars/all.yml`), so you can enable phases incrementally.
|
||||
|
||||
## Configuration
|
||||
|
||||
All knobs live in [`inventory/group_vars/all.yml`](inventory/group_vars/all.yml)
|
||||
and can be overridden per-host (`inventory/host_vars/<host>.yml`), per-group
|
||||
(`inventory/group_vars/<group>.yml`), or directly in AWX as **extra vars** on a
|
||||
Job Template. Key variables:
|
||||
|
||||
| Variable | Purpose |
|
||||
|-------------------------|------------------------------------------------------|
|
||||
| `dns_servers` | Authoritative recursive DNS servers |
|
||||
| `ntp_servers` | Upstream NTP sources |
|
||||
| `postfix_relayhost` | SMTP smarthost |
|
||||
| `wazuh_manager` | Wazuh server FQDN |
|
||||
| `packages_install` | Fleet toolset package list |
|
||||
| `packages_remove` | Packages purged on every host |
|
||||
| `run_*` | Feature toggles to enable/skip each hardening phase |
|
||||
|
||||
## Host-class conditionals
|
||||
|
||||
The `preflight` role detects host class at runtime and sets facts that
|
||||
downstream roles branch on. Inventory groups provide additional static
|
||||
classification.
|
||||
|
||||
| Fact | Source | Controls |
|
||||
|------|--------|----------|
|
||||
| `is_physical_host` | dmidecode Dell + NOT Proxmox + NOT Pi | physical snmpd.conf, CPU governor, physical packages |
|
||||
| `is_proxmox_host` | dpkg proxmox-ve | physical packages + CPU governor; skips cockpit/tuned |
|
||||
| `is_virt_guest` | virt-what (hyperv/kvm) | VM snmpd.conf, qemu-guest-agent, tuned virtual-guest |
|
||||
| `is_raspi` | /sys/firmware/devicetree/base/model | Pi snmpd.conf, skip GRUB perms |
|
||||
| `is_kali` | ansible_distribution==Kali | skip unavailable packages |
|
||||
| `is_ubuntu` | ansible_distribution==Ubuntu | skip ssh-audit hardening drop-in |
|
||||
| `is_ntp_server` | `ntp_servers` inventory group | skip NTP client config |
|
||||
| `is_dhcp_server` | `dhcp_servers` inventory group | skip dhclient.conf deploy |
|
||||
| `is_librenms_server` | `librenms_server` inventory group | skip rsyslog forward config |
|
||||
| `is_wazuh_server` | `wazuh_server` inventory group | skip wazuh-agent install |
|
||||
| `is_dev_workstation` | `dev_workstations` inventory group | skip hardened sshd_config |
|
||||
|
||||
## Roadmap
|
||||
|
||||
This is the foundation for a comprehensive DISA STIG / CMMC / FedRAMP / ITAR
|
||||
compliance library. The `security_scap_stig` role is the seed for that work —
|
||||
additional STIG control roles will be added alongside it.
|
||||
|
||||
## AWX setup
|
||||
|
||||
AWX resources have been created at `http://tsys-awx.knel.net`:
|
||||
|
||||
| Resource | ID | Name |
|
||||
|----------|----|------|
|
||||
| Credential | 3 | KNELIAC Git Credential (Source Control) |
|
||||
| Credential | 4 | KNELIAC Host SSH Key (Machine) |
|
||||
| Project | 10 | KNELIAC (git, auto-syncs on launch) |
|
||||
| Inventory | 2 | KNELIAC Fleet (SCM-backed, syncs from hosts.yml) |
|
||||
|
||||
Job templates will be created after the code is pushed to git. Run:
|
||||
```bash
|
||||
python3 scripts/awx_create_job_templates.py
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user