Adam Langley | d059297 | 2015-03-30 14:49:51 -0700 | [diff] [blame] | 1 | SSH-AGENT(1) General Commands Manual SSH-AGENT(1) |
Greg Hartman | bd77cf7 | 2015-02-25 13:21:06 -0800 | [diff] [blame] | 2 | |
| 3 | NAME |
Adam Langley | d059297 | 2015-03-30 14:49:51 -0700 | [diff] [blame] | 4 | ssh-agent M-bM-^@M-^S authentication agent |
Greg Hartman | bd77cf7 | 2015-02-25 13:21:06 -0800 | [diff] [blame] | 5 | |
| 6 | SYNOPSIS |
Adam Langley | d059297 | 2015-03-30 14:49:51 -0700 | [diff] [blame] | 7 | ssh-agent [-c | -s] [-d] [-a bind_address] [-E fingerprint_hash] |
| 8 | [-t life] [command [arg ...]] |
Greg Hartman | bd77cf7 | 2015-02-25 13:21:06 -0800 | [diff] [blame] | 9 | ssh-agent [-c | -s] -k |
| 10 | |
| 11 | DESCRIPTION |
| 12 | ssh-agent is a program to hold private keys used for public key |
Adam Langley | d059297 | 2015-03-30 14:49:51 -0700 | [diff] [blame] | 13 | authentication (RSA, DSA, ECDSA, Ed25519). ssh-agent is usually started |
Greg Hartman | bd77cf7 | 2015-02-25 13:21:06 -0800 | [diff] [blame] | 14 | in the beginning of an X-session or a login session, and all other |
| 15 | windows or programs are started as clients to the ssh-agent program. |
| 16 | Through use of environment variables the agent can be located and |
| 17 | automatically used for authentication when logging in to other machines |
| 18 | using ssh(1). |
| 19 | |
Adam Langley | d059297 | 2015-03-30 14:49:51 -0700 | [diff] [blame] | 20 | The agent initially does not have any private keys. Keys are added using |
| 21 | ssh-add(1). Multiple identities may be stored in ssh-agent concurrently |
| 22 | and ssh(1) will automatically use them if present. ssh-add(1) is also |
| 23 | used to remove keys from ssh-agent and to query the keys that are held in |
| 24 | one. |
| 25 | |
Greg Hartman | bd77cf7 | 2015-02-25 13:21:06 -0800 | [diff] [blame] | 26 | The options are as follows: |
| 27 | |
| 28 | -a bind_address |
| 29 | Bind the agent to the UNIX-domain socket bind_address. The |
| 30 | default is $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>. |
| 31 | |
| 32 | -c Generate C-shell commands on stdout. This is the default if |
| 33 | SHELL looks like it's a csh style of shell. |
| 34 | |
| 35 | -d Debug mode. When this option is specified ssh-agent will not |
| 36 | fork. |
| 37 | |
Adam Langley | d059297 | 2015-03-30 14:49:51 -0700 | [diff] [blame] | 38 | -E fingerprint_hash |
| 39 | Specifies the hash algorithm used when displaying key |
| 40 | fingerprints. Valid options are: M-bM-^@M-^\md5M-bM-^@M-^] and M-bM-^@M-^\sha256M-bM-^@M-^]. The |
| 41 | default is M-bM-^@M-^\sha256M-bM-^@M-^]. |
| 42 | |
Greg Hartman | bd77cf7 | 2015-02-25 13:21:06 -0800 | [diff] [blame] | 43 | -k Kill the current agent (given by the SSH_AGENT_PID environment |
| 44 | variable). |
| 45 | |
| 46 | -s Generate Bourne shell commands on stdout. This is the default if |
| 47 | SHELL does not look like it's a csh style of shell. |
| 48 | |
| 49 | -t life |
| 50 | Set a default value for the maximum lifetime of identities added |
| 51 | to the agent. The lifetime may be specified in seconds or in a |
| 52 | time format specified in sshd_config(5). A lifetime specified |
| 53 | for an identity with ssh-add(1) overrides this value. Without |
| 54 | this option the default maximum lifetime is forever. |
| 55 | |
| 56 | If a commandline is given, this is executed as a subprocess of the agent. |
| 57 | When the command dies, so does the agent. |
| 58 | |
Greg Hartman | bd77cf7 | 2015-02-25 13:21:06 -0800 | [diff] [blame] | 59 | The idea is that the agent is run in the user's local PC, laptop, or |
| 60 | terminal. Authentication data need not be stored on any other machine, |
| 61 | and authentication passphrases never go over the network. However, the |
| 62 | connection to the agent is forwarded over SSH remote logins, and the user |
| 63 | can thus use the privileges given by the identities anywhere in the |
| 64 | network in a secure way. |
| 65 | |
| 66 | There are two main ways to get an agent set up: The first is that the |
| 67 | agent starts a new subcommand into which some environment variables are |
| 68 | exported, eg ssh-agent xterm &. The second is that the agent prints the |
| 69 | needed shell commands (either sh(1) or csh(1) syntax can be generated) |
| 70 | which can be evaluated in the calling shell, eg eval `ssh-agent -s` for |
| 71 | Bourne-type shells such as sh(1) or ksh(1) and eval `ssh-agent -c` for |
| 72 | csh(1) and derivatives. |
| 73 | |
| 74 | Later ssh(1) looks at these variables and uses them to establish a |
| 75 | connection to the agent. |
| 76 | |
| 77 | The agent will never send a private key over its request channel. |
| 78 | Instead, operations that require a private key will be performed by the |
| 79 | agent, and the result will be returned to the requester. This way, |
| 80 | private keys are not exposed to clients using the agent. |
| 81 | |
| 82 | A UNIX-domain socket is created and the name of this socket is stored in |
| 83 | the SSH_AUTH_SOCK environment variable. The socket is made accessible |
| 84 | only to the current user. This method is easily abused by root or |
| 85 | another instance of the same user. |
| 86 | |
| 87 | The SSH_AGENT_PID environment variable holds the agent's process ID. |
| 88 | |
| 89 | The agent exits automatically when the command given on the command line |
| 90 | terminates. |
| 91 | |
| 92 | FILES |
Greg Hartman | bd77cf7 | 2015-02-25 13:21:06 -0800 | [diff] [blame] | 93 | $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid> |
| 94 | UNIX-domain sockets used to contain the connection to the |
| 95 | authentication agent. These sockets should only be readable by |
| 96 | the owner. The sockets should get automatically removed when the |
| 97 | agent exits. |
| 98 | |
| 99 | SEE ALSO |
| 100 | ssh(1), ssh-add(1), ssh-keygen(1), sshd(8) |
| 101 | |
| 102 | AUTHORS |
| 103 | OpenSSH is a derivative of the original and free ssh 1.2.12 release by |
| 104 | Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo |
| 105 | de Raadt and Dug Song removed many bugs, re-added newer features and |
| 106 | created OpenSSH. Markus Friedl contributed the support for SSH protocol |
| 107 | versions 1.5 and 2.0. |
| 108 | |
Adam Langley | d059297 | 2015-03-30 14:49:51 -0700 | [diff] [blame] | 109 | OpenBSD 5.7 December 21, 2014 OpenBSD 5.7 |