./scripts/health-check.sh
This command provides a comprehensive overview of all monitoring services and their status.
Symptoms:
Diagnosis:
## Check LaunchAgent status
launchctl list | grep homelab
## Check for error messages
tail -f ~/.homelab/logs/*.log
## Verify file permissions
ls -la ~/.homelab/monitoring/
Solutions:
Reset LaunchAgents:
## Unload existing agents
launchctl unload ~/Library/LaunchAgents/com.homelab.*.plist
## Reload agents
launchctl load ~/Library/LaunchAgents/com.homelab.*.plist
## Verify they're running
launchctl list | grep homelab
Fix Permissions:
## Reset ownership
sudo chown -R $(whoami) ~/.homelab/
## Make scripts executable
chmod +x ~/.homelab/monitoring/*.sh
chmod +x scripts/*.sh
## Fix log directory permissions
sudo chown $(whoami) /var/log/family-macbook-*.log
Recreate Configuration:
## Re-run setup scripts
./scripts/setup-monitoring.sh
./scripts/setup-parental-controls.sh
Symptoms:
Diagnosis:
## Test homelab connectivity
ping seq.speicher.family
ping beszel.speicher.family
ping grafana.speicher.family
## Check Tailscale status
tailscale status
## Test specific ports
nc -zv seq.speicher.family 12201
nc -zv beszel.speicher.family 80
Solutions:
Restart Tailscale:
## Restart Tailscale connection
sudo launchctl unload /Library/LaunchDaemons/com.tailscale.tailscaled.plist
sudo launchctl load /Library/LaunchDaemons/com.tailscale.tailscaled.plist
## Re-authenticate if needed
tailscale up
Check Network Configuration:
## Verify DNS resolution
nslookup seq.speicher.family
nslookup beszel.speicher.family
## Check routing
traceroute seq.speicher.family
Use Fallback Connectivity:
## Temporarily use local network IPs
## Edit ~/.homelab/monitoring/beszel-agent.conf
## Change HOST to local IP if Tailscale is down
Symptoms:
Diagnosis:
## Check if agent is running
pgrep -f beszel-agent
## View agent logs
tail -f ~/.homelab/logs/beszel-agent.log
## Test manual connection
beszel-agent --help
## Check configuration
cat ~/.homelab/monitoring/beszel-agent.conf
Solutions:
Restart Agent:
## Kill existing process
pkill beszel-agent
## Restart via LaunchAgent
launchctl unload ~/Library/LaunchAgents/com.homelab.beszel-agent.plist
launchctl load ~/Library/LaunchAgents/com.homelab.beszel-agent.plist
Update Agent:
## Update via Homebrew
brew update
brew upgrade beszel-agent
## Restart after update
./scripts/health-check.sh
Reset Configuration:
## Regenerate configuration
./scripts/setup-monitoring.sh
## Verify configuration
cat ~/.homelab/monitoring/beszel-agent.conf
Symptoms:
Diagnosis:
## Check osquery status
pgrep -f osquery
## Test osquery manually
sudo osqueryi "SELECT * FROM system_info;"
## Check configuration
sudo cat /etc/osquery/osquery.conf
## View osquery logs
tail -f ~/.homelab/logs/osqueryd.results.log
Solutions:
Permissions Fix:
## Fix osquery permissions
sudo chown root:wheel /etc/osquery/osquery.conf
sudo chmod 644 /etc/osquery/osquery.conf
## Create log directories
sudo mkdir -p ~/.homelab/logs
sudo chown $(whoami) ~/.homelab/logs
Restart osquery:
## Stop osquery
sudo pkill osqueryd
## Restart via LaunchAgent
launchctl unload ~/Library/LaunchAgents/com.homelab.osquery.plist
launchctl load ~/Library/LaunchAgents/com.homelab.osquery.plist
Recreate Configuration:
## Regenerate osquery config
./scripts/setup-monitoring.sh
Symptoms:
Diagnosis:
## Check parental control services
pgrep -f screen-time-monitor
pgrep -f app-monitor
pgrep -f browser-monitor
## View parental control logs
tail -f /var/log/family-macbook-*.log
## Test Screen Time API access
## (Requires manual verification in System Preferences)
Solutions:
Enable Screen Time:
Restart Parental Services:
## Restart all parental control services
launchctl unload ~/Library/LaunchAgents/com.homelab.*-monitor.plist
launchctl load ~/Library/LaunchAgents/com.homelab.*-monitor.plist
Reset Parental Configuration:
## Reconfigure parental controls
./scripts/setup-parental-controls.sh
## Verify configuration
cat ~/.homelab/parental-controls/*.conf
Symptoms:
Diagnosis:
## Check data flow
./scripts/family-dashboard.sh
## Test Seq connectivity
curl -I http://seq.speicher.family:12201
## Verify log forwarding
tail -f ~/.homelab/logs/log-forwarder.log
Solutions:
Reset Log Forwarding:
## Restart log forwarding service
launchctl unload ~/Library/LaunchAgents/com.homelab.log-forwarder.plist
launchctl load ~/Library/LaunchAgents/com.homelab.log-forwarder.plist
Manual Data Check:
## Generate test data
echo "Test log entry: $(date)" >> ~/.homelab/logs/test.log
## Force log forwarding
~/.homelab/monitoring/log-forwarder.sh &
Symptoms:
Diagnosis:
## Check system resources
top -o cpu
top -o mem
## Monitor network usage
nettop
## Check monitoring resource usage
ps aux | grep -E "(osquery|beszel|fswatch)"
Solutions:
Optimize osquery:
## Edit osquery configuration to reduce frequency
sudo nano /etc/osquery/osquery.conf
## Increase intervals for less critical queries
## Reduce query complexity if needed
Reduce Monitoring Frequency:
## Edit monitoring scripts
nano ~/.homelab/monitoring/*.sh
## Increase sleep intervals
## Reduce data collection frequency
Resource Limits:
## Set resource limits for monitoring processes
## Add to LaunchAgent plist files:
## <key>SoftResourceLimits</key>
## <dict>
## <key>NumberOfFiles</key>
## <integer>256</integer>
## </dict>
Symptoms:
Solutions:
Verify Little Snitch Installation:
Configure Little Snitch Rules:
Symptoms:
Diagnosis:
## Check browser monitoring service
pgrep -f browser-monitor
## Test browser history access
ls -la ~/Library/Safari/History.db
ls -la ~/Library/Application\ Support/Google/Chrome/Default/History
## View browser monitoring logs
tail -f /var/log/family-macbook-browser.log
Solutions:
Fix Browser Permissions:
## Grant Terminal full disk access in System Preferences
## This allows browser history access
## Restart browser monitoring
launchctl unload ~/Library/LaunchAgents/com.homelab.browser-monitor.plist
launchctl load ~/Library/LaunchAgents/com.homelab.browser-monitor.plist
Test History Access:
## Test Safari history access
sqlite3 ~/Library/Safari/History.db "SELECT url, title FROM history_visits LIMIT 5;"
## Test Chrome history access
sqlite3 ~/Library/Application\ Support/Google/Chrome/Default/History "SELECT url, title FROM urls LIMIT 5;"
If monitoring is completely broken:
## 1. Stop all monitoring services
launchctl unload ~/Library/LaunchAgents/com.homelab.*.plist
## 2. Clean up old files
rm -rf ~/.homelab/
sudo rm -f /var/log/family-macbook-*.log
## 3. Reinstall everything
./scripts/install-tools.sh
./scripts/setup-monitoring.sh
./scripts/setup-parental-controls.sh
## 4. Verify installation
./scripts/health-check.sh
For homework or emergency situations:
## Temporary monitoring pause (requires parent approval)
## Create emergency file
touch ~/.homelab/emergency-override
## Monitoring will detect this file and enter emergency mode
## Remove file to resume normal monitoring
rm ~/.homelab/emergency-override
Create Backup:
## Backup all configuration
tar -czf family-macbook-backup-$(date +%Y%m%d).tar.gz ~/.homelab/
## Backup LaunchAgents
cp ~/Library/LaunchAgents/com.homelab.*.plist ~/Desktop/
Restore from Backup:
## Restore configuration
tar -xzf family-macbook-backup-YYYYMMDD.tar.gz -C ~/
## Restore LaunchAgents
cp ~/Desktop/com.homelab.*.plist ~/Library/LaunchAgents/
## Reload services
launchctl load ~/Library/LaunchAgents/com.homelab.*.plist
Analyzing Issues:
## Search for errors in all logs
grep -i error ~/.homelab/logs/*.log
## Check for connection issues
grep -i "connection refused" ~/.homelab/logs/*.log
## Look for permission problems
grep -i "permission denied" ~/.homelab/logs/*.log
## Find service restart events
grep -i "starting\|stopping" ~/.homelab/logs/*.log
./scripts/health-check.sh./scripts/family-dashboard.sh~/.homelab/logs/ for detailed informationQuick Status Check:
## One-line health check
pgrep -f "beszel-agent|osquery|fswatch" && echo "Core services running" || echo "Services need attention"
Resource Usage Check:
## Monitor resource usage
ps aux | grep -E "(beszel|osquery|fswatch)" | awk '{print $2, $3, $4, $11}'
Network Connectivity Test:
## Test all homelab services
for host in seq.speicher.family beszel.speicher.family grafana.speicher.family; do
echo -n "$host: "
ping -c1 $host > /dev/null && echo "OK" || echo "FAIL"
done
This troubleshooting guide covers the most common issues with the family MacBook monitoring system. For persistent problems, document the issue with screenshots and log files before seeking additional help.