ssh-agent

Start an SSH Agent for the current shell

$ eval $(ssh-agent)

$ ssh-agent -k

ssh-agent [-c | -s] [-D] [-a bind_address] [-E fingerprint_hash] [-P pid_file] [-t life] [command [arg ...]]
ssh-agent [-k]

-s
    Generates sh (Bourne shell) commands to set the necessary environment variables (SSH_AUTH_SOCK and SSH_AGENT_PID). This is the default if the SHELL environment variable suggests a sh-like shell.

-c
    Generates csh (C shell) commands to set the necessary environment variables.

-D
    Causes ssh-agent to daemonize (run in the background). This is the default behavior if no command is specified.

-a bind_address
    Binds the agent's Unix domain socket to the specified bind_address instead of a default temporary directory. This is useful for specific network setups or security hardening.

-E fingerprint_hash
    Specifies the hash algorithm to use when displaying key fingerprints (e.g., `md5` or `sha256`). The default is `sha256`.

-P pid_file
    Writes the agent's process ID (PID) to the specified pid_file. Useful for process management and scripting.

-t life
    Sets a default maximum lifetime (in seconds) for identities added to the agent using ssh-add. Identities will be automatically removed after this period. A value of `0` means no limit.

command [arg ...]
    Executes the specified command with its arguments. The ssh-agent will terminate itself once the command finishes execution.

-k
    Kills the currently running ssh-agent process. This typically requires the SSH_AGENT_PID environment variable to be set, indicating which agent process to terminate.

ssh-agent is a program that holds private keys used for public key authentication with SSH. Its primary purpose is to eliminate the need for users to repeatedly enter passphrases for their encrypted private keys each time they establish an SSH connection. Instead, users add their keys to the agent once using ssh-add, and the agent then handles all subsequent authentication requests by signing challenges on behalf of the SSH client, without ever exposing the private key directly. This enhances both security, by keeping sensitive key material in memory and off disk, and convenience.

When started, ssh-agent typically runs as a background daemon and prints environment variables (SSH_AUTH_SOCK and SSH_AGENT_PID) to standard output. These variables, once `eval`uated by the shell, allow SSH clients and tools like ssh-add to locate and communicate with the running agent. Alternatively, ssh-agent can execute a specified command and terminate itself once that command finishes, making it suitable for integration into scripts or short-lived sessions.

Security Risk with Agent Forwarding: While ssh-agent itself enhances security, using agent forwarding (`-A` option with ssh) can introduce risks. A compromised remote server could potentially hijack your forwarded agent connection and use your keys to authenticate to other systems without your explicit consent. Exercise caution and only forward agents to trusted hosts.
Keys in Memory: The agent stores unencrypted private keys in memory. If your local machine is severely compromised, a malicious process with sufficient privileges could potentially extract these keys from the agent's memory. However, this is generally considered more secure than having unencrypted keys on disk.
Environment Setup: Proper environment variable setup (e.g., `eval $(ssh-agent -s)`) is crucial for ssh and ssh-add to communicate with the agent. Forgetting to set these variables will result in ssh prompting for passphrases directly, bypassing the agent.

The most common way to start and connect to ssh-agent is to execute `eval $(ssh-agent -s)` in a shell. This command starts the agent in the background and then uses `eval` to execute the shell commands printed by ssh-agent. These commands set the SSH_AUTH_SOCK and SSH_AGENT_PID environment variables, which are essential for ssh, ssh-add, and other SSH tools to locate and interact with the running agent instance.

To stop a running ssh-agent and clear its associated environment variables, you can use `eval $(ssh-agent -k)`. This command utilizes the SSH_AGENT_PID variable (which must have been set by a previous `ssh-agent` invocation) to identify and terminate the correct agent process, and then clears the environment variables from the current shell.

Many modern desktop environments (e.g., GNOME, KDE) and login managers include built-in SSH key management. They often automatically start an ssh-agent instance upon user login and handle its lifecycle, including prompting for passphrases for keys loaded into the agent. In such environments, manual invocation of ssh-agent may not be necessary for most users.

ssh-agent is a core component of the OpenSSH suite, designed to significantly improve both the security and user experience of SSH public key authentication. Its development addressed the inconvenience of repeatedly entering passphrases for encrypted private keys, a common deterrent to using stronger key protection. Introduced early in the history of SSH, the agent concept provided a secure in-memory store for private keys, allowing users to unlock their keys once per session (or boot) and then seamlessly use them for multiple connections. This design has become a standard and essential feature for developers and system administrators relying on SSH for daily operations.

ssh(1), ssh-add(1), ssh-keygen(1), sshd(8)