1180740SdesSSH-AGENT(1) OpenBSD Reference Manual SSH-AGENT(1) 2180740Sdes 3180740SdesNAME 4180740Sdes ssh-agent - authentication agent 5180740Sdes 6180740SdesSYNOPSIS 7180746Sdes ssh-agent [-c | -s] [-d] [-a bind_address] [-t life] [command [arg ...]] 8180740Sdes ssh-agent [-c | -s] -k 9180740Sdes 10180740SdesDESCRIPTION 11214979Sdes ssh-agent is a program to hold private keys used for public key 12262566Sdes authentication (RSA, DSA, ECDSA, ED25519). The idea is that ssh-agent is 13262566Sdes started in the beginning of an X-session or a login session, and all 14262566Sdes other windows or programs are started as clients to the ssh-agent 15262566Sdes program. Through use of environment variables the agent can be located 16262566Sdes and automatically used for authentication when logging in to other 17262566Sdes machines using ssh(1). 18180740Sdes 19180740Sdes The options are as follows: 20180740Sdes 21180740Sdes -a bind_address 22214979Sdes Bind the agent to the UNIX-domain socket bind_address. The 23218767Sdes default is $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>. 24180740Sdes 25180740Sdes -c Generate C-shell commands on stdout. This is the default if 26180740Sdes SHELL looks like it's a csh style of shell. 27180740Sdes 28180746Sdes -d Debug mode. When this option is specified ssh-agent will not 29180746Sdes fork. 30180740Sdes 31180740Sdes -k Kill the current agent (given by the SSH_AGENT_PID environment 32180740Sdes variable). 33180740Sdes 34180746Sdes -s Generate Bourne shell commands on stdout. This is the default if 35180746Sdes SHELL does not look like it's a csh style of shell. 36180746Sdes 37180740Sdes -t life 38180740Sdes Set a default value for the maximum lifetime of identities added 39180740Sdes to the agent. The lifetime may be specified in seconds or in a 40180740Sdes time format specified in sshd_config(5). A lifetime specified 41180740Sdes for an identity with ssh-add(1) overrides this value. Without 42180740Sdes this option the default maximum lifetime is forever. 43180740Sdes 44180740Sdes If a commandline is given, this is executed as a subprocess of the agent. 45180740Sdes When the command dies, so does the agent. 46180740Sdes 47180740Sdes The agent initially does not have any private keys. Keys are added using 48180740Sdes ssh-add(1). When executed without arguments, ssh-add(1) adds the files 49262566Sdes ~/.ssh/id_rsa, ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519 and 50262566Sdes ~/.ssh/identity. If the identity has a passphrase, ssh-add(1) asks for 51262566Sdes the passphrase on the terminal if it has one or from a small X11 program 52262566Sdes if running under X11. If neither of these is the case then the 53262566Sdes authentication will fail. It then sends the identity to the agent. 54262566Sdes Several identities can be stored in the agent; the agent can 55262566Sdes automatically use any of these identities. ssh-add -l displays the 56262566Sdes identities currently held by the agent. 57180740Sdes 58214979Sdes The idea is that the agent is run in the user's local PC, laptop, or 59214979Sdes terminal. Authentication data need not be stored on any other machine, 60214979Sdes and authentication passphrases never go over the network. However, the 61214979Sdes connection to the agent is forwarded over SSH remote logins, and the user 62214979Sdes can thus use the privileges given by the identities anywhere in the 63214979Sdes network in a secure way. 64180740Sdes 65180740Sdes There are two main ways to get an agent set up: The first is that the 66180740Sdes agent starts a new subcommand into which some environment variables are 67180740Sdes exported, eg ssh-agent xterm &. The second is that the agent prints the 68180740Sdes needed shell commands (either sh(1) or csh(1) syntax can be generated) 69197670Sdes which can be evaluated in the calling shell, eg eval `ssh-agent -s` for 70180740Sdes Bourne-type shells such as sh(1) or ksh(1) and eval `ssh-agent -c` for 71180740Sdes csh(1) and derivatives. 72180740Sdes 73214979Sdes Later ssh(1) looks at these variables and uses them to establish a 74214979Sdes connection to the agent. 75180740Sdes 76214979Sdes The agent will never send a private key over its request channel. 77214979Sdes Instead, operations that require a private key will be performed by the 78214979Sdes agent, and the result will be returned to the requester. This way, 79214979Sdes private keys are not exposed to clients using the agent. 80180740Sdes 81204861Sdes A UNIX-domain socket is created and the name of this socket is stored in 82180740Sdes the SSH_AUTH_SOCK environment variable. The socket is made accessible 83214979Sdes only to the current user. This method is easily abused by root or 84214979Sdes another instance of the same user. 85180740Sdes 86180740Sdes The SSH_AGENT_PID environment variable holds the agent's process ID. 87180740Sdes 88180740Sdes The agent exits automatically when the command given on the command line 89180740Sdes terminates. 90180740Sdes 91180740SdesFILES 92180740Sdes ~/.ssh/identity 93180740Sdes Contains the protocol version 1 RSA authentication identity of 94180740Sdes the user. 95180740Sdes 96180740Sdes ~/.ssh/id_dsa 97180740Sdes Contains the protocol version 2 DSA authentication identity of 98180740Sdes the user. 99180740Sdes 100218767Sdes ~/.ssh/id_ecdsa 101218767Sdes Contains the protocol version 2 ECDSA authentication identity of 102218767Sdes the user. 103218767Sdes 104262566Sdes ~/.ssh/id_ed25519 105262566Sdes Contains the protocol version 2 ED25519 authentication identity 106262566Sdes of the user. 107262566Sdes 108180740Sdes ~/.ssh/id_rsa 109180740Sdes Contains the protocol version 2 RSA authentication identity of 110180740Sdes the user. 111180740Sdes 112218767Sdes $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid> 113214979Sdes UNIX-domain sockets used to contain the connection to the 114214979Sdes authentication agent. These sockets should only be readable by 115214979Sdes the owner. The sockets should get automatically removed when the 116180740Sdes agent exits. 117180740Sdes 118180740SdesSEE ALSO 119180740Sdes ssh(1), ssh-add(1), ssh-keygen(1), sshd(8) 120180740Sdes 121180740SdesAUTHORS 122180740Sdes OpenSSH is a derivative of the original and free ssh 1.2.12 release by 123180740Sdes Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 124214979Sdes de Raadt and Dug Song removed many bugs, re-added newer features and 125214979Sdes created OpenSSH. Markus Friedl contributed the support for SSH protocol 126180740Sdes versions 1.5 and 2.0. 127180740Sdes 128264377SdesOpenBSD 5.5 December 7, 2013 OpenBSD 5.5 129