Skip to content

FAQ

Agent Operation

Q: How often does the agent sync with Keystash servers?

The sync interval varies by plan:

Plan Refresh Period
Free 5 Min
Essentials 90 Sec
Pro 60 Sec
Business 60 Sec

Q: Does the agent require root access?

Yes, the agent needs root access to manage users and SSH configurations.

Q: Can I use the agent behind a proxy?

Yes, you can configure a proxy using either:

  • The proxy_url setting in the config file
  • Environment variables HTTPS_PROXY or HTTP_PROXY

Connectivity

Q: What happens if the agent loses connection to Keystash servers?

The agent will:

  1. Continue operating with last known configuration
  2. Attempt to reconnect every 60 seconds
  3. After 5 failed authentication attempts, increase retry interval to 60 minutes
  4. Log all connection attempts for troubleshooting

Compatibility

Q: Which Linux distributions are supported?

The agent supports:

  • AlmaLinux 8 and newer
  • Amazon Linux 2
  • Amazon Linux 2023 and newer
  • CentOS 7 and newer
  • Fedora Server 34 and newer
  • Debian 10 and newer
  • Oracle Linux 7 and newer
  • Redhat Enterprise Linux 7 and newer
  • Rocky Linux 8 and newer
  • Ubuntu 18.04 and newer

Verification and Maintenance

Q: How do I verify the agent is running correctly?

Check the server status in the web interface: https://app.keystash.io

Or check the agent status on the server itself: 

systemctl status keystash
Look for "Active: active (running)" in the output.

journalctl -fu keystash
Look for "INFO: Agent refresh completed successfully." in the output.

Q: What ports does the agent need?

The agent requires:

  • Outbound access to server-api.keystash.io on port 443 (HTTPS)

Q: How do I backup the agent configuration?

You can manually backup /etc/keystash/keystash.conf

Upgrades

Q: What happens during an agent upgrade?

The upgrade process:

  1. Preserves all existing configuration
  2. Maintains backup of previous configuration
  3. Automatically restarts the agent service
  4. Verifies connectivity with Keystash servers
  5. Resynchronizes all user and SSH key data

Q: Can I manually trigger a sync with Keystash servers?

Yes, restart the agent to trigger an immediate sync: 

systemctl restart keystash

Note

If you're experiencing issues not covered in this documentation, please reach out to Keystash Support.