Troubleshooting

Common Issues

Here are solutions to common issues you might encounter with the Keystash Agent:

Agent Not Starting

1. Check the agent status using systemd:

   systemctl status keystash
   

2. Review the logs:

   journalctl -u keystash
   

3. Verify configuration file permissions:

   ls -l /etc/keystash/keystash.conf
   # Should show: -rw------- 1 root root
   

Authentication Failures

Check your configuration:

• Verify account_id and deployment_secret in your config file
• Ensure network connectivity to server-api.keystash.io
• Check proxy settings if using a proxy

User Synchronization Issues

Verify permissions:

• Check if agent can write to /etc/passwd
• Verify permissions on user home directories
• Look for conflicts with local user management tools

SSH Key Problems

Check file permissions:

• ~/.ssh directories should be 700
• authorized_keys files should be 600
• Verify SELinux/AppArmor aren't blocking access

Logging

The Keystash Agent provides detailed logging to help troubleshoot issues:

1. Enable debug logging:

   /opt/keystash/keystash-key-manager.bin --debug
   

2. View logs:

3. Systemd logs: journalctl -u keystash
4. Agent logs: /opt/keystash_update.log