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