ssh-agent, ssh-add

What it does

A key with a passphrase is safe on disk, but typing the passphrase for every connection is slow. ssh-agent is a small background program that holds the unlocked keys in memory. ssh asks the agent to sign the login; the private key never leaves the agent.

ssh-add loads keys into the agent (asking for the passphrase once), lists them and removes them. On a desktop, the agent usually starts with your session; in a plain terminal you start it with eval "$(ssh-agent)".

How to write it

ssh-agent [-c | -s] [-Dd] [-a BIND_ADDRESS] [-E HASH] [-O OPTION] [-P PROVIDERS] [-t LIFE] [COMMAND [ARG ...]]
ssh-agent [-c | -s] -k
ssh-add [-cCDdKkLlqvXx] [-E HASH] [-H HOSTKEY_FILE] [-h DEST] [-S PROVIDER] [-t LIFE] [FILE ...]
ssh-add -s PKCS11 / ssh-add -e PKCS11 / ssh-add -T PUBKEY ...

Options 30

Most used

ssh-agent

-s: Print Bourne shell (bash) commands to set the variables (default for bash).
-c: Print C-shell commands.
-k: Stop the agent of this session (SSH_AGENT_PID).
-t life: Default lifetime of added keys, like 1h.
-a socket: Use this socket path.
-D: Run in the foreground.
-d: Debug mode (foreground with debug output).
-E hash: Fingerprint hash for logs (sha256 or md5).
-O option: Extra options (like no-restrict-websafe).
-P providers: Allowed PKCS#11/FIDO library paths.

ssh-add

(no option): Add the default keys (~/.ssh/id_*).
file: Add this key file.
-l: List the fingerprints of the loaded keys.
-L: List the public keys of the loaded keys.
-d: Remove this key from the agent.
-D: Remove all keys from the agent.
-t life: Keep this key only for this time, like 30m.
-c: Ask for a confirmation each time the key is used.
-x / -X: Lock / unlock the agent with a password.
-k: Load only plain keys, skip certificates.
-K: Load resident keys from a FIDO security key.
-s pkcs11 / -e pkcs11: Add / remove keys from a smart card library.
-S provider: The FIDO provider library.
-T pubkey: Test that the private key for this public key works.
-h destination: Allow the key only for these hosts (destination constraints).
-H file: Known hosts file for destination constraints.
-C: Also load certificates (with -h).
-E hash: Fingerprint hash for -l (sha256 or md5).
-q: Quiet.
-v: Verbose.

Examples 12

$ run as a normal user# run as root (or with sudo)

1Start an agent in your shell
```
$eval "$(ssh-agent -s)"
Agent pid 4321
```
Sets SSH_AUTH_SOCK and SSH_AGENT_PID for this shell.
2Load your key (type the passphrase once)
```
$ssh-add
```
Every ssh in this session now uses the key without asking.
3List the keys in the agent
```
$ssh-add -l
256 SHA256:Xh7… student@server1 (ED25519)
```
"The agent has no identities" = nothing loaded yet.
4Load a key for one hour only
```
$ssh-add -t 1h ~/.ssh/prod_admin
```
After an hour the key is removed automatically. Good for production keys.
5Remove all keys when you leave your desk
```
$ssh-add -D
```
Nobody can use your keys from this session any more.
6Ask before each use of a key
```
$ssh-add -c ~/.ssh/prod_admin
```
A confirmation window appears for each use (needs a graphical askpass program).
7Lock the agent with a password
```
$ssh-add -x
```
Keys stay loaded but cannot be used until ssh-add -X.
8Use the agent on a jump host safely (forward only when needed)
```
$ssh -J admin@bastion admin@10.10.0.15
```
With -J the key stays on your computer; prefer it to agent forwarding (-A).
9Start a command with its own agent
```
$ssh-agent bash -c 'ssh-add ~/.ssh/deploy_key && ./deploy.sh'
```
The agent and the key disappear when the command ends.
10Stop the agent
```
$eval "$(ssh-agent -k)"
```
Kills the agent and clears the variables.
11Limit a key to some servers
```
$ssh-add -h server2.example.com ~/.ssh/id_ed25519
```
The agent refuses to use this key for any other destination.
12Check that the agent is reachable
```
$echo "$SSH_AUTH_SOCK"
```
Empty means no agent is connected to this shell.

Watch out

Agent forwarding (ssh -A) lets root on the remote server use your keys while you are connected. Avoid it on servers you do not fully trust.
An agent started in one terminal is not known in another terminal unless you export SSH_AUTH_SOCK there.

Files

$SSH_AUTH_SOCK: The socket where programs talk to the agent.

Tips to remember

eval "$(ssh-agent)" → ssh-add → work → ssh-add -D.

`ssh-agent, ssh-add`

What it does

How to write it

Options 30

ssh-agent

ssh-add

Examples 12

1Start an agent in your shell

2Load your key (type the passphrase once)

3List the keys in the agent

4Load a key for one hour only

5Remove all keys when you leave your desk

6Ask before each use of a key

7Lock the agent with a password

8Use the agent on a jump host safely (forward only when needed)

9Start a command with its own agent

10Stop the agent

11Limit a key to some servers

12Check that the agent is reachable

Watch out

Files

Tips to remember

Full manual

What it does

How to write it

Options 30

ssh-agent

ssh-add

Examples 12

1Start an agent in your shell

2Load your key (type the passphrase once)

3List the keys in the agent

4Load a key for one hour only

5Remove all keys when you leave your desk

6Ask before each use of a key

7Lock the agent with a password

8Use the agent on a jump host safely (forward only when needed)

9Start a command with its own agent

10Stop the agent

11Limit a key to some servers

12Check that the agent is reachable

Watch out

Files

Tips to remember

Related commands

Used in these lessons

Used in these labs

Full manual

`ssh-agent, ssh-add`