# Diagnostic Commands

Essential commands for diagnosing issues with the Unraid Management Agent.

## Service Status

### Check if Service is Running

```bash
# Process check
ps aux | grep unraid-management-agent

# Expected output shows running process:
# root ... /usr/local/emhttp/plugins/unraid-management-agent/unraid-management-agent boot
```

### View Service Logs

```bash
# Real-time log monitoring
tail -f /var/log/unraid-management-agent.log

# Last 100 lines
tail -100 /var/log/unraid-management-agent.log

# Search for errors
grep -i error /var/log/unraid-management-agent.log

# Search for specific collector
grep "Docker collector" /var/log/unraid-management-agent.log
```

### Service Control

```bash
# Stop service
/usr/local/emhttp/plugins/unraid-management-agent/scripts/stop

# Start service
/usr/local/emhttp/plugins/unraid-management-agent/scripts/start

# Restart service
/usr/local/emhttp/plugins/unraid-management-agent/scripts/stop
/usr/local/emhttp/plugins/unraid-management-agent/scripts/start

# Start in debug mode (manual)
/usr/local/emhttp/plugins/unraid-management-agent/unraid-management-agent boot --debug
```

## Network Diagnostics

### Check Port Status

```bash
# Check if port 8043 is listening
netstat -tulpn | grep 8043

# Check what process is using port 8043
lsof -i :8043

# Check all listening ports
netstat -tulpn | grep LISTEN
```

### Test API Connectivity

```bash
# Local connection
curl http://localhost:8043/api/v1/health

# From another machine
curl http://UNRAID_IP:8043/api/v1/health

# Check response time
time curl http://localhost:8043/api/v1/system

# Verbose connection test
curl -v http://localhost:8043/api/v1/health
```

### Test WebSocket

```bash
# Using websocat (if installed)
websocat ws://localhost:8043/api/v1/ws

# Using wscat (if installed)
wscat -c ws://localhost:8043/api/v1/ws
```

## Data Collection Diagnostics

### Verify System Access

```bash
# Check /proc access
cat /proc/stat | head -5
cat /proc/meminfo | head -5
cat /proc/uptime

# Check /sys access
ls -l /sys/class/hwmon/
ls -l /sys/class/net/

# Check Unraid config files
cat /var/local/emhttp/var.ini | head -10
```

### Docker Diagnostics

```bash
# Check Docker socket access
ls -l /var/run/docker.sock

# Test Docker connection
docker info

# List containers
docker ps -a

# Check Docker API version
docker version
```

### VM/Libvirt Diagnostics

```bash
# Check libvirt socket
ls -l /var/run/libvirt/libvirt-sock

# List VMs via virsh
virsh list --all

# Check libvirtd status
ps aux | grep libvirtd
```

### Disk/SMART Diagnostics

```bash
# Check smartctl availability
which smartctl

# Test SMART on a disk
smartctl -i /dev/sda
smartctl -H /dev/sda

# Check disk stats
cat /proc/diskstats
```

### Temperature Sensor Diagnostics

```bash
# Check sensors command
which sensors

# List all sensors
sensors

# Raw sensor output
sensors -u

# Check hwmon devices
ls -la /sys/class/hwmon/
cat /sys/class/hwmon/hwmon*/name
```

### GPU Diagnostics

```bash
# Check nvidia-smi
which nvidia-smi

# Test GPU detection
nvidia-smi

# GPU detailed info
nvidia-smi -q
```

### UPS Diagnostics

```bash
# Check apcupsd
which apcaccess
apcaccess status

# Check NUT
which upsc
upsc -l
upsc ups@localhost
```

## API Response Testing

### Test All Endpoints

```bash
# Create test script
cat << 'EOF' > /tmp/test-api.sh
#!/bin/bash
BASE_URL="http://localhost:8043/api/v1"

echo "Testing endpoints..."
curl -s $BASE_URL/health && echo "✓ Health"
curl -s $BASE_URL/system > /dev/null && echo "✓ System"
curl -s $BASE_URL/array > /dev/null && echo "✓ Array"
curl -s $BASE_URL/disks > /dev/null && echo "✓ Disks"
curl -s $BASE_URL/docker > /dev/null && echo "✓ Docker"
curl -s $BASE_URL/vm > /dev/null && echo "✓ VMs"
curl -s $BASE_URL/network > /dev/null && echo "✓ Network"
curl -s $BASE_URL/shares > /dev/null && echo "✓ Shares"
curl -s $BASE_URL/ups > /dev/null && echo "✓ UPS"
curl -s $BASE_URL/gpu > /dev/null && echo "✓ GPU"
echo "Done!"
EOF

chmod +x /tmp/test-api.sh
/tmp/test-api.sh
```

### Collector Status Check

```bash
# Check collectors status (if endpoint exists)
curl http://localhost:8043/api/v1/collectors/status | jq

# Check specific collector
curl http://localhost:8043/api/v1/collectors/system | jq
```

## Performance Diagnostics

### Memory Usage

```bash
# Check agent memory usage
ps aux | grep unraid-management-agent | grep -v grep

# Detailed memory info
pmap $(pgrep -f unraid-management-agent)
```

### CPU Usage

```bash
# Real-time CPU monitoring
top -b -n 1 | grep unraid-management-agent

# CPU usage over time (run for 10 seconds)
top -b -d 1 -n 10 | grep unraid-management-agent
```

### Response Times

```bash
# Measure endpoint response times
for endpoint in health system array disks docker vm; do
  echo -n "$endpoint: "
  time curl -s http://localhost:8043/api/v1/$endpoint > /dev/null
done
```

## Configuration Diagnostics

### Check Configuration File

```bash
# View current config
cat /boot/config/plugins/unraid-management-agent/config.cfg

# Check file permissions
ls -l /boot/config/plugins/unraid-management-agent/

# Verify config syntax (if tool available)
cat /boot/config/plugins/unraid-management-agent/config.cfg | grep -v ^# | grep .
```

### Check Binary Info

```bash
# Binary location
which unraid-management-agent

# Binary version
/usr/local/emhttp/plugins/unraid-management-agent/unraid-management-agent --version

# Binary permissions
ls -l /usr/local/emhttp/plugins/unraid-management-agent/unraid-management-agent
```

## Log Analysis

### Find Errors

```bash
# Recent errors
grep -i error /var/log/unraid-management-agent.log | tail -20

# Count error types
grep -i error /var/log/unraid-management-agent.log | cut -d: -f2 | sort | uniq -c

# Errors in last hour
grep -i error /var/log/unraid-management-agent.log | grep "$(date +'%Y-%m-%d %H')"
```

### Find Warnings

```bash
# All warnings
grep -i warning /var/log/unraid-management-agent.log

# Recent warnings
grep -i warning /var/log/unraid-management-agent.log | tail -10
```

### Collector Activity

```bash
# See which collectors are running
grep "Starting.*collector" /var/log/unraid-management-agent.log

# Check collector errors
grep "collector.*failed\|collector.*error" /var/log/unraid-management-agent.log

# Last collection times
grep "Collecting" /var/log/unraid-management-agent.log | tail -20
```

## System Information

### Unraid Version

```bash
# Unraid version
cat /etc/unraid-version

# Kernel version
uname -r

# System architecture
uname -m
```

### Plugin Version

```bash
# Plugin version from binary
/usr/local/emhttp/plugins/unraid-management-agent/unraid-management-agent --version

# Plugin version from file
cat /usr/local/emhttp/plugins/unraid-management-agent/VERSION
```

## Export Diagnostics

There are two primary ways to export diagnostics depending on whether you are sharing information externally or inspecting the host locally:

### 1. Redacted Diagnostics Bundle (Recommended for Bug Reports)

The agent provides a built-in diagnostic bundling service that exports a ZIP archive with known sensitive values (API tokens, MCP connect secret, MQTT credentials, and passwords) redacted. Review the archive for sensitive data before attaching it to GitHub issues and bug reports.

**Via HTTP API:**

```bash
# Download redacted bundle directly from the agent
curl -OJ http://localhost:8043/api/v1/diagnostics/bundle
```

**Via WebGUI:**
Navigate to the Unraid Management Agent settings page in the Unraid WebGUI and click **Download Diagnostics**.

**Via CLI:**

```bash
# Generate the redacted ZIP archive locally into the current or specified directory
/usr/local/emhttp/plugins/unraid-management-agent/unraid-management-agent diagnostics --output-dir=/tmp
```

For API endpoint details and response format, see the [Diagnostics API Reference](../api/diagnostics.md).

### 2. Local Unredacted Shell Diagnostic Bundle (Host Admin Analysis)

For immediate, deep debugging by the system administrator directly on the Unraid server, you can generate an unredacted diagnostic text dump (`uma-diagnostics` shell script).

> [!WARNING]
> The shell diagnostic script captures raw configuration files (including `config.cfg`), which may contain unmasked passwords or API tokens. **This shell dump is unredacted** and intended strictly for local administrator inspection. Do **not** post this file to public forums or GitHub without manual redaction.

```bash
# Create comprehensive unredacted local diagnostic output
cat << 'EOF' > /tmp/diagnostic-bundle.sh
#!/bin/bash
OUTPUT="/tmp/unraid-agent-diagnostics.txt"
echo "Unraid Management Agent Diagnostics (UNREDACTED - LOCAL ADMIN ONLY)" > $OUTPUT
echo "Generated: $(date)" >> $OUTPUT
echo "=================================" >> $OUTPUT

echo -e "\n=== System Info ===" >> $OUTPUT
uname -a >> $OUTPUT
cat /etc/unraid-version >> $OUTPUT

echo -e "\n=== Service Status ===" >> $OUTPUT
ps aux | grep unraid-management-agent >> $OUTPUT

echo -e "\n=== Port Status ===" >> $OUTPUT
netstat -tulpn | grep 8043 >> $OUTPUT

echo -e "\n=== Last 50 Log Lines ===" >> $OUTPUT
tail -50 /var/log/unraid-management-agent.log >> $OUTPUT

echo -e "\n=== Configuration ===" >> $OUTPUT
cat /boot/config/plugins/unraid-management-agent/config.cfg >> $OUTPUT

echo -e "\n=== API Health Check ===" >> $OUTPUT
curl -s http://localhost:8043/api/v1/health >> $OUTPUT 2>&1

echo -e "\n=== Collectors Status ===" >> $OUTPUT
curl -s http://localhost:8043/api/v1/collectors/status >> $OUTPUT 2>&1

echo "Diagnostics saved to: $OUTPUT"
cat $OUTPUT
EOF

chmod +x /tmp/diagnostic-bundle.sh
/tmp/diagnostic-bundle.sh
```

## Next Steps

- [Common Issues](common-issues.md) - Solutions to frequent problems
- [Hardware Compatibility](hardware-compatibility.md) - Hardware-specific guidance
- [System Requirements](../guides/system-requirements.md) - Verify requirements

---

**Last Updated**: January 2026