1SSH-AGENT(1)              BSD General Commands Manual             SSH-AGENT(1)
2

NAME

4     ssh-agent — OpenSSH authentication agent
5

SYNOPSIS

7     ssh-agent [-c | -s] [-Dd] [-a bind_address] [-E fingerprint_hash]
8               [-P allowed_providers] [-t life]
9     ssh-agent [-a bind_address] [-E fingerprint_hash] [-P allowed_providers]
10               [-t life] command [arg ...]
11     ssh-agent [-c | -s] -k
12

DESCRIPTION

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
19     The options are as follows:
20
21     -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
25     -c      Generate C-shell commands on stdout.  This is the default if
26             SHELL looks like it's a csh style of shell.
27
28     -D      Foreground mode.  When this option is specified ssh-agent will
29             not fork.
30
31     -d      Debug mode.  When this option is specified ssh-agent will not
32             fork and will write debug information to standard error.
33
34     -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
39     -k      Kill the current agent (given by the SSH_AGENT_PID environment
40             variable).
41
42     -P allowed_providers
43             Specify a pattern-list of acceptable paths for PKCS#11 provider
44             and FIDO authenticator middleware shared libraries that may be
45             used with the -S or -s options to ssh-add(1).  Libraries that do
46             not match the pattern list will be refused.  See PATTERNS in
47             ssh_config(5) for a description of pattern-list syntax.  The de‐
48             fault list is “/usr/lib/*,/usr/local/lib/*”.
49
50     -s      Generate Bourne shell commands on stdout.  This is the default if
51             SHELL does not look like it's a csh style of shell.
52
53     -t life
54             Set a default value for the maximum lifetime of identities added
55             to the agent.  The lifetime may be specified in seconds or in a
56             time format specified in sshd_config(5).  A lifetime specified
57             for an identity with ssh-add(1) overrides this value.  Without
58             this option the default maximum lifetime is forever.
59
60     command [arg ...]
61             If a command (and optional arguments) is given, this is executed
62             as a subprocess of the agent.  The agent exits automatically when
63             the command given on the command line terminates.
64
65     There are two main ways to get an agent set up.  The first is at the
66     start of an X session, where all other windows or programs are started as
67     children of the ssh-agent program.  The agent starts a command under
68     which its environment variables are exported, for example ssh-agent xterm
69     &.  When the command terminates, so does the agent.
70
71     The second method is used for a login session.  When ssh-agent is
72     started, it prints the shell commands required to set its environment
73     variables, which in turn can be evaluated in the calling shell, for exam‐
74     ple eval `ssh-agent -s`.
75
76     In both cases, ssh(1) looks at these environment variables and uses them
77     to establish a connection to the agent.
78
79     The agent initially does not have any private keys.  Keys are added using
80     ssh-add(1) or by ssh(1) when AddKeysToAgent is set in ssh_config(5).
81     Multiple identities may be stored in ssh-agent concurrently and ssh(1)
82     will automatically use them if present.  ssh-add(1) is also used to re‐
83     move keys from ssh-agent and to query the keys that are held in one.
84
85     Connections to ssh-agent may be forwarded from further remote hosts using
86     the -A option to ssh(1) (but see the caveats documented therein), avoid‐
87     ing the need for authentication data to be stored on other machines.  Au‐
88     thentication passphrases and private keys never go over the network: the
89     connection to the agent is forwarded over SSH remote connections and the
90     result is returned to the requester, allowing the user access to their
91     identities anywhere in the network in a secure fashion.
92

ENVIRONMENT

94     SSH_AGENT_PID  When ssh-agent starts, it stores the name of the agent's
95                    process ID (PID) in this variable.
96
97     SSH_AUTH_SOCK  When ssh-agent starts, it creates a UNIX-domain socket and
98                    stores its pathname in this variable.  It is accessible
99                    only to the current user, but is easily abused by root or
100                    another instance of the same user.
101

FILES

103     $TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>
104             UNIX-domain sockets used to contain the connection to the authen‐
105             tication agent.  These sockets should only be readable by the
106             owner.  The sockets should get automatically removed when the
107             agent exits.
108

SEE ALSO

110     ssh(1), ssh-add(1), ssh-keygen(1), ssh_config(5), sshd(8)
111

AUTHORS

113     OpenSSH is a derivative of the original and free ssh 1.2.12 release by
114     Tatu Ylonen.  Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
115     de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
116     ated OpenSSH.  Markus Friedl contributed the support for SSH protocol
117     versions 1.5 and 2.0.
118
119BSD                              June 22, 2020                             BSD
Impressum