# System Info Role Cheatsheet

Quick reference guide for the `system_info` role - comprehensive system information gathering.

## Quick Start

```bash
# Run complete information gathering
ansible-playbook site.yml -t system_info

# Run on specific hosts
ansible-playbook site.yml -l webservers -t system_info

# Run with validation only
ansible-playbook site.yml -t system_info,validate
```

## Common Execution Patterns

### Full Execution
```bash
# All hosts, all information
ansible-playbook site.yml -t system_info

# Single host
ansible-playbook site.yml -l hostname.example.com -t system_info

# Specific group
ansible-playbook site.yml -l production -t system_info
```

### Selective Information Gathering

```bash
# CPU information only
ansible-playbook site.yml -t system_info,cpu

# GPU information only
ansible-playbook site.yml -t system_info,gpu

# Memory and swap only
ansible-playbook site.yml -t system_info,memory

# Disk information only
ansible-playbook site.yml -t system_info,disk

# Network information only
ansible-playbook site.yml -t system_info,network

# Hypervisor detection only
ansible-playbook site.yml -t system_info,hypervisor

# System information only
ansible-playbook site.yml -t system_info,system
```

### Combined Tags

```bash
# CPU, Memory, and Disk
ansible-playbook site.yml -t system_info,cpu,memory,disk

# Skip installation, gather only
ansible-playbook site.yml -t system_info --skip-tags install

# Validation and health check
ansible-playbook site.yml -t system_info,validate,health-check

# Export statistics only (requires prior gathering)
ansible-playbook site.yml -t system_info,export
```

## Available Tags

| Tag | Description |
|-----|-------------|
| `system_info` | Main role tag (required) |
| `install` | Install required packages |
| `gather` | All information gathering |
| `system` | OS and system info |
| `cpu` | CPU details |
| `gpu` | GPU detection |
| `memory` | RAM and swap |
| `disk` | Storage and filesystems |
| `network` | Network interfaces |
| `hypervisor` | Virtualization detection |
| `export` | Export to JSON |
| `statistics` | Statistics aggregation |
| `validate` | Validation checks |
| `health-check` | Health monitoring |
| `security` | Security-related info |

## Common Variables

### Directory Configuration
```yaml
# Custom statistics directory
system_info_stats_base_dir: /var/lib/ansible/stats

# Disable automatic directory creation
system_info_create_stats_dir: false
```

### Feature Toggles
```yaml
# Disable GPU gathering (for servers without GPU)
system_info_gather_gpu: false

# Disable hypervisor detection
system_info_detect_hypervisor: false

# Minimal gathering (CPU, Memory, Disk only)
system_info_gather_network: false
system_info_gather_gpu: false
system_info_detect_hypervisor: false
```

### Output Configuration
```yaml
# Increase JSON readability
system_info_json_indent: 4

# Include raw command outputs
system_info_include_raw_output: true
```

## Output Files

### Default Location
```
./stats/machines/<fqdn>/
├── system_info.json           # Latest statistics
├── system_info_<epoch>.json   # Timestamped backup
└── summary.txt                 # Human-readable summary
```

### View Statistics
```bash
# View JSON (pretty-printed)
jq . ./stats/machines/server01.example.com/system_info.json

# View summary
cat ./stats/machines/server01.example.com/summary.txt

# Extract specific information
jq '.cpu.model' ./stats/machines/*/system_info.json
jq '.memory.total_mb' ./stats/machines/*/system_info.json
jq '.hypervisor.is_hypervisor' ./stats/machines/*/system_info.json

# Count hypervisors
jq -r 'select(.hypervisor.is_hypervisor == true) | .host_info.fqdn' \
  ./stats/machines/*/system_info.json | wc -l

# Find all VMs
jq -r 'select(.hypervisor.is_virtual == true) | .host_info.fqdn' \
  ./stats/machines/*/system_info.json

# Memory usage report
jq -r '"\(.host_info.fqdn): \(.memory.usage_percent)%"' \
  ./stats/machines/*/system_info.json
```

## Example Playbooks

### Basic Playbook
```yaml
---
- name: Gather system information
  hosts: all
  become: true
  roles:
    - system_info
```

### Advanced Playbook
```yaml
---
- name: Gather detailed system information
  hosts: all
  become: true
  roles:
    - role: system_info
      vars:
        system_info_stats_base_dir: /var/lib/ansible/inventory
        system_info_json_indent: 4
        system_info_gather_gpu: true
        system_info_detect_hypervisor: true
```

