1.\" $OpenBSD: ssh-agent.1,v 1.72 2020/06/22 05:52:05 djm Exp $ 2.\" $FreeBSD$ 3.\" 4.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 5.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 6.\" All rights reserved 7.\" 8.\" As far as I am concerned, the code I have written for this software 9.\" can be used freely for any purpose. Any derived versions of this 10.\" software must be clearly marked as such, and if the derived work is 11.\" incompatible with the protocol description in the RFC file, it must be 12.\" called by a name other than "ssh" or "Secure Shell". 13.\" 14.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 15.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 16.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 17.\" 18.\" Redistribution and use in source and binary forms, with or without 19.\" modification, are permitted provided that the following conditions 20.\" are met: 21.\" 1. Redistributions of source code must retain the above copyright 22.\" notice, this list of conditions and the following disclaimer. 23.\" 2. Redistributions in binary form must reproduce the above copyright 24.\" notice, this list of conditions and the following disclaimer in the 25.\" documentation and/or other materials provided with the distribution. 26.\" 27.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 28.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 29.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 30.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 31.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 32.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 33.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 34.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 35.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 36.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd $Mdocdate: June 22 2020 $ 39.Dt SSH-AGENT 1 40.Os 41.Sh NAME 42.Nm ssh-agent 43.Nd OpenSSH authentication agent 44.Sh SYNOPSIS 45.Nm ssh-agent 46.Op Fl c | s 47.Op Fl \&Ddx 48.Op Fl a Ar bind_address 49.Op Fl E Ar fingerprint_hash 50.Op Fl P Ar allowed_providers 51.Op Fl t Ar life 52.Nm ssh-agent 53.Op Fl a Ar bind_address 54.Op Fl E Ar fingerprint_hash 55.Op Fl P Ar allowed_providers 56.Op Fl t Ar life 57.Ar command Op Ar arg ... 58.Nm ssh-agent 59.Op Fl c | s 60.Fl k 61.Sh DESCRIPTION 62.Nm 63is a program to hold private keys used for public key authentication. 64Through use of environment variables the agent can be located 65and automatically used for authentication when logging in to other 66machines using 67.Xr ssh 1 . 68.Pp 69The options are as follows: 70.Bl -tag -width Ds 71.It Fl a Ar bind_address 72Bind the agent to the 73.Ux Ns -domain 74socket 75.Ar bind_address . 76The default is 77.Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt . 78.It Fl c 79Generate C-shell commands on 80.Dv stdout . 81This is the default if 82.Ev SHELL 83looks like it's a csh style of shell. 84.It Fl D 85Foreground mode. 86When this option is specified 87.Nm 88will not fork. 89.It Fl d 90Debug mode. 91When this option is specified 92.Nm 93will not fork and will write debug information to standard error. 94.It Fl E Ar fingerprint_hash 95Specifies the hash algorithm used when displaying key fingerprints. 96Valid options are: 97.Dq md5 98and 99.Dq sha256 . 100The default is 101.Dq sha256 . 102.It Fl k 103Kill the current agent (given by the 104.Ev SSH_AGENT_PID 105environment variable). 106.It Fl P Ar allowed_providers 107Specify a pattern-list of acceptable paths for PKCS#11 provider and FIDO 108authenticator middleware shared libraries that may be used with the 109.Fl S 110or 111.Fl s 112options to 113.Xr ssh-add 1 . 114Libraries that do not match the pattern list will be refused. 115See PATTERNS in 116.Xr ssh_config 5 117for a description of pattern-list syntax. 118The default list is 119.Dq /usr/lib/*,/usr/local/lib/* . 120.It Fl s 121Generate Bourne shell commands on 122.Dv stdout . 123This is the default if 124.Ev SHELL 125does not look like it's a csh style of shell. 126.It Fl t Ar life 127Set a default value for the maximum lifetime of identities added to the agent. 128The lifetime may be specified in seconds or in a time format specified in 129.Xr sshd_config 5 . 130A lifetime specified for an identity with 131.Xr ssh-add 1 132overrides this value. 133Without this option the default maximum lifetime is forever. 134.It Ar command Op Ar arg ... 135If a command (and optional arguments) is given, 136this is executed as a subprocess of the agent. 137The agent exits automatically when the command given on the command 138line terminates. 139.It Fl x 140Exit after the last client has disconnected. 141.El 142.Pp 143There are two main ways to get an agent set up. 144The first is at the start of an X session, 145where all other windows or programs are started as children of the 146.Nm 147program. 148The agent starts a command under which its environment 149variables are exported, for example 150.Cm ssh-agent xterm & . 151When the command terminates, so does the agent. 152.Pp 153The second method is used for a login session. 154When 155.Nm 156is started, 157it prints the shell commands required to set its environment variables, 158which in turn can be evaluated in the calling shell, for example 159.Cm eval `ssh-agent -s` . 160.Pp 161In both cases, 162.Xr ssh 1 163looks at these environment variables 164and uses them to establish a connection to the agent. 165.Pp 166The agent initially does not have any private keys. 167Keys are added using 168.Xr ssh-add 1 169or by 170.Xr ssh 1 171when 172.Cm AddKeysToAgent 173is set in 174.Xr ssh_config 5 . 175Multiple identities may be stored in 176.Nm 177concurrently and 178.Xr ssh 1 179will automatically use them if present. 180.Xr ssh-add 1 181is also used to remove keys from 182.Nm 183and to query the keys that are held in one. 184.Pp 185Connections to 186.Nm 187may be forwarded from further remote hosts using the 188.Fl A 189option to 190.Xr ssh 1 191(but see the caveats documented therein), 192avoiding the need for authentication data to be stored on other machines. 193Authentication passphrases and private keys never go over the network: 194the connection to the agent is forwarded over SSH remote connections 195and the result is returned to the requester, 196allowing the user access to their identities anywhere in the network 197in a secure fashion. 198.Sh ENVIRONMENT 199.Bl -tag -width "SSH_AGENT_PID" 200.It Ev SSH_AGENT_PID 201When 202.Nm 203starts, it stores the name of the agent's process ID (PID) in this variable. 204.It Ev SSH_AUTH_SOCK 205When 206.Nm 207starts, it creates a 208.Ux Ns -domain 209socket and stores its pathname in this variable. 210It is accessible only to the current user, 211but is easily abused by root or another instance of the same user. 212.El 213.Sh FILES 214.Bl -tag -width Ds 215.It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid> 216.Ux Ns -domain 217sockets used to contain the connection to the authentication agent. 218These sockets should only be readable by the owner. 219The sockets should get automatically removed when the agent exits. 220.El 221.Sh SEE ALSO 222.Xr ssh 1 , 223.Xr ssh-add 1 , 224.Xr ssh-keygen 1 , 225.Xr ssh_config 5 , 226.Xr sshd 8 227.Sh AUTHORS 228.An -nosplit 229OpenSSH is a derivative of the original and free ssh 1.2.12 release by 230.An Tatu Ylonen . 231.An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt 232and 233.An Dug Song 234removed many bugs, re-added newer features and created OpenSSH. 235.An Markus Friedl 236contributed the support for SSH protocol versions 1.5 and 2.0. 237