Skip to content

Installing and Upgrading the agent

Installing the Agent

The Keystash Agent can be installed using your system's package manager. The installation process varies depending on your Linux distribution.

Info

Everything ships in a single keystash package — the agent binary, its systemd unit, a keystash.conf skeleton, and the bundled pam_keystash.so module that provides Two Factor Authentication and SSH Connection Logging. There is no separate package to install for 2FA.

Debian/Ubuntu Systems

  1. Add the Keystash repository. Download the repository package and install it locally, then refresh your package lists: 

    # Download and install the Keystash repository package
curl -sSL -o /tmp/keystash-repo.deb https://download.keystash.io/keystash-repo_1.0_stable.deb
dpkg -i /tmp/keystash-repo.deb

# Refresh package lists
apt-get update

    Note

    On older Debian/Ubuntu releases, use the legacy repository package keystash-repo_1.0_legacy.deb in place of keystash-repo_1.0_stable.deb.

  2. Install the agent: 

    apt-get install -y keystash

RHEL/CentOS/Fedora Systems

  1. Add the Keystash repository: 

    dnf install -y https://download.keystash.io/keystash-repo-1.0-1.noarch.rpm

  2. Install the agent: 

    dnf install -y keystash

    Note

    For older RHEL/CentOS systems using yum, replace dnf with yum in the commands above.

Upgrading the Agent

Debian/Ubuntu Systems

# Update repository information
apt-get update

# Upgrade only the Keystash package
apt-get install --only-upgrade keystash

RHEL/CentOS/Fedora Systems

# Clean repository cache
dnf clean all

# Update only the Keystash package
dnf update keystash

Note

For older RHEL/CentOS systems using yum, replace dnf with yum in the commands above.

Upgrading from v1.5 to v1.6

Agent v1.6 is a ground-up rewrite, but it ships under the same keystash package name, so apt/dnf treat it as a normal upgrade. We recommend performing the upgrade from the Keystash app rather than by hand — see Remote Upgrades below.

The most important change in v1.6 is that Two Factor Authentication moved out of the old google-authenticator tooling and into the bundled pam_keystash.so module. The upgrade handles this transition for you:

  • The legacy 2FA packages — libpam-google-authenticator on Debian/Ubuntu and otp-authenticator / google-authenticator on RHEL-based systems — are automatically removed.
  • The post-install step rewrites the PAM line to pam_keystash.so before the old package is erased, so 2FA users are never locked out during the upgrade.
  • No manual PAM edits are required, and existing SSH sessions stay connected throughout.
  • The legacy ~/.ssh/two_factor_auth_settings files are no longer used — TOTP secrets are now served to the PAM module in memory over IPC — and the agent removes any that were left behind by an older agent.

Warning

Because this upgrade rewrites the SSH PAM stack, treat it like any other change to authentication: roll it out to a small group of non-production servers first and confirm you can still log in (including with Two Factor Authentication) before upgrading the rest of your fleet.

Note

The agent will only write the enforcing auth required pam_keystash.so line once it has verified the module is present on disk and its IPC socket is reachable. If either check fails it leaves the existing PAM stack untouched and retries, so a partial upgrade cannot produce a deny-all SSH configuration.

Remote Upgrades

The Keystash Agent includes a sophisticated remote upgrade system that ensures safe, reliable upgrades while maintaining system security. Here's how it works:

Overview

Remote upgrades are initiated from the Keystash web interface and are executed in a controlled, monitored fashion on each server. The process is designed to:

  • Maintain system stability
  • Prevent failed or incomplete upgrades
  • Keep your server secure during the upgrade
  • Provide feedback on the upgrade status

Upgrade Process

When an upgrade is initiated, the following steps occur:

  1. Upgrade Execution

    • Package repositories are refreshed using the system package manager
    • Only the Keystash package is upgraded using the system package manager (no other system packages)
    • Configuration files are preserved
    • Upgrade runs in a detached process to maintain stability

  2. Post-upgrade Verification

    • New version is verified
    • Configuration is validated
    • Connection to Keystash servers is confirmed
    • Service is automatically restarted

Monitoring & Status Updates

During the upgrade, you can monitor the process in several ways:

  • Through the Keystash web interface: https://app.keystash.io
  • Via the agent's local logs: /opt/keystash/keystash_update.log
  • Using systemd logs: journalctl -fu keystash

The agent will report its status as:

  • upgrading during the upgrade process
  • connected after successful upgrade
  • error if issues occur during upgrade

Timeouts & Safety Measures

The upgrade process includes several safety measures:

  • Maximum upgrade time of 10 minutes
  • Automatic termination if upgrade exceeds timeout
  • Status monitoring to detect hung processes
  • Automatic retry on transient failures

Warning

If an upgrade exceeds the 10-minute timeout, the agent will:

  • Terminate the upgrade process
  • Report the failure to Keystash servers
  • Continue running on the previous version
  • Log detailed information about the failure in the local logs

Proxy Considerations

If your server uses a proxy:

  • Ensure proxy settings are configured before upgrading
  • The upgrade process will respect existing proxy configuration
  • Both HTTP and HTTPS proxy settings are supported

Log Files

During the upgrade, detailed logs are written to: 

journald                            # Main agent log
/opt/keystash/keystash_update.log   # Upgrade-specific log

Rollback Process

If an upgrade fails:

  1. The previous version remains active
  2. Configuration files are preserved
  3. A detailed error report is generated
  4. The agent continues operating on the previous version
  5. Status is reported to Keystash servers
  6. Use the manual upgrade process to retry the upgrade

Upgrade Best Practices

When performing remote upgrades:

  1. Staging

    • Test upgrades on non-production servers first
    • Use server groups to organize upgrade rollouts
    • Monitor the first few servers in each upgrade batch

  2. Timing

    • Schedule upgrades during maintenance windows
    • Allow sufficient time for upgrades to complete
    • Consider time zones when scheduling upgrades

  3. Monitoring

    • Watch for success notifications
    • Check logs on a sample of upgraded servers
    • Verify agent functionality after upgrade

  4. Troubleshooting

    • Monitor for any user access issues post-upgrade
    • Check system logs for any related errors

Frequently Asked Questions

Q: Can I cancel an in-progress upgrade?

A: Once an upgrade has started on a server, it must complete or timeout.

Q: What happens to user sessions during upgrade?

A: Existing SSH sessions remain active. New key deployments and user updates pause briefly during the upgrade.

Q: Will the upgrade affect my SSH configuration?

A: No, the upgrade process preserves all SSH configurations and user settings.

Q: How do I verify a successful upgrade?

A: You can use the following options to check: 

# Check agent version in the web interface
https://app.keystash.io

# Check agent status
systemctl status keystash

# Verify recent logs
journalctl -u keystash --since "5 minutes ago"

# Check upgrade-specific logs
cat /opt/keystash/keystash_update.log

Tip

Always test upgrades on a small subset of servers before rolling out to your entire infrastructure. This allows you to identify any potential issues in your specific environment.