### Targeted Playbook
```yaml
---
- name: Gather hypervisor information only
  hosts: hypervisors
  become: true
  tasks:
    - name: Include system_info role for hypervisor detection
      include_role:
        name: system_info
        tasks_from: detect_hypervisor
      tags: [hypervisor]
```

## Troubleshooting

### Check Role Execution
```bash
# Dry-run (check mode)
ansible-playbook site.yml -t system_info --check

# Verbose output
ansible-playbook site.yml -t system_info -v

# Very verbose (debug)
ansible-playbook site.yml -t system_info -vvv

# Single host debugging
ansible-playbook site.yml -l problematic-host -t system_info -vvv
```

### Common Issues

**Missing packages**
```bash
# Install packages manually first
ansible-playbook site.yml -t system_info,install

# Check what would be installed
ansible all -m package_facts
```

**Permission errors**
```bash
# Ensure become is enabled
ansible-playbook site.yml -t system_info --become

# Check sudo access
ansible all -m ping --become
```

**Statistics not saved**
```bash
# Check if directory exists
ls -la ./stats/machines/

# Check disk space on control node
df -h .

# Verify write permissions
touch ./stats/machines/test && rm ./stats/machines/test
```

### Validation

```bash
# Run only validation tasks
ansible-playbook site.yml -t system_info,validate

# Check specific host health
ansible-playbook site.yml -l server01 -t validate,health-check

# Verify JSON files
for f in ./stats/machines/*/system_info.json; do
  echo "Checking $f"
  jq empty "$f" && echo "OK" || echo "INVALID"
done
```

## Performance Optimization

### Parallel Execution
```bash
# Increase parallelism (default: 5)
ansible-playbook site.yml -t system_info -f 20

# Serial execution (one at a time)
ansible-playbook site.yml -t system_info -f 1
```

### Skip Slow Tasks
```bash
# Skip installation if packages are pre-installed
ansible-playbook site.yml -t system_info --skip-tags install

# Skip network gathering (can be slow)
ansible-playbook site.yml -t system_info --skip-tags network
```

## Integration Examples

### Cron Job for Regular Collection
```bash
# Daily collection at 2 AM
0 2 * * * cd /opt/ansible && ansible-playbook site.yml -t system_info >> /var/log/ansible/system_info.log 2>&1
```

### Generate HTML Report
```bash
# Convert JSON to HTML
for host in ./stats/machines/*; do
  hostname=$(basename "$host")
  jq -r 'to_entries | map("\(.key): \(.value)") | .[]' \
    "$host/system_info.json" > "$host/report.txt"
done
```

### Compare Statistics
```bash
# Compare CPU across hosts
jq -r '"\(.host_info.fqdn),\(.cpu.model),\(.cpu.count.vcpus)"' \
  ./stats/machines/*/system_info.json | column -t -s,

# Compare memory across hosts
jq -r '"\(.host_info.fqdn),\(.memory.total_mb) MB,\(.memory.usage_percent)%"' \
  ./stats/machines/*/system_info.json | column -t -s,
```

## Security Checkpoints

- ✓ Role runs with `become: true` for hardware access
- ✓ No credentials or secrets are collected
- ✓ Statistics files contain infrastructure details - protect appropriately
- ✓ Sensitive data (serial numbers, UUIDs) included - review before sharing
- ✓ Files stored on control node only - not on managed hosts

## Quick Reference Commands

```bash
# Full scan
ansible-playbook site.yml -t system_info

# CPU + Memory only
ansible-playbook site.yml -t system_info,cpu,memory

# Validate all hosts
ansible-playbook site.yml -t system_info,validate

# Export only (no gathering)
ansible-playbook site.yml -t system_info,export

# Single host, verbose
ansible-playbook site.yml -l hostname -t system_info -v

# View latest stats
cat ./stats/machines/$(hostname -f)/summary.txt
```

## Ansible Ad-Hoc Alternatives

```bash
# Quick CPU check
ansible all -m shell -a "lscpu | grep 'Model name'"

# Quick memory check
ansible all -m shell -a "free -h"

# Quick disk check
ansible all -m shell -a "df -h"

# Check virtualization
ansible all -m shell -a "systemd-detect-virt"
```

---

**Role**: system_info v1.0.0
**Updated**: 2025-01-11
**Documentation**: See `roles/system_info/README.md`