Skip to content

Keystash Agent

The Keystash Agent runs on your Linux servers to manage users, SSH keys, and security configurations. This guide covers everything you need to know about the agent.

The agent is a single, statically-compiled Go binary with no external runtime dependencies, and it ships alongside a self-contained PAM module (pam_keystash.so) that handles Two Factor Authentication and SSH Connection Logging. Both are delivered together in one keystash package, so a standard install or upgrade gives you everything you need.

Hardware Requirements

The Keystash Agent is designed to be lightweight and efficient, requiring minimal system resources to operate effectively.

Minimum Requirements

Resource Requirement Notes
RAM 15 MB Peak memory usage during user synchronization
CPU 1 core Any speed; agent is not CPU intensive
Disk Space 6 MB Includes agent and configuration

Detailed Resource Usage

Memory Usage

  • Idle footprint is a few MB
  • Peak usage: Up to 15 MB during:
    • User synchronization
    • SSH key updates
    • Two-factor authentication configuration

CPU Usage

  • Idle: <0.1% of one core
  • Active: Brief spikes during:
    • User updates
    • Configuration changes
    • Key synchronization
  • No multi-core optimization needed

Disk Space Breakdown

  • Agent binary and PAM module: ~6 MB
  • Configuration: 0.1 MB

While the agent can run with minimal resources, we recommend:

  • 20 MB RAM allocation for optimal performance
  • 100 MB disk space for logs and future updates
  • Network bandwidth: 1 Mbps or higher

Tip

The agent is designed to run efficiently in resource-constrained environments like containers and virtual machines.

Software Requirements

The Keystash Agent has different dependencies based on your Linux distribution. All packages are installed automatically through the package manager during installation.

Supported Distributions

  • 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

Debian/Ubuntu Requirements

  • sudo: For managing user permissions and access
  • systemd: For service management

RHEL/CentOS/Fedora Requirements

  • sudo: For managing user permissions and access
  • systemd: For service management

Note

Two Factor Authentication is now built directly into the bundled pam_keystash.so module — there is no longer any dependency on google-authenticator, otp-authenticator, or libpam-google-authenticator. When you upgrade from an older agent, these legacy packages are automatically removed and the PAM stack is rewritten to use the new module. See Upgrading from v1.5 to v1.6 for details.

SSH Connection Logging

Agent v1.6 and newer can record the full SSH session lifecycle — login attempts, successful authentication, session open/close, and denials — for every server running the agent, and surface those sessions in the Keystash app. This is handled by the same bundled PAM module, so no extra software is required. See SSH Connection Logging to learn more.

System Requirements

  • Architecture: x86_64/amd64 (64-bit) and Aarch64/ ARM64 (64-bit) systems only

  • Package Manager:

    • Debian/Ubuntu: apt and dpkg
    • RHEL/CentOS/Fedora: yum or dnf

  • Systemd: Required for service management

  • SSL/TLS: Required for secure communication with Keystash servers

Warning

32-bit (i386/i686) systems are not supported. Ensure you are running a 64-bit operating system before installation.