Agent Troubleshooting

Agent Troubleshooting

Diagnose and resolve common SSH-KLM agent issues.

Diagnostic Commands

# Check agent status
sudo systemctl status ssh-klm-agent

# View recent logs
sudo journalctl -u ssh-klm-agent -n 100

# Follow logs in real-time
sudo journalctl -u ssh-klm-agent -f

# Agent self-test
sudo ssh-klm-agent diagnose

Common Issues

Agent Not Connecting

Symptoms: Agent shows “disconnected” in UI

Diagnosis:

# Test connectivity
curl -v https://ssh-klm.example.com/health

# Check DNS resolution
nslookup ssh-klm.example.com

# Test with agent
sudo ssh-klm-agent test-connection

Solutions:

1. Verify server URL in config
2. Check firewall allows outbound 443/8443
3. Validate registration token
4. Check proxy settings if applicable

Registration Failed

Symptoms: registration failed: invalid token

Solutions:

1. Generate new registration token
2. Check token hasn’t expired
3. Verify token host limit not reached

# Re-register agent
sudo ssh-klm-agent configure \
  --server https://ssh-klm.example.com \
  --token NEW_TOKEN \
  --force

Discovery Returns No Keys

Symptoms: Scan completes with 0 keys

Diagnosis:

# Check paths being scanned
sudo ssh-klm-agent config show | grep -A10 discovery

# Manual check
sudo ls -la /home/*/.ssh/

Solutions:

1. Verify discovery paths in config
2. Check agent has read permissions
3. Ensure SSH directories exist

# Test discovery manually
sudo ssh-klm-agent discovery run --dry-run

High Memory Usage

Symptoms: Agent using excessive memory

Solutions:

1. Reduce concurrent scans:

resources:
  maxConcurrentScans: 1

2. Increase scan interval
3. Exclude large directories

Agent Crashes

Symptoms: Service restarts frequently

Diagnosis:

# Check for crash logs
sudo journalctl -u ssh-klm-agent | grep -i "panic\|fatal\|error"

# Check system resources
free -h
df -h

Solutions:

1. Check disk space
2. Verify memory available
3. Update to latest agent version

Certificate Errors

Symptoms: TLS handshake failures

Solutions:

# Update CA certificates
sudo update-ca-certificates

# Or specify CA in config
server:
  tls:
    caCert: /path/to/ca.crt

Debug Mode

Enable verbose logging:

logging:
  level: debug

Or via environment:

SSHKLM_LOG_LEVEL=debug sudo ssh-klm-agent run

Collecting Support Bundle

# Generate diagnostic bundle
sudo ssh-klm-agent support-bundle --output /tmp/agent-diag.tar.gz

# Contents:
# - Configuration (secrets redacted)
# - Recent logs
# - System information
# - Network diagnostics

Related Pages

• Agent Installation
• Agent Configuration
• Operations Troubleshooting