1.\" $OpenBSD: ssh-agent.1,v 1.87 2026/05/27 03:04:30 djm Exp $ 2.\" 3.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 5.\" All rights reserved 6.\" 7.\" As far as I am concerned, the code I have written for this software 8.\" can be used freely for any purpose. Any derived versions of this 9.\" software must be clearly marked as such, and if the derived work is 10.\" incompatible with the protocol description in the RFC file, it must be 11.\" called by a name other than "ssh" or "Secure Shell". 12.\" 13.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 14.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 15.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 16.\" 17.\" Redistribution and use in source and binary forms, with or without 18.\" modification, are permitted provided that the following conditions 19.\" are met: 20.\" 1. Redistributions of source code must retain the above copyright 21.\" notice, this list of conditions and the following disclaimer. 22.\" 2. Redistributions in binary form must reproduce the above copyright 23.\" notice, this list of conditions and the following disclaimer in the 24.\" documentation and/or other materials provided with the distribution. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 27.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 28.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 29.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 30.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 31.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 32.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 33.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 34.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 35.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd $Mdocdate: May 27 2026 $ 38.Dt SSH-AGENT 1 39.Os 40.Sh NAME 41.Nm ssh-agent 42.Nd OpenSSH authentication agent 43.Sh SYNOPSIS 44.Nm ssh-agent 45.Op Fl c | s 46.Op Fl \&DdTUx 47.Op Fl a Ar bind_address 48.Op Fl E Ar fingerprint_hash 49.Op Fl O Ar option 50.Op Fl P Ar allowed_providers 51.Op Fl t Ar life 52.Nm ssh-agent 53.Op Fl TU 54.Op Fl a Ar bind_address 55.Op Fl E Ar fingerprint_hash 56.Op Fl O Ar option 57.Op Fl P Ar allowed_providers 58.Op Fl t Ar life 59.Ar command Op Ar arg ... 60.Nm ssh-agent 61.Op Fl c | s 62.Fl k 63.Nm ssh-agent 64.Fl u 65.Nm ssh-agent 66.Fl V 67.Sh DESCRIPTION 68.Nm 69is a program to hold private keys used for public key authentication. 70Through use of environment variables the agent can be located 71and automatically used for authentication when logging in to other 72machines using 73.Xr ssh 1 . 74.Pp 75The options are as follows: 76.Bl -tag -width Ds 77.It Fl a Ar bind_address 78Bind the agent to the 79.Ux Ns -domain 80socket 81.Ar bind_address . 82The default is to create a socket at a random path matching 83.Pa $HOME/.ssh/agent/s.* . 84.It Fl c 85Generate C-shell commands on standard output. 86This is the default if 87.Ev SHELL 88looks like it's a csh style of shell. 89.It Fl D 90Foreground mode. 91When this option is specified, 92.Nm 93will not fork. 94.It Fl d 95Debug mode. 96When this option is specified, 97.Nm 98will not fork and will write debug information to standard error. 99.It Fl E Ar fingerprint_hash 100Specifies the hash algorithm used when displaying key fingerprints. 101Valid options are: 102.Dq md5 103and 104.Dq sha256 . 105The default is 106.Dq sha256 . 107.It Fl k 108Kill the current agent (given by the 109.Ev SSH_AGENT_PID 110environment variable). 111.It Fl O Ar option 112Specify an option when starting 113.Nm . 114The supported options are: 115.Cm allow-remote-pkcs11 , 116.Cm no-restrict-websafe 117and 118.Cm websafe-allow . 119.Pp 120The 121.Cm allow-remote-pkcs11 122option allows clients of a forwarded 123.Nm 124to load PKCS#11 or FIDO provider libraries. 125By default only local clients may perform this operation. 126Note that signalling that an 127.Nm 128client is remote is performed by 129.Xr ssh 1 , 130and use of other tools to forward access to the agent socket may circumvent 131this restriction. 132.Pp 133The 134.Cm no-restrict-websafe 135option instructs 136.Nm 137to permit signatures using FIDO keys that might be web authentication 138requests. 139By default, 140.Nm 141refuses signature requests for FIDO keys where the key application string 142does not start with 143.Dq ssh: 144and when the data to be signed does not appear to be an 145.Xr ssh 1 146user authentication request or an 147.Xr ssh-keygen 1 148signature. 149The default behaviour prevents forwarded access to a FIDO key from also 150implicitly forwarding the ability to authenticate to websites. 151.Pp 152Alternately the 153.Cm websafe-allow 154option allows specifying a pattern-list of key application strings to 155replace the default application allow-list, for example: 156.Dq websafe-allow=ssh:*,example.org,*.example.com 157.Pp 158See PATTERNS in 159.Xr ssh_config 5 160for a description of pattern-list syntax. 161.It Fl P Ar allowed_providers 162Specify a pattern-list of acceptable paths for PKCS#11 provider and FIDO 163authenticator middleware shared libraries that may be used with the 164.Fl S 165or 166.Fl s 167options to 168.Xr ssh-add 1 . 169Libraries that do not match the pattern list will be refused. 170The default list is 171.Dq /usr/lib*/*,/usr/local/lib*/* . 172.Pp 173See PATTERNS in 174.Xr ssh_config 5 175for a description of pattern-list syntax. 176.It Fl s 177Generate Bourne shell commands on standard output. 178This is the default if 179.Ev SHELL 180does not look like it's a csh style of shell. 181.It Fl T 182Bind the agent socket in a randomised subdirectory of the form 183.Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt , 184instead of the default behaviour of using a randomised name matching 185.Pa $HOME/.ssh/agent/s.* . 186.It Fl t Ar life 187Set a default value for the maximum lifetime of identities added to the agent. 188The lifetime may be specified in seconds or in a time format specified in 189.Xr sshd_config 5 . 190A lifetime specified for an identity with 191.Xr ssh-add 1 192overrides this value. 193Without this option the default maximum lifetime is forever. 194.It Fl U 195Instructs 196.Nm 197not to clean up stale agent sockets under 198.Pa $HOME/.ssh/agent/ . 199.It Fl u 200Instructs 201.Nm 202to only clean up stale agent sockets under 203.Pa $HOME/.ssh/agent/ 204and then exit immediately. 205If this option is given twice, 206.Nm 207will delete stale agent sockets regardless of the host name that created them. 208.It Fl x 209Exit after the last client has disconnected. 210.It Ar command Op Ar arg ... 211If a command (and optional arguments) is given, 212this is executed as a subprocess of the agent. 213The agent exits automatically when the command given on the command 214line terminates. 215.It Fl V 216Display the version number and exit. 217.El 218.Pp 219There are three main ways to get an agent set up. 220The first is at the start of an X session, 221where all other windows or programs are started as children of the 222.Nm 223program. 224The agent starts a command under which its environment 225variables are exported, for example 226.Cm ssh-agent xterm & . 227When the command terminates, so does the agent. 228.Pp 229The second method is used for a login session. 230When 231.Nm 232is started, 233it prints the shell commands required to set its environment variables, 234which in turn can be evaluated in the calling shell, for example 235.Cm eval `ssh-agent -s` . 236.Pp 237In both of these cases, 238.Xr ssh 1 239looks at these environment variables 240and uses them to establish a connection to the agent. 241.Pp 242The third way to run 243.Nm 244is via socket activation from a supervising process, such as systemd. 245In this mode, the supervising process creates the listening socket and 246is responsible for starting 247.Nm 248as needed, and also for communicating the location of the socket listener 249to other programs in the user's session. 250Socket activation is used when 251.Nm 252is started with either of the 253.Fl d 254or 255.Fl D 256flags, no socket listening address specified by the 257.Fl a 258flag, and both the 259.Ev LISTEN_FDS 260and 261.Ev LISTEN_PID 262environment variables correctly supplied by the supervising process. 263.Pp 264The agent initially does not have any private keys. 265Keys are added using 266.Xr ssh-add 1 267or by 268.Xr ssh 1 269when 270.Cm AddKeysToAgent 271is set in 272.Xr ssh_config 5 . 273Multiple identities may be stored in 274.Nm 275concurrently and 276.Xr ssh 1 277will automatically use them if present. 278.Xr ssh-add 1 279is also used to remove keys from 280.Nm 281and to query the keys that are held in one. 282.Pp 283Connections to 284.Nm 285may be forwarded from further remote hosts using the 286.Fl A 287option to 288.Xr ssh 1 289(but see the caveats documented therein), 290avoiding the need for authentication data to be stored on other machines. 291Authentication passphrases and private keys never go over the network: 292the connection to the agent is forwarded over SSH remote connections 293and the result is returned to the requester, 294allowing the user access to their identities anywhere in the network 295in a secure fashion. 296.Pp 297.Nm 298will delete all keys it has loaded upon receiving 299.Dv SIGUSR1 . 300.Sh ENVIRONMENT 301.Bl -tag -width "SSH_AGENT_PID" 302.It Ev SSH_AGENT_PID 303When 304.Nm 305starts, it stores the name of the agent's process ID (PID) in this variable. 306.It Ev SSH_AUTH_SOCK 307When 308.Nm 309starts, it creates a 310.Ux Ns -domain 311socket and stores its pathname in this variable. 312It is accessible only to the current user, 313but is easily abused by root or another instance of the same user. 314.El 315.Sh FILES 316.Bl -tag -width Ds 317.It Pa $HOME/.ssh/agent/s.* 318.Ux Ns -domain 319sockets used to contain the connection to the authentication agent. 320These sockets should only be readable by the owner. 321The sockets should get automatically removed when the agent exits. 322.El 323.Sh SEE ALSO 324.Xr ssh 1 , 325.Xr ssh-add 1 , 326.Xr ssh-keygen 1 , 327.Xr ssh_config 5 , 328.Xr sshd 8 329.Sh AUTHORS 330.An -nosplit 331OpenSSH is a derivative of the original and free ssh 1.2.12 release by 332.An Tatu Ylonen . 333.An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt 334and 335.An Dug Song 336removed many bugs, re-added newer features and created OpenSSH. 337.An Markus Friedl 338contributed the support for SSH protocol versions 1.5 and 2.0. 339