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

Q: Does the agent log SSH connections?

Yes. On agent v1.6 and newer, the agent (together with its bundled PAM module) can record the full SSH session lifecycle — login attempts, successful authentication, session open/close, and denials — for every server in a Server Group. This is enabled per Server Group from the Keystash app and is on by default. You can read more about it on the SSH Connection Logging page.

Q: What happened to google-authenticator? Does the agent still need it?

No. As of v1.6, Two Factor Authentication is built directly into the bundled pam_keystash.so module, so the agent no longer depends on google-authenticator, otp-authenticator, or libpam-google-authenticator. When you upgrade from an older agent, those legacy packages are automatically removed and the PAM stack is rewritten to use the new module — without locking out 2FA users. See Upgrading from v1.5 to v1.6.

Q: Can I point the agent at a different Keystash server?

Yes. The agent endpoint can be set with the keystash_server, keystash_port, and keystash_protocol keys in keystash.conf, or via the matching KEYSTASH_SERVER, KEYSTASH_PORT, and KEYSTASH_PROTOCOL environment variables. See Endpoint Configuration for the full reference and the precedence rules.

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 on its normal sync tick (around every 60 seconds)
  3. After repeated authentication errors, back off to an extended retry interval of 60 minutes
  4. If the account can no longer be found, hibernate and retry every 12 hours
  5. 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.