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.

Debian/Ubuntu Systems

  1. Add the Keystash repository: 

    apt-get install -y https://download.keystash.io/keystash-repo-1.0-1.noarch.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.4.x to v1.5.x On Fedora, Oracle Linux and RHEL/CentOS 7

If you are running any of the following operating systems, you must follow these steps to upgrade from v1.4.x to v1.5.x: - Fedora (all versions) - Oracle Linux (all versions) - RHEL 7 - CentOS Linux 7

This is due to repository structure changes that will stop Keystash from being able to upgrade.

# Re-install repository package
yum reinstall -y https://download.keystash.io/keystash-repo-1.0-1.noarch.rpm

# Force refresh of repository metadata
yum clean all

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.