Annotation of src/usr.bin/ssh/ssh-agent.1, Revision 1.68
1.68 ! jmc 1: .\" $OpenBSD: ssh-agent.1,v 1.67 2019/11/19 16:02:32 jmc Exp $
1.7 markus 2: .\"
1.16 deraadt 3: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5: .\" All rights reserved
1.1 deraadt 6: .\"
1.16 deraadt 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".
1.1 deraadt 12: .\"
1.22 deraadt 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.
1.8 deraadt 16: .\"
1.16 deraadt 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.
1.1 deraadt 25: .\"
1.16 deraadt 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.
1.1 deraadt 36: .\"
1.68 ! jmc 37: .Dd $Mdocdate: November 19 2019 $
1.2 deraadt 38: .Dt SSH-AGENT 1
39: .Os
40: .Sh NAME
41: .Nm ssh-agent
42: .Nd authentication agent
43: .Sh SYNOPSIS
1.11 aaron 44: .Nm ssh-agent
1.52 jmc 45: .Op Fl c | s
1.67 jmc 46: .Op Fl \&Dd
1.32 markus 47: .Op Fl a Ar bind_address
1.57 djm 48: .Op Fl E Ar fingerprint_hash
1.65 djm 49: .Op Fl P Ar provider_whitelist
1.36 marc 50: .Op Fl t Ar life
1.46 sobrado 51: .Op Ar command Op Ar arg ...
1.67 jmc 52: .Nm ssh-agent
53: .Op Fl c | s
54: .Fl k
1.11 aaron 55: .Sh DESCRIPTION
1.2 deraadt 56: .Nm
1.68 ! jmc 57: is a program to hold private keys used for public key authentication.
1.10 aaron 58: Through use of environment variables the agent can be located
1.14 markus 59: and automatically used for authentication when logging in to other
1.1 deraadt 60: machines using
1.2 deraadt 61: .Xr ssh 1 .
62: .Pp
1.7 markus 63: The options are as follows:
64: .Bl -tag -width Ds
1.32 markus 65: .It Fl a Ar bind_address
1.48 sobrado 66: Bind the agent to the
1.49 sobrado 67: .Ux Ns -domain
68: socket
1.32 markus 69: .Ar bind_address .
70: The default is
1.53 djm 71: .Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt .
1.7 markus 72: .It Fl c
73: Generate C-shell commands on
74: .Dv stdout .
75: This is the default if
76: .Ev SHELL
77: looks like it's a csh style of shell.
1.58 djm 78: .It Fl D
79: Foreground mode.
80: When this option is specified
81: .Nm
82: will not fork.
1.46 sobrado 83: .It Fl d
84: Debug mode.
85: When this option is specified
86: .Nm
1.58 djm 87: will not fork and will write debug information to standard error.
1.57 djm 88: .It Fl E Ar fingerprint_hash
89: Specifies the hash algorithm used when displaying key fingerprints.
90: Valid options are:
91: .Dq md5
92: and
93: .Dq sha256 .
94: The default is
95: .Dq sha256 .
1.46 sobrado 96: .It Fl k
97: Kill the current agent (given by the
98: .Ev SSH_AGENT_PID
99: environment variable).
1.65 djm 100: .It Fl P Ar provider_whitelist
101: Specify a pattern-list of acceptable paths for PKCS#11 and security key shared
102: libraries that may be used with the
1.68 ! jmc 103: .Fl S
! 104: or
1.63 djm 105: .Fl s
1.65 djm 106: options to
1.63 djm 107: .Xr ssh-add 1 .
1.65 djm 108: Libraries that do not match the whitelist will be refused.
1.63 djm 109: See PATTERNS in
110: .Xr ssh_config 5
111: for a description of pattern-list syntax.
1.68 ! jmc 112: The default whitelist is
! 113: .Dq /usr/lib/*,/usr/local/lib/* .
1.7 markus 114: .It Fl s
115: Generate Bourne shell commands on
116: .Dv stdout .
117: This is the default if
118: .Ev SHELL
119: does not look like it's a csh style of shell.
1.36 marc 120: .It Fl t Ar life
1.37 jmc 121: Set a default value for the maximum lifetime of identities added to the agent.
1.36 marc 122: The lifetime may be specified in seconds or in a time format specified in
1.43 dtucker 123: .Xr sshd_config 5 .
1.36 marc 124: A lifetime specified for an identity with
125: .Xr ssh-add 1
126: overrides this value.
127: Without this option the default maximum lifetime is forever.
1.68 ! jmc 128: .It Ar command Op Ar arg ...
! 129: If a command (and optional arguments) is given,
! 130: this is executed as a subprocess of the agent.
! 131: The agent exits automatically when the command given on the command
! 132: line terminates.
1.7 markus 133: .El
134: .Pp
1.68 ! jmc 135: There are two main ways to get an agent set up.
! 136: The first is at the start of an X session,
! 137: where all other windows or programs are started as children of the
! 138: .Nm
! 139: program.
! 140: The agent starts a command under which its environment
! 141: variables are exported, for example
! 142: .Cm ssh-agent xterm & .
! 143: When the command terminates, so does the agent.
1.7 markus 144: .Pp
1.68 ! jmc 145: The second method is used for a login session.
! 146: When
! 147: .Nm
! 148: is started,
! 149: it prints the shell commands required to set its environment variables,
! 150: which in turn can be evaluated in the calling shell, for example
! 151: .Cm eval `ssh-agent -s` .
1.40 dtucker 152: .Pp
1.68 ! jmc 153: In both cases,
1.7 markus 154: .Xr ssh 1
1.68 ! jmc 155: looks at these environment variables and uses them to establish a connection to the agent.
1.29 stevesk 156: .Pp
1.68 ! jmc 157: The agent initially does not have any private keys.
! 158: Keys are added using
! 159: .Xr ssh-add 1
! 160: or by
! 161: .Xr ssh 1
! 162: when
! 163: .Cm AddKeysToAgent
! 164: is set in
! 165: .Xr ssh_config 5 .
! 166: Multiple identities may be stored in
! 167: .Nm
! 168: concurrently and
! 169: .Xr ssh 1
! 170: will automatically use them if present.
! 171: .Xr ssh-add 1
! 172: is also used to remove keys from
! 173: .Nm
! 174: and to query the keys that are held in one.
1.7 markus 175: .Pp
1.68 ! jmc 176: Connections to
! 177: .Nm
! 178: may be forwarded from further remote hosts using the
! 179: .Fl A
! 180: option to
! 181: .Xr ssh 1
! 182: (but see the caveats documented therein),
! 183: avoiding the need for authentication data to be stored on other machines.
! 184: Authentication passphrases and private keys never go over the network:
! 185: the connection to the agent is forwarded over SSH remote connections
! 186: and the result is returned to the requester,
! 187: allowing the user access to their identities anywhere in the network
! 188: in a secure fashion.
! 189: .Sh ENVIRONMENT
! 190: .Bl -tag -width "SSH_AGENT_PID"
! 191: .It Ev SSH_AGENT_PID
! 192: When
! 193: .Nm
! 194: starts, it stores the name of the agent's process ID (PID) in this variable.
! 195: .It Ev SSH_AUTH_SOCK
! 196: When
! 197: .Nm
! 198: starts, it creates a
1.49 sobrado 199: .Ux Ns -domain
1.68 ! jmc 200: socket and stores its pathname in this variable.
! 201: It is accessible only to the current user,
! 202: but is easily abused by root or another instance of the same user.
! 203: .El
1.2 deraadt 204: .Sh FILES
205: .Bl -tag -width Ds
1.64 jmc 206: .It Pa $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
1.49 sobrado 207: .Ux Ns -domain
208: sockets used to contain the connection to the authentication agent.
1.10 aaron 209: These sockets should only be readable by the owner.
210: The sockets should get automatically removed when the agent exits.
1.13 aaron 211: .El
1.39 jmc 212: .Sh SEE ALSO
213: .Xr ssh 1 ,
214: .Xr ssh-add 1 ,
215: .Xr ssh-keygen 1 ,
1.68 ! jmc 216: .Xr ssh_config 5 ,
1.39 jmc 217: .Xr sshd 8
1.17 aaron 218: .Sh AUTHORS
1.64 jmc 219: .An -nosplit
220: OpenSSH is a derivative of the original and free ssh 1.2.12 release by
221: .An Tatu Ylonen .
222: .An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt
223: and
224: .An Dug Song
225: removed many bugs, re-added newer features and created OpenSSH.
226: .An Markus Friedl
227: contributed the support for SSH protocol versions 1.5 and 2.0.
![[BACK]](/icons/back.gif){kind=icon}
Return to ssh-agent.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh