Agent Troubleshooting

This guide helps diagnose and resolve common issues with the PatchCTL agent.

Quick Diagnostics

Run these commands to quickly assess agent health:

# Check service status
sudo systemctl status patchctl

# View recent logs
sudo journalctl -u patchctl --since "10 minutes ago"

# Test API connectivity
curl -I https://api.patchctl.com/health

# Check agent version
/opt/patchctl/bin/patchctl-agent --version

Common Issues

Agent Not Starting

Symptoms: Service fails to start, status shows "failed"

Check logs:

sudo journalctl -u patchctl -n 50

Common causes:

Error	Solution
"config file not found"	Create /etc/patchctl/config.json
"invalid license key"	Verify key in dashboard Settings
"permission denied"	Check file permissions
"binary not found"	Reinstall the agent binary

Fix permissions:

sudo chown -R root:root /opt/patchctl
sudo chmod +x /opt/patchctl/bin/patchctl-agent
sudo chmod 600 /etc/patchctl/config.json

Server Not Appearing in Dashboard

Symptoms: Agent running but server not visible in dashboard

Check heartbeat:

sudo journalctl -u patchctl | grep -i "heartbeat"

Common causes:

1. License key mismatch

   # Verify license key
   sudo cat /etc/patchctl/config.json | grep license_key

2. Network issues

   # Test API connectivity
   curl -v https://api.patchctl.com/health

3. Firewall blocking

   # Check if outbound HTTPS is allowed
   sudo iptables -L OUTPUT -n | grep 443

4. DNS resolution

   # Test DNS
   nslookup api.patchctl.com

Agent Showing Offline

Symptoms: Server appears in dashboard but shows "offline"

Possible causes:

• Agent service stopped
• Network connectivity lost
• Agent crashed

Resolution:

# Check if running
sudo systemctl status patchctl

# Restart if needed
sudo systemctl restart patchctl

# Watch logs for errors
sudo journalctl -u patchctl -f

Patch Operations Failing

Symptoms: Updates fail to install via dashboard

Check agent logs during operation:

sudo journalctl -u patchctl -f

Common causes:

Issue	Solution
Package manager locked	Wait or kill stale process
Disk full	Free space on root partition
Broken dependencies	Run package manager manually
Repository errors	Refresh repository cache

Package manager fixes:

# Ubuntu/Debian
sudo apt update
sudo dpkg --configure -a
sudo apt --fix-broken install

# RHEL/Rocky
sudo dnf clean all
sudo dnf makecache

# SUSE
sudo zypper refresh
sudo zypper clean --all

High CPU or Memory Usage

Symptoms: Agent consuming excessive resources

Check resource usage:

# CPU and memory
ps aux | grep patchctl-agent

# Open files
sudo lsof -p $(pgrep patchctl-agent) | wc -l

Possible causes:

• Large package list causing slow scans
• Network timeouts causing retries
• Debug logging enabled

Resolution:

1. Set log level to info (not debug)
2. Restart the agent
3. Contact support if issue persists

SSL/TLS Errors

Symptoms: Certificate verification failures

Common errors:

• "certificate verify failed"
• "SSL: CERTIFICATE_VERIFY_FAILED"

Check certificates:

# Test SSL connection
openssl s_client -connect api.patchctl.com:443 -brief

Fixes:

# Ubuntu/Debian - update CA certificates
sudo apt install --reinstall ca-certificates
sudo update-ca-certificates

# RHEL/Rocky
sudo dnf reinstall ca-certificates
sudo update-ca-trust

# SUSE
sudo zypper install -f ca-certificates
sudo update-ca-certificates

Corporate proxy with SSL inspection:

# Add corporate CA
sudo cp corporate-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Log Analysis

Log Location

# Via journald (recommended)
sudo journalctl -u patchctl

# Log file (if configured)
/opt/patchctl/var/log/agent.log

Important Log Messages

Message	Meaning
"Heartbeat sent successfully"	Normal operation
"Package scan completed"	Package inventory updated
"Command received"	Processing dashboard request
"Update installed"	Patch applied successfully
"Connection failed"	Network issue
"Authentication failed"	License key problem

Enable Debug Logging

Temporarily enable verbose logging:

# Edit config
sudo nano /etc/patchctl/config.json
# Change "log_level": "info" to "log_level": "debug"

# Restart
sudo systemctl restart patchctl

# Watch logs
sudo journalctl -u patchctl -f

Remember to set back to info after troubleshooting.

Getting Help

If you can't resolve an issue:

1. Collect diagnostics:

   sudo journalctl -u patchctl --since "1 hour ago" > agent-logs.txt
   cat /etc/patchctl/config.json | grep -v license_key > agent-config.txt
   uname -a > system-info.txt

2. Contact support via the dashboard or email with:

   • Agent logs
   • System information
   • Description of the issue
   • Steps to reproduce