# Gather System Info Playbook Cheatsheet

Quick reference for using the gather_system_info.yml playbook to collect comprehensive system information across infrastructure.

## Quick Start

```bash
# Gather information from all hosts
ansible-playbook playbooks/gather_system_info.yml

# Specific environment
ansible-playbook -i inventories/production playbooks/gather_system_info.yml

# Specific host group
ansible-playbook playbooks/gather_system_info.yml --limit webservers
```

## Common Usage

### Basic Execution

```bash
# All hosts in inventory
ansible-playbook playbooks/gather_system_info.yml

# Single host
ansible-playbook playbooks/gather_system_info.yml --limit server01.example.com

# Specific group
ansible-playbook playbooks/gather_system_info.yml --limit databases

# Check mode (dry-run)
ansible-playbook playbooks/gather_system_info.yml --check
```

### Selective Information Gathering

```bash
# CPU information only
ansible-playbook playbooks/gather_system_info.yml --tags cpu

# Memory and disk only
ansible-playbook playbooks/gather_system_info.yml --tags memory,disk

# Hypervisor detection only
ansible-playbook playbooks/gather_system_info.yml --tags hypervisor

# Skip installation of packages
ansible-playbook playbooks/gather_system_info.yml --skip-tags install

# Validation and health checks only
ansible-playbook playbooks/gather_system_info.yml --tags validate,health-check
```

## Available Tags

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

## Playbook Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `system_info_stats_base_dir` | `./stats/machines` | Base directory for output |
| `system_info_gather_cpu` | `true` | Gather CPU information |
| `system_info_gather_gpu` | `true` | Gather GPU information |
| `system_info_gather_memory` | `true` | Gather memory information |
| `system_info_gather_disk` | `true` | Gather disk information |
| `system_info_gather_network` | `true` | Gather network information |
| `system_info_detect_hypervisor` | `true` | Detect hypervisor capabilities |

## 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 human-readable summary
cat ./stats/machines/server01.example.com/summary.txt

# List all hosts with stats
ls -1 ./stats/machines/

# Count total hosts
ls -1d ./stats/machines/*/ | wc -l
```

## Example Invocations

### Basic Examples

```bash
# Production inventory
ansible-playbook -i inventories/production playbooks/gather_system_info.yml

# Staging inventory
ansible-playbook -i inventories/staging playbooks/gather_system_info.yml

# Custom output directory
ansible-playbook playbooks/gather_system_info.yml \
  -e "system_info_stats_base_dir=/var/lib/ansible/inventory"
```

### Advanced Examples

```bash
# Hypervisors only with full gathering
ansible-playbook playbooks/gather_system_info.yml \
  --limit hypervisors \
  -e "system_info_detect_hypervisor=true"

# Quick scan (minimal gathering)
ansible-playbook playbooks/gather_system_info.yml \
  -e "system_info_gather_network=false" \
  -e "system_info_gather_gpu=false" \
  --skip-tags install

# Parallel execution (10 hosts at a time)
ansible-playbook playbooks/gather_system_info.yml -f 10

# With increased verbosity
ansible-playbook playbooks/gather_system_info.yml -v
```

## Data Queries

### Using jq for Data Extraction

```bash
# Get CPU models across all hosts
jq -r '.cpu.model' ./stats/machines/*/system_info.json

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

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

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

# Get OS distribution
jq -r '"\(.host_info.fqdn): \(.system.distribution) \(.system.distribution_version)"' \
  ./stats/machines/*/system_info.json

# Find hosts with high CPU count
jq -r 'select(.cpu.count.vcpus > 8) | "\(.host_info.fqdn): \(.cpu.count.vcpus) vCPUs"' \
  ./stats/machines/*/system_info.json

# Find hosts with low disk space
jq -r 'select(.disk.usage_percent > 80) | "\(.host_info.fqdn): \(.disk.usage_percent)%"' \
  ./stats/machines/*/system_info.json
```

### Generate Reports

```bash
# CSV export: Hostname, OS, CPU, Memory
jq -r '["FQDN","OS","CPU Cores","Memory GB"],
       ([.host_info.fqdn, .system.distribution,
         .cpu.count.vcpus, (.memory.total_mb/1024|round)]) | @csv' \
  ./stats/machines/*/system_info.json > infrastructure_report.csv

