Troubleshooting
Troubleshooting
Section titled “Troubleshooting”Common issues and solutions for SSH-KLM.
Discovery Issues
Section titled “Discovery Issues”No Keys Found
Section titled “No Keys Found”Symptoms: Discovery scan completes but reports 0 keys
Solutions:
- Verify agent has read permissions:
Terminal window sudo -u sshklm ls -la /home/*/.ssh/ - Check discovery paths in config
- Review agent logs:
Terminal window sudo journalctl -u ssh-klm-agent | grep discovery
Scan Timeout
Section titled “Scan Timeout”Symptoms: Discovery times out on large hosts
Solutions:
- Increase timeout:
discovery:timeout: 600 # 10 minutes
- Use incremental scans
- Exclude large directories
Rotation Issues
Section titled “Rotation Issues”Rotation Failed
Section titled “Rotation Failed”Symptoms: Key rotation fails with error
Common Causes:
- SSH daemon not accepting key type
authorized_keysfile permissions- Agent connectivity issues
Solutions:
- Check SSH config:
Terminal window grep PubkeyAcceptedKeyTypes /etc/ssh/sshd_config - Fix permissions:
Terminal window chmod 600 ~/.ssh/authorized_keyschmod 700 ~/.ssh
Locked Out After Rotation
Section titled “Locked Out After Rotation”Symptoms: Cannot SSH after rotation
Solutions:
- Use rollback:
await client.ssh.rollbackRotation({ rotationId: 'ROT-xxx' });
- Access via console/out-of-band
- Restore from backup key
Agent Issues
Section titled “Agent Issues”Agent Not Connecting
Section titled “Agent Not Connecting”Symptoms: Agent shows disconnected in UI
Solutions:
- Check network:
Terminal window curl -v https://ssh-klm.example.com/health - Verify token:
Terminal window sudo ssh-klm-agent verify-token - Check firewall:
Terminal window sudo ufw allow out 443/tcp
Agent High CPU
Section titled “Agent High CPU”Symptoms: Agent using excessive CPU
Solutions:
- Increase discovery interval
- Exclude unnecessary paths
- Check for filesystem issues
API Issues
Section titled “API Issues”401 Unauthorized
Section titled “401 Unauthorized”Symptoms: API returns 401 errors
Solutions:
- Verify API key is valid
- Check key hasn’t expired
- Confirm key has required permissions
429 Rate Limited
Section titled “429 Rate Limited”Symptoms: Requests being rejected
Solutions:
- Implement exponential backoff
- Cache responses where possible
- Request rate limit increase
Database Issues
Section titled “Database Issues”Connection Errors
Section titled “Connection Errors”Symptoms: Database connection failures
Solutions:
- Check PostgreSQL is running:
Terminal window sudo systemctl status postgresql - Verify connection string
- Check pg_hba.conf for access rules
Getting Help
Section titled “Getting Help”If issues persist:
- Collect logs:
Terminal window sudo ssh-klm-agent logs --since 1h > agent-logs.txt - Check documentation
- Contact support with:
- Error messages
- Log files
- Steps to reproduce