5 UNIX / Linux ssh-agent Command Examples to Manage SSH Private Keys

ssh-agent is used to hold the private keys of remote server, which can be used to authenticate from the local machine.

The idea is once you add private keys using ssh-add command to the ssh-agent, you can login to the remote machine without having to enter the password.

If you are new to this, you should first understand how ssh-add command works.

1. Start the ssh-agent

You can start the ssh-agent from your session, as shown below. By default, you can start it without any parameter as shown below.

# ssh-agent
SSH_AUTH_SOCK=/tmp/ssh-pwrid11012/agent.11012; export SSH_AUTH_SOCK;
echo Agent pid 11013;

In this case, the parent PID for the ssh-agent will be 1. So, it is not tied to the current terminal.

# ps -ef | grep ssh-agent
root     11013     1  0 14:09 ?        00:00:00 ssh-agent

If you want to start ssh-agent only for your terminal session, it is recommend that you pass the shell command variable (i.e /bin/bash to the ssh-agent while starting it as shown below). In this case, the ssh-agent will be forked from the current terminal, as you see below, the parent PID of the ssh-agent is the current terminal’s bash process.

# ssh-agent $SHELL

# ps -ef | grep ssh-agent
root     11020 11019  0 14:10 ?        00:00:00 ssh-agent /bin/bash

2. Stop / Kill the ssh-agent

While you can use kill -9 command to kill the ssh-agent process, it is recommend that you use the -k option as shown below.

# ssh-agent -k
echo Agent pid 11020 killed;

# ps -ef | grep ssh-agent

3. Run ssh-agent in debug mode

For some reason, after you’ve added the keys ot the ssh-agent, if it still asks for password when you ssh to remote server, you may want to debug and see if ssh-agent has the right keys.

You can run ssh-agent in the debug mode as shown below. Please note that when you run in debug mode, it will run in the foreground mode.

# ssh-agent -d
SSH_AUTH_SOCK=/tmp/ssh-AVGCG11176/agent.11176; export SSH_AUTH_SOCK;
echo Agent pid 11176;

4. Set Bind Socket Name

By default, the ssh-agent binds to a socket under /tmp directory (for example: SSH_AUTH_SOCK=/tmp/ssh-UMmVe11244/agent.11244). If you are concerned about this for security reasons, you can specify your own socket file name under your home directory (or anywhere else), instead of the /tmp directory.

The following example will use the my-ssh-socket file for the SSH_AUTH_SOCK.

# ssh-agent -a ~/my-ssh-socket $SHELL

After starting the ssh-agent, you can verify that the bind socket is created in the location you’ve specified.

# ls -al ~/my-ssh-socket
srw-------. 1 root root 0 Sep  4 14:39 /root/my-ssh-socket

When this ssh-agent is killed properly, this bind socket file will be deleted automatically by the ssh-agent as shown below.

# ssh-agent -k
echo Agent pid 11254 killed;

# ls -al ~/my-ssh-socket
ls: cannot access /root/my-ssh-socket: No such file or directory

5. Set Expiry Time for Keys

By default, the keys added to the ssh-agent doesn’t expire. They stay there as long as ssh-agent is running. However you can set an expire time using the -t option as shown below.

In the following example, the keys will expire after 3600 second, which is 1 hour.

# ssh-agent -t 3600 $SHELL

You can also use one of the following time qualifiers

  • m | M minutes (for example: 5M for 5 minutes)
  • h | H hours (for example: 5h for 5 hours)
  • d | D days (for example: 5D for 5 days)
  • w | W weeks (for example 5w for 5 weeks)

In the following example, the keys will expire after 3 days.

# ssh-agent -t 3d $SHELL