# Count CPUs across infrastructure
jq -s 'map(.cpu.count.total_cores | tonumber) | add' \
  ./stats/machines/*/system_info.json

# Total memory across infrastructure (GB)
jq -s 'map(.memory.total_mb | tonumber) | add / 1024 | round' \
  ./stats/machines/*/system_info.json

# List GPU-enabled hosts
jq -r 'select(.gpu.detected == true) | "\(.host_info.fqdn): \(.gpu.devices[0].model)"' \
  ./stats/machines/*/system_info.json

# SELinux status report
jq -r '"\(.host_info.fqdn): SELinux \(.security.selinux)"' \
  ./stats/machines/*/system_info.json | grep -v "N/A"

# AppArmor status report
jq -r '"\(.host_info.fqdn): AppArmor \(.security.apparmor)"' \
  ./stats/machines/*/system_info.json | grep -v "N/A"
```

## Integration Examples

### Cron Job for Regular Collection

```bash
# Daily collection at 2 AM
0 2 * * * cd /opt/ansible && ansible-playbook playbooks/gather_system_info.yml \
  >> /var/log/ansible/gather_system_info.log 2>&1
```

### SystemD Timer

```ini
# /etc/systemd/system/ansible-gather-system-info.timer
[Unit]
Description=Gather System Information Daily

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target
```

```ini
# /etc/systemd/system/ansible-gather-system-info.service
[Unit]
Description=Ansible Gather System Information

[Service]
Type=oneshot
WorkingDirectory=/opt/ansible
ExecStart=/usr/bin/ansible-playbook playbooks/gather_system_info.yml
User=ansible
StandardOutput=append:/var/log/ansible/gather_system_info.log
StandardError=append:/var/log/ansible/gather_system_info.log
```

### CMDB Integration

```bash
# Export to NetBox or other CMDB
for host_dir in ./stats/machines/*/; do
  host=$(basename "$host_dir")
  curl -X POST https://netbox.example.com/api/dcim/devices/ \
    -H "Authorization: Token $NETBOX_TOKEN" \
    -H "Content-Type: application/json" \
    -d @"${host_dir}/system_info.json"
done
```

### Monitoring Integration

```bash
# Create Prometheus metrics
for stats_file in ./stats/machines/*/system_info.json; do
  host=$(jq -r '.host_info.fqdn' "$stats_file")
  cpu=$(jq -r '.cpu.count.vcpus' "$stats_file")
  mem=$(jq -r '.memory.total_mb' "$stats_file")

  cat <<EOF > /var/lib/node_exporter/textfile_collector/${host}.prom
# HELP system_info_cpu_count Number of CPU cores
# TYPE system_info_cpu_count gauge
system_info_cpu_count{host="$host"} $cpu

# HELP system_info_memory_mb Total memory in MB
# TYPE system_info_memory_mb gauge
system_info_memory_mb{host="$host"} $mem
EOF
done
```

## Troubleshooting

### Check Playbook Execution

```bash
# Dry-run (check mode)
ansible-playbook playbooks/gather_system_info.yml --check

# Verbose output
ansible-playbook playbooks/gather_system_info.yml -v

# Very verbose (debug)
ansible-playbook playbooks/gather_system_info.yml -vvv

# Single host debugging
ansible-playbook playbooks/gather_system_info.yml \
  --limit problematic-host -vvv
```

### Common Issues

**Missing packages**
```bash
# Install packages manually first
ansible all -m package -a "name=lshw,dmidecode,pciutils state=present" --become

# Or run with install tag only
ansible-playbook playbooks/gather_system_info.yml --tags install
```

**Permission errors**
```bash
# Ensure become is enabled
ansible-playbook playbooks/gather_system_info.yml --become

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

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

# Check disk space
df -h .

# Create directory manually
mkdir -p ./stats/machines

# Specify alternative directory
ansible-playbook playbooks/gather_system_info.yml \
  -e "system_info_stats_base_dir=/tmp/stats"
```

**Slow execution**
```bash
# Skip slow operations
ansible-playbook playbooks/gather_system_info.yml \
  --skip-tags install,network

# Disable GPU gathering
ansible-playbook playbooks/gather_system_info.yml \
  -e "system_info_gather_gpu=false"

# Increase parallelism
ansible-playbook playbooks/gather_system_info.yml -f 20
```

### Validation

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

# Check for missing files
for host in $(ansible all --list-hosts | tail -n +2); do
  if [ ! -f "./stats/machines/${host}/system_info.json" ]; then
    echo "Missing: $host"
  fi
done

# Verify data completeness
jq -r 'if .cpu == null then "Missing CPU data" else "OK" end' \
  ./stats/machines/*/system_info.json
```

## Performance Optimization

### Parallel Execution

```bash
# Default (5 hosts at a time)
ansible-playbook playbooks/gather_system_info.yml

# Increase parallelism
ansible-playbook playbooks/gather_system_info.yml -f 20

# Serial execution (one at a time)
ansible-playbook playbooks/gather_system_info.yml -f 1
```

### Skip Slow Tasks

```bash
# Skip package installation
ansible-playbook playbooks/gather_system_info.yml --skip-tags install

# Skip network gathering
ansible-playbook playbooks/gather_system_info.yml --skip-tags network

# Minimal gathering
ansible-playbook playbooks/gather_system_info.yml \
  -e "system_info_gather_gpu=false" \
  -e "system_info_gather_network=false" \
  -e "system_info_detect_hypervisor=false"
```

### Fact Caching

Enable in ansible.cfg:
```ini
[defaults]
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 3600
```

## Use Cases

### Infrastructure Audit

```bash
# Collect from all environments
for env in production staging development; do
  ansible-playbook -i inventories/$env playbooks/gather_system_info.yml
done

# Generate comprehensive report
./scripts/generate_infrastructure_report.sh
```

### Capacity Planning

```bash
# Gather current utilization
ansible-playbook playbooks/gather_system_info.yml --tags validate,health-check

# Analyze resource usage
jq -r '"\(.host_info.fqdn),\(.cpu.load_average.one_min),\(.memory.usage_percent),\(.disk.usage_percent)"' \
  ./stats/machines/*/system_info.json | column -t -s,
```

### Compliance Reporting

```bash
# Security compliance check
ansible-playbook playbooks/gather_system_info.yml --tags security

# Generate compliance report
jq -r '"\(.host_info.fqdn),\(.security.selinux),\(.security.apparmor)"' \
  ./stats/machines/*/system_info.json > compliance_report.csv
```

### License Auditing

```bash
# Count CPU cores for licensing
ansible-playbook playbooks/gather_system_info.yml --tags cpu

# Total cores
jq -s 'map(.cpu.count.total_cores | tonumber) | add' \
  ./stats/machines/*/system_info.json
```

## Quick Reference Commands

```bash
# Standard execution
ansible-playbook playbooks/gather_system_info.yml

# Specific hosts
ansible-playbook playbooks/gather_system_info.yml --limit webservers

# Specific tags
ansible-playbook playbooks/gather_system_info.yml --tags cpu,memory

# Custom output directory
ansible-playbook playbooks/gather_system_info.yml \
  -e "system_info_stats_base_dir=/custom/path"

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

# Query all hosts
jq . ./stats/machines/*/system_info.json | less
```

## See Also

- [System Info Role README](../../roles/system_info/README.md)
- [System Info Role Documentation](../../docs/roles/system_info.md)
- [System Info Role Cheatsheet](../roles/system_info.md)
- [Role Index](../../docs/roles/role-index.md)

---

**Playbook**: gather_system_info.yml
**Updated**: 2025-11-11
**Related Role**: system_info v1.0.0