1SSH-AGENT(1) BSD General Commands Manual SSH-AGENT(1)
2
4 ssh-agent — OpenSSH authentication agent
5
7 ssh-agent [-c | -s] [-Dd] [-a bind_address] [-E fingerprint_hash]
8 [-O option] [-P allowed_providers] [-t life]
9 ssh-agent [-a bind_address] [-E fingerprint_hash] [-O option]
10 [-P allowed_providers] [-t life] command [arg ...]
11 ssh-agent [-c | -s] -k
12
14 ssh-agent is a program to hold private keys used for public key authenti‐
15 cation. Through use of environment variables the agent can be located
16 and automatically used for authentication when logging in to other ma‐
17 chines using ssh(1).
18 The options are as follows:
20 -a bind_address
22 Bind the agent to the UNIX-domain socket bind_address. The de‐
23 fault is $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>.
24 -c Generate C-shell commands on stdout. This is the default if
26 SHELL looks like it's a csh style of shell.
27 -D Foreground mode. When this option is specified, ssh-agent will
29 not fork.
30 -d Debug mode. When this option is specified, ssh-agent will not
32 fork and will write debug information to standard error.
33 -E fingerprint_hash
35 Specifies the hash algorithm used when displaying key finger‐
36 prints. Valid options are: “md5” and “sha256”. The default is
37 “sha256”.
38 -k Kill the current agent (given by the SSH_AGENT_PID environment
40 variable).
41 -O option
43 Specify an option when starting ssh-agent. Currently two options
44 are supported: allow-remote-pkcs11 and no-restrict-websafe.
45 The allow-remote-pkcs11 option allows clients of a forwarded
47 ssh-agent to load PKCS#11 or FIDO provider libraries. By default
48 only local clients may perform this operation. Note that sig‐
49 nalling that a ssh-agent client remote is performed by ssh(1),
50 and use of other tools to forward access to the agent socket may
51 circumvent this restriction.
52 The no-restrict-websafe, instructs ssh-agent to permit signatures
54 using FIDO keys that might be web authentication requests. By
55 default, ssh-agent refuses signature requests for FIDO keys where
56 the key application string does not start with “ssh:” and when
57 the data to be signed does not appear to be a ssh(1) user authen‐
58 tication request or a ssh-keygen(1) signature. The default be‐
59 haviour prevents forwarded access to a FIDO key from also implic‐
60 itly forwarding the ability to authenticate to websites.
61 -P allowed_providers
63 Specify a pattern-list of acceptable paths for PKCS#11 provider
64 and FIDO authenticator middleware shared libraries that may be
65 used with the -S or -s options to ssh-add(1). Libraries that do
66 not match the pattern list will be refused. See PATTERNS in
67 ssh_config(5) for a description of pattern-list syntax. The de‐
68 fault list is “/usr/lib/*,/usr/local/lib/*”.
69 -s Generate Bourne shell commands on stdout. This is the default if
71 SHELL does not look like it's a csh style of shell.
72 -t life
74 Set a default value for the maximum lifetime of identities added
75 to the agent. The lifetime may be specified in seconds or in a
76 time format specified in sshd_config(5). A lifetime specified
77 for an identity with ssh-add(1) overrides this value. Without
78 this option the default maximum lifetime is forever.
79 command [arg ...]
81 If a command (and optional arguments) is given, this is executed
82 as a subprocess of the agent. The agent exits automatically when
83 the command given on the command line terminates.
84 There are two main ways to get an agent set up. The first is at the
86 start of an X session, where all other windows or programs are started as
87 children of the ssh-agent program. The agent starts a command under
88 which its environment variables are exported, for example ssh-agent xterm
89 &. When the command terminates, so does the agent.
90 The second method is used for a login session. When ssh-agent is
92 started, it prints the shell commands required to set its environment
93 variables, which in turn can be evaluated in the calling shell, for exam‐
94 ple eval `ssh-agent -s`.
95 In both cases, ssh(1) looks at these environment variables and uses them
97 to establish a connection to the agent.
98 The agent initially does not have any private keys. Keys are added using
100 ssh-add(1) or by ssh(1) when AddKeysToAgent is set in ssh_config(5).
101 Multiple identities may be stored in ssh-agent concurrently and ssh(1)
102 will automatically use them if present. ssh-add(1) is also used to re‐
103 move keys from ssh-agent and to query the keys that are held in one.
104 Connections to ssh-agent may be forwarded from further remote hosts using
106 the -A option to ssh(1) (but see the caveats documented therein), avoid‐
107 ing the need for authentication data to be stored on other machines. Au‐
108 thentication passphrases and private keys never go over the network: the
109 connection to the agent is forwarded over SSH remote connections and the
110 result is returned to the requester, allowing the user access to their
111 identities anywhere in the network in a secure fashion.
112
114 SSH_AGENT_PID When ssh-agent starts, it stores the name of the agent's
115 process ID (PID) in this variable.
116 SSH_AUTH_SOCK When ssh-agent starts, it creates a UNIX-domain socket and
118 stores its pathname in this variable. It is accessible
119 only to the current user, but is easily abused by root or
120 another instance of the same user.
121
123 $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
124 UNIX-domain sockets used to contain the connection to the authen‐
125 tication agent. These sockets should only be readable by the
126 owner. The sockets should get automatically removed when the
127 agent exits.
128
130 ssh(1), ssh-add(1), ssh-keygen(1), ssh_config(5), sshd(8)
131
133 OpenSSH is a derivative of the original and free ssh 1.2.12 release by
134 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
135 de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
136 ated OpenSSH. Markus Friedl contributed the support for SSH protocol
137 versions 1.5 and 2.0.
138BSD October 7, 2022 BSD