Debugging
Tools and techniques for debugging Noid VMs and troubleshooting issues.
VM Console Access
Interactive Console
Access VM directly via console:
# Attach to VM console
noid console my-vm
# Press Ctrl+] to exit
Use cases:
- Debug boot issues
- Check system logs
- Interactive troubleshooting
- Network diagnostics
Serial Output
View VM serial console output:
# View boot messages
noid exec my-vm -- dmesg
# Check system logs
noid exec my-vm -- journalctl -xe
# Kernel messages
noid exec my-vm -- tail -f /var/log/kern.log
Process Inspection
Running Processes
# List all processes
noid exec my-vm -- ps aux
# Process tree
noid exec my-vm -- pstree -p
# Top processes by CPU
noid exec my-vm -- top -b -n 1 | head -20
# Top processes by memory
noid exec my-vm -- ps aux --sort=-%mem | head -10
Process Debugging
# Attach to process with strace
noid exec my-vm -- strace -p <pid>
# Get stack trace
noid exec my-vm -- pstack <pid>
# Memory map
noid exec my-vm -- pmap <pid>
# Open files
noid exec my-vm -- lsof -p <pid>
Network Debugging
Connectivity Tests
# Test external connectivity
noid exec my-vm -- ping -c 3 8.8.8.8
# DNS resolution
noid exec my-vm -- nslookup google.com
# Test specific port
noid exec my-vm -- nc -zv example.com 443
# Trace route
noid exec my-vm -- traceroute google.com
Network Configuration
# Check IP address
noid exec my-vm -- ip addr show
# Routing table
noid exec my-vm -- ip route show
# ARP cache
noid exec my-vm -- arp -a
# Network interfaces
noid exec my-vm -- ifconfig -a
Network Traffic Analysis
# Capture packets
noid exec my-vm -- tcpdump -i eth0 -n
# HTTP traffic
noid exec my-vm -- tcpdump -i eth0 -A 'tcp port 80'
# DNS queries
noid exec my-vm -- tcpdump -i eth0 'udp port 53'
# Network statistics
noid exec my-vm -- netstat -s
Disk & Filesystem
Disk Usage
# Filesystem usage
noid exec my-vm -- df -h
# Directory sizes
noid exec my-vm -- du -sh /*
# Find large files
noid exec my-vm -- find / -type f -size +100M -exec ls -lh {} \\;
# Inode usage
noid exec my-vm -- df -i
File Operations
# Find recently modified files
noid exec my-vm -- find /var/log -mtime -1 -type f
# Search file content
noid exec my-vm -- grep -r "error" /var/log/
# Check file permissions
noid exec my-vm -- ls -la /path/to/file
# File type
noid exec my-vm -- file /path/to/file
Memory Analysis
Memory Usage
# Memory statistics
noid exec my-vm -- free -h
# Detailed memory info
noid exec my-vm -- cat /proc/meminfo
# Process memory
noid exec my-vm -- ps aux --sort=-%mem | head -20
# Memory map
noid exec my-vm -- cat /proc/<pid>/maps
Memory Leaks
# Install valgrind
noid exec my-vm -- apt-get install -y valgrind
# Check for memory leaks
noid exec my-vm -- valgrind --leak-check=full ./your-app
# Monitor memory over time
noid exec my-vm -- sh -c "
while true; do
free -m | grep Mem
sleep 5
done
"
Application Debugging
Logs
# Application logs
noid exec my-vm -- tail -f /var/log/app.log
# Filter errors
noid exec my-vm -- grep ERROR /var/log/app.log
# Last 100 errors
noid exec my-vm -- grep ERROR /var/log/app.log | tail -100
# Real-time error monitoring
noid exec my-vm -- tail -f /var/log/app.log | grep --color=always ERROR
Environment Variables
# List all environment variables
noid exec my-vm -- printenv
# Check specific variable
noid exec my-vm -- echo \$PATH
# Set and test variable
noid exec my-vm -e DEBUG=true -- ./run-app
Core Dumps
# Enable core dumps
noid exec my-vm -- ulimit -c unlimited
# Core dump location
noid exec my-vm -- cat /proc/sys/kernel/core_pattern
# Analyze core dump with gdb
noid exec my-vm -- gdb ./app core
Performance Profiling
CPU Profiling
# CPU usage over time
noid exec my-vm -- mpstat 1 10
# Per-CPU statistics
noid exec my-vm -- mpstat -P ALL
# I/O wait time
noid exec my-vm -- iostat -x 1 10
Application Profiling
# Profile Python application
noid exec my-vm -- python3 -m cProfile app.py
# Profile Node.js application
noid exec my-vm -- node --prof app.js
# Profile with perf
noid exec my-vm -- perf record -g ./app
noid exec my-vm -- perf report
Server-Side Debugging
Server Logs
# View Noid server logs
sudo journalctl -u noid-server -f
# Filter errors
sudo journalctl -u noid-server | grep ERROR
# Last 100 lines
sudo journalctl -u noid-server -n 100
# Specific time range
sudo journalctl -u noid-server --since "1 hour ago"
Firecracker Processes
# List Firecracker processes
ps aux | grep firecracker
# Check Firecracker logs
sudo ls -la /var/lib/noid/vms/*/firecracker.log
# Monitor Firecracker API calls
sudo strace -p $(pgrep firecracker) -e trace=network
Resource Usage
# System resource usage
htop
# Disk I/O
iotop
# Network bandwidth
iftop
# All processes resource usage
systemd-cgtop
Common Issues
VM Won't Start
# Check if VM already exists
noid list | grep my-vm
# Check server logs
sudo journalctl -u noid-server -n 50
# Verify Firecracker
firecracker --version
# Check KVM availability
lsmod | grep kvm
Slow VM Creation
# Check if using btrfs
mount | grep noid
# Disk performance
sudo iostat -x 1 10
# Check if golden snapshot exists
ls -la /var/lib/noid/checkpoints/
Network Issues
# Check bridge
ip link show noid0
# Verify NAT rules
sudo iptables -t nat -L
# Check IP pool
# (check server logs for IP allocation)
# Test VM connectivity
noid exec my-vm -- ping -c 3 8.8.8.8
Debugging Workflows
Checkpoint for Debugging
# Create checkpoint before debugging
noid checkpoint my-vm before-debug
# Make changes, test, experiment
noid exec my-vm -- gdb ./app
# If things break, restore
noid restore my-vm before-debug
# If fix works, create new checkpoint
noid checkpoint my-vm fixed
Bisecting Issues
# Create checkpoints at key points
noid checkpoint my-vm checkpoint-1
# ... make changes ...
noid checkpoint my-vm checkpoint-2
# ... make changes ...
noid checkpoint my-vm checkpoint-3
# Issue found, bisect by restoring
noid restore my-vm checkpoint-2
# Test if issue exists
# Narrow down to specific change
Remote Debugging
# Start debug server in VM
noid exec my-vm -- gdbserver :2345 ./app
# Get VM IP
VM_IP=$(noid list | grep my-vm | awk '{print $4}')
# Connect from host
gdb ./app
(gdb) target remote $VM_IP:2345
(gdb) continue
Diagnostic Tools
Install Debug Tools
# Essential debugging tools
noid exec my-vm -- apt-get install -y \
strace \
ltrace \
gdb \
valgrind \
tcpdump \
netcat \
curl \
wget \
vim \
htop \
iotop \
lsof
Custom Debug Script
#!/bin/bash
# debug-vm.sh
VM_NAME=$1
echo "=== System Info ==="
noid exec $VM_NAME -- uname -a
echo -e "\n=== Memory Usage ==="
noid exec $VM_NAME -- free -h
echo -e "\n=== Disk Usage ==="
noid exec $VM_NAME -- df -h
echo -e "\n=== Network ==="
noid exec $VM_NAME -- ip addr show
echo -e "\n=== Running Processes ==="
noid exec $VM_NAME -- ps aux | head -20
echo -e "\n=== Recent Errors ==="
noid exec $VM_NAME -- journalctl -p err -n 10
Usage:
./debug-vm.sh my-vm
Next Steps
- Common Issues - Common problems
- Monitoring - Set up monitoring
- CLI Reference - Command reference