=head1 NAME

keychain - Manager for ssh-agent, gpg-agent and private keys. Compatible with POSIX systems.

=head1 SYNOPSIS

S<keychain [ -hklQqV ] [ --clear --confhost --confallhosts --debug>
S<--extended --gpg2 --help --ignore-missing --list --noask --nocolor --nogui>
S<--noinherit --nolock --quick --quiet --ssh-allow-forwarded --ssh-allow-gpg>
S<--ssh-rm --ssh-spawn-gpg --systemd --version ] [ --ssh-agent-socket I<path> ]>
S<[ --dir I<dirname> ] [ --host I<name> ] [ --lockwait I<seconds> ]>
S<[ --stop I<which> ] [ --timeout I<minutes> ] [ --wipe I<which> ] [ keys... ]>

=head1 INTRODUCTION

B<Keychain> helps you to manage SSH and GPG keys in a convenient and secure
manner. It acts as a frontend to C<ssh-agent> and C<ssh-add>, but allows you
to easily have one long-running C<ssh-agent> process per system, rather than
the norm of one C<ssh-agent> per login session.

This dramatically reduces the number of times you need to enter your
passphrase. With C<keychain>, you only need to enter a passphrase once every
time your local machine is rebooted. Keychain also makes it easy for remote
cron jobs to securely "hook in" to a long running C<ssh-agent> process,
allowing your scripts to take advantage of key-based logins.

Keychain also supports GnuPG 2.1 and later, and will automatically start
gpg-agent if any GPG keys are referenced on the command-line, and will ensure
these credentials are cached in memory and available for use.

Official project home: L<https://github.com/danielrobbins/keychain>.

=head1 COMPATIBILITY

Keychain supports most UNIX-like operating systems and intentionally limits
its scope to modern, widely deployed implementations of OpenSSH and GnuPG.

=over 4

=item * Minimum OpenSSH version: 7.3

OpenSSH 7.3 (released 2016-08-01) introduced the C<-G> (config dump) option
used by Keychain to expand C<host:> extended keys and the C<--confallhosts>
feature. Because this option is central to modern key discovery, Keychain
officially targets OpenSSH 7.3 or newer. Earlier versions (>=6.5) may appear
to work for basic usage (loading explicitly named keys) but are not part of
the supported test matrix.

Key types supported under the 7.3+ baseline include RSA, ECDSA and Ed25519
(Ed25519 first appeared in OpenSSH 6.5). DSA keys have been disabled by
default upstream since OpenSSH 7.0; Keychain will still list or load them
if they are explicitly enabled and present, but they are considered legacy.

Features leveraged from OpenSSH:

    ssh -V            (implementation detection)
    ssh -nG host      (configuration expansion for host: extended keys)
    ssh-agent -s      (Bourne-compatible environment output; always forced)
    ssh-agent -t      (default key lifetime when spawning)
    ssh-agent -a path (explicit socket path when requested)
    ssh-add -l/-L     (list fingerprints / public keys)
    ssh-add -d/-D     (remove one / remove all keys)
    ssh-add -c        (confirmation mode)
    ssh-add -t        (per-key lifetime override)
    ssh-keygen -l -f  (fingerprint extraction, handles SHA256 & legacy MD5)
    Forwarded agent sockets (optionally adopted with --ssh-allow-forwarded)

=item * GnuPG / gpg-agent

GnuPG 2.1 or later is required for gpg-agent integration. Keychain uses
C<gpg-connect-agent> C<GETINFO socket_name> and C<GETINFO ssh_socket_name>
to detect, adopt or (optionally) spawn gpg-agent when acting as an
SSH agent via C<--ssh-allow-gpg> or C<--ssh-spawn-gpg>. Earlier GnuPG
versions (2.0.x) lacked reliable SSH key storage support and are not
supported.

=item * Shells

The Keychain script itself requires a POSIX / Bourne-compatible shell.
It generates pidfiles for Bourne (C<...-sh>), csh/tcsh (C<...-csh>) and
fish (C<...-fish>) shells. Internally Keychain now always consumes the
canonical Bourne output of ssh-agent (forced with C<-s>) and derives
the other shell formats. Bash, ksh and zsh consume the Bourne pidfiles.

Keychain is officially supported on Git Bash (MSYS2) for Windows, including
proper handling of Windows-style paths and usernames containing spaces.

The csh/tcsh and fish pidfiles remain supported for backward compatibility.
They are candidates for deprecation: a warning about planned removal will
be announced at least two minor releases before any change.

=item * Spaces in HOME and paths

Keychain 2.9.7+ properly handles home directories and private key paths
containing spaces. All path variables in pidfiles (SSH_AUTH_SOCK) are quoted
to ensure correct parsing by shells. The implementation uses a robust approach
that evaluates ssh-agent output in a subshell to extract environment variables
directly, rather than fragile string parsing. This ensures compatibility even
if ssh-agent output format changes. File ownership detection uses POSIX-defined
ls output format with logic to correctly parse usernames containing spaces.

=item * Legacy / Other SSH implementations

SunSSH (found on older Oracle Solaris releases) may still function; code
paths for SunSSH detection are retained but are not actively tested. They
are scheduled for review and possible removal after three future minor
releases unless community feedback requests retention.

The historical commercial ssh.com implementation and its agent are no longer
targets. If detected, behavior may fall back to simpler key loading; advanced
features (confirmation, modern fingerprint parsing, host expansion) are not
guaranteed. Reporting such usage via GitHub Issues will help shape any
future support decisions.

=item * Systemd user environment

On systems with systemd --user, Keychain can inject C<SSH_AUTH_SOCK> (and
optionally C<SSH_AGENT_PID>) via C<--systemd> for wider session availability.

=back

Summary: A supported environment is OpenSSH >= 7.3 plus (optionally) GnuPG
>= 2.1, running under any modern UNIX-like OS with a POSIX shell. Earlier
versions or unlisted SSH implementations may work for basic scenarios but
are outside official scope.

=head1 LIFECYCLE

Typically, you configure keychain to run when you first log in to a system.
If you are using Bourne shell or bash, you will create a F<~/.profile> or
F<~/.bash_profile> file and include the following line in it:

    eval "$(keychain --eval id_rsa)"

Keychain will start ssh-agent if one isn't already running. Keychain then
checks to make sure your private keys (in this example, "id_rsa") are loaded
into the agent. If they are not, you are prompted for any passphrase necessary
to decrypt them, so that they are cached in memory and available for use.

In addition to printing some user-friendly output to your terminal, keychain
will also output important ssh-agent environment variables, which the S<"$( )">
(you can also use S<"` `">) captures, and the "eval" evaluates, setting these
variables in your current shell.

These ssh-agent environment variables are also written to
F<~/.keychain/${HOSTNAME}-sh>, so that subsequent logins and non-interactive
shells such as cron jobs can source the file to access the running ssh-agent
and make passwordless ssh connections using the cached private keys --
even when you are logged out. These files are collectively called B<pidfiles>.

The key files specified on the command-line will be searched for in the
F<~/.ssh/> directory, and keychain will expect to find the private key file
with the same name, as well as a C<.pub> public key. Keychain will also
see if any GPG keys are specified, and if so, prompt for any passphrases
to cache these keys into C<gpg-agent>.

Typically, private SSH key files are specified by filename only, without path,
although it is possible to specify an absolute or relative
path to the private key file as well. Private key files can be symlinks
to the actual key as long as your system has the C<readlink> command available.
More advanced features are available for specifying keys as well -- see the
B<--extended> and B<--confallhosts> options for more information.

In addition, for GPG keys specified, similar steps will be taken to ensure
that gpg-agent has the GPG key cached in memory and ready for use.

=head1 STREAMLINING AND SIMPLIFICATION

Keychain 2.9.0 has been streamlined, and with this maintenance several
command-line options have been retired as they are not completely necessary.
This simplifies the use of the tool by making it more intuitive to use.
The files created in F<~/.keychain> have also been cleaned up. This section
details all the important changes.

=head2 PIDFILE CHANGES

"Pidfile" is the nickname for files created in F<~/.keychain> which can then
be sourced by your scripts to access a running agent.

When using gpg-agent for GPG keys, keychain will no longer create a
F<~/.keychain/${HOSTNAME}-sh-gpg> pidfile. This file is no longer needed
as the canonical GPG socket inside F<~/.gnupg/> will be used to detect the
running gpg-agent, which is the modern convention. GnuPG 2.1 and later
have stopped using environment variables to find the agent, so we follow
this upstream change.

=head2 IMPROVED DEBUGGING

A new B<--debug> option is now available which will print additional information
related to keychain's decisions regarding why and how an agent was found -- or
not.

=head2 NEW (AND DEPRECATED) OPTIONS

This section provides an overview of new and deprecated command-line options.
For full details on each option, see the respective option definition under
L</OPTIONS>.

=head3 Keychain 2.9.2

The C<--confhost> option has been deprecated. Instead of C<--confhost hostname>,
use C<--extended host:hostname>. This extended format allows multiple keys of
multiple types (SSH, GPG and SSH-from-hostname) to be specified on the
command-line together. This is also fully compatible with C<--confallhosts>,
and keychain now de-duplicates the list of keys to be loaded.

=head3 Keychain 2.9.1

The short-lived C<--ssh-wipe> and C<--gpg-wipe> options that appeared only in
version 2.9.0 were replaced with C<--wipe I<which>> to work similarly to
the C<--stop> option, and allows you to specify "ssh", "gpg" or "all".

=head3 Keychain 2.9.0

The C<--agents> option is now deprecated. Keychain will always ensure an
ssh-agent or equivalent is running, or if C<--ssh-spawn-gpg> is used,
potentially a gpg-agent for the purpose of storing SSH keys if no running
ssh-agent is available. To simply use a gpg-agent if one is already running,
falling back to launching ssh-agent if no agent is available, use the
C<--ssh-allow-gpg> option.

Specifying a GPG key on the command-line will instruct keychain to
enable gpg-agent functionality automatically. This eliminates an option
that you need to specify (C<--agents ssh,gpg>) when invoking keychain,
and for many will avoid spawning a GPG agent you may not be using.

Specifying the C<--agents> option will now display a warning that it's
deprecated, but keychain will not abort.

The C<--inherit> option, which took one of four arguments, has been
deprecated. Keychain's default behavior remains that of preferring to
use an ssh-agent or equivalent referenced by its pidfile, falling
back to finding an ssh-agent in its environment. By default, keychain
will not use a gpg-agent socket for SSH keys unless at least C<--ssh-allow-gpg>
is specified. Similarly, the use of any forwarded SSH agent connection
is disabled by default and can be enabled via C<--ssh-allow-forwarded>.
Again, see the full documentation for each option in the L</OPTIONS>
section.

You can still influence keychain's behavior via the still-present
C<--noinherit> option which will prevent all detection of existing
SSH agents via the environment.

The C<--clear> option is still available, but isn't intended to be a
"standalone" option, meaning that it is used to perform an initial clearing
of cached keys before loading any specified keys when Keychain is run.
To perform the sole action of wiping all cached keys, use the C<--wipe>
action. To remove an individual cached SSH private
key or keys, use the C<--ssh-rm> I<keyfile> option.

The C<--stop> option will now only stop any running ssh-agent processes,
and still supports three possible options: "mine", "others" and "all".
It no longer stops gpg-agent processes, which tend to get auto-respawned
by GPG tools, so killing gpg-agent typically doesn't make a lot of sense.

=head2 BETTER GNUPG INTEGRATION

Keychain can now use an existing gpg-agent that has been started in your
environment to store ssh keys, rather than spawning its own ssh-agent, by
using the C<--ssh-allow-gpg> option.

If you would like keychain to spawn gpg-agent instead of ssh-agent, and
use it to store SSH keys, specify the "--ssh-spawn-gpg" option.

Without either option, keychain will not use an SSH_AUTH_SOCK that is
provided by gpg-agent, and will spawn an official ssh-agent process.

In addition, behind the scenes, keychain now uses the gpg-connect-agent
executable to restart the agent, get official PID and socket information, etc.

Please note that while gpg-agent provides full compatibility with ssh-agent,
its password prompt is handled by pinentry and its store may encrypt your
in-memory keys. For this reason, consider
this new feature experimental, and use GitHub issues to report back any
anomalies or suggested improvements for gpg-agent integration.

=head2 DISPLAY CHANGES

When keychain uses gpg-agent for either GnuPG or SSH support, then keychain will display
the GnuPG socket file in its output, rather than the PID. Since the socket
file has the F<~/.gnupg> path in it, this communicates to you that gpg-agent,
not ssh-agent, is active. If you see an integer PID, this means that ssh-agent
is being used.

=head2 STREAMLINED STARTUP

By default, keychain will always ensure that an ssh-agent should be started.
It will only start a gpg-agent if a GPG key is referenced on the command-line.

Modern versions of gpg-agent also support the caching of SSH keys, allowing it
to be a drop-in replacement for ssh-agent. With keychain 2.9.0, a new
"--ssh-spawn-gpg" option has been added, which when specified will give
keychain permission to spawn a gpg-agent in place of ssh-agent.

=head2 CODE OPTIMIZATION

With keychain 2.9.0, there has been significant code cleanup, reducing the size
of the script from 1500 lines to about 1100 lines. In addition, the script is
now fully compliant with L<ShellCheck|https://shellcheck.net>, which will be
hugely helpful to ensure continued POSIX shell compatibility moving forward.

=head1 AGENT DETECTION AND STARTUP ALGORITHM

This section documents the official algorithm used for detecting and if necessary
starting ssh-agent, to facilitate understanding as well as developer maintenance
of the codebase.

=head2 DEFINITIONS

There are several important definition related to the algorithm:

=over

=item 1. The B<agent>, "ssh-agent", which is a long-running daemon. This can also
    in some cases be "gpg-agent", depending on command-line options.

=item 2. The B<inherited agent>, which is the agent or forwarded agent that was not started by keychain,
    but is detected in the environment or by other means.

=item 3. The B<adopted agent>, which is an B<inherited agent> whose information has
    been persisted by being written to the B<pidfiles> (see below).

=item 4. The B<environment variables> C<SSH_AUTH_SOCK>, which points to the socket file
    used to communicate with ssh-agent, and optionally C<SSH_AGENT_PID>, which indicates
    its process ID if running locally (although gpg-agent does not define C<SSH_AGENT_PID>,
    even if running locally.)

=item 5. The file F<~/.keychain/${HOSTNAME}-sh> and related files, which are
    collectively referred to as "B<pidfiles>".
   Pidfiles are used to persistently store C<SSH_AUTH_SOCK> and C<SSH_AGENT_PID>
   environment variables for use by other scripts, as well as by keychain itself,
   formatted so that they can be "sourced" by shells of various types.

=item 6. Relevant B<command-line options> affecting behavior, which include B<--noinherit>,
    B<--ssh-allow-gpg>, B<--ssh-spawn-gpg>, and B<--ssh-allow-forwarded>.

=back

=head2 ALGORITHM OVERVIEW

When the keychain script is run, it will first attempt to find a running ssh-agent.

=over

=item Phase 1: pidfile: To do this, it will first look for an existing B<pidfile>. If one exists, it will
be inspected and used to find a running agent, in alignment with specified
B<command-line options>. If this process is successful, a "keychain-spawned" agent is
found and this process is complete. Otherwise, we continue to the next step.

=item Phase 2: environment: If keychain's B<pidfile> did not yield a running agent, keychain looks at
B<environment variables> defined in the current environment. This step will be skipped if the
B<--noinherit> option is specified. If an agent is found
that is in alignment with specified B<command-line options>, it is considered "B<inherited>" by keychain,
and the process is complete. Otherwise, we continue to the next step.

=item Phase 3: spawn agent: In the absence of finding a keychain-spawned or existing agent that can be
adopted, keychain will spawn a new ssh-agent, or a new gpg-agent if
B<--ssh-spawn-gpg> is specified and gpg-agent is available.

=item Final Phase: update pidfile: In addition, the B<pidfile>s will be updated to reflect the keychain-spawned or
B<"inherited"> agent. An B<"inherited"> agent, once written to the B<pidfile>, is now considered
to be B<"adopted">.

=item Pidfile update exception: If the B<--ssh-allow-forwarded> option was specified,
and a forwarded SSH socket was found -- which is identified as a valid SSH
socket defined in a C<SSH_AUTH_SOCK> variable, which has no associated or
valid C<SSH_AGENT_PID> also defined in the environment and is also determined to not
be the socket of any running gpg-agent -- then this agent will simply be used, B<but not persisted> in any
B<pidfile>. This is because this SSH-supplied
socket will disappear when the underlying SSH connection terminates, and thus
it cannot be relied on to be available persistently.

=back

=head2 THE QUICK SHORT-CIRCUIT

When the B<--quick> option is specified, a special algorithm will run prior to the
main agent-detection algorithm listed above. A pidfile, if it exists, will be
evaluated as per Phase 1 of the main algorithm. If a valid running agent
is found, it will be queried for valid keys. If at least one valid key is loaded
into the agent, the quick start is considered successful, and keychain will skip
the regular agent startup algorithm, and will use this found agent.

=head2 SUMMARY AND RATIONALE

The keychain ssh-agent detection and startup algorithm is somewhat sophisticated for
a reason. There is an intention behind its behavior.

The algorithm has been specifically designed to prefer an agent spawned by keychain,
or previously adopted, if that agent is currently available. This is by design, because
other system software could spawn ssh-agent and/or gpg-agent processes, and we want keychain to
not coerced into using these new agents which may suddenly appear in the environment
unexpectedly when new desktop sessions start and in other circumstances.  If keychain
is too "suggestible", it will lose track of the agent which currently holds valid keys,
which can result in unnecessary prompting for passphrases, and general confusion.

=head1 OPTIONS

=over

=item B<--absolute>

This option can be used with the B<--dir> option, if you would like to specify a
non-default directory to store pidfiles (defaults to F<~/.keychain>). When this
option is used, the script does not automatically append F</.keychain> to the
path, allowing you to use any arbitrary directory name for the storing of pidfiles.
Please note that Keychain 2.9.3 adds some extra security checks related to
directory and file permissions -- you must have exclusive ownership of any
directory that keychain uses to store pidfiles, or keychain will abort.

=item B<--clear>

When specified, this option adds an initial step prior to adding any keys
to the agents of wiping all existing cached keys/passphrases.
This is intended to be used alongside keychain --eval to ensure that only the specified
keys are loaded, and that keychain should assume that you are an intruder
until proven otherwise and force all interactive logins to specify valid
passphrases. This option increases security and still allows your
cron jobs to use your ssh keys when you're logged out.

=item B<--confallhosts>

In addition to any keys specified on the command-line, this option will
tell keychain to scour F<~/.ssh/config> for all private keys referenced
in all C<IdentityFile> lines, and load all keys for all hosts.

=item B<--confirm>

Keys are subject to interactive confirmation by the SSH_ASKPASS
program before being used for authentication.  See the -c option for
ssh-add(1).

=item B<--debug>

Keychain 2.9.0 introduces the B<--debug> option, which will output
additional information related to how Keychain makes its agent-selection
process. Specifically, it will output when an B<SSH_AUTH_SOCK> is rejected
because it is being supplied by gpg-agent -- and this is not allowed
due to no B<--ssh-allow-gpg> option, or when it is rejected because it
appears to be from a forwarded SSH connection, and B<--ssh-allow-forwarded>
was not supplied.

=item B<--dir> I<dirname>

This option allows you to use another directory besides F<$HOME/.keychain>
for the storing of pidfiles. Please note that Keychain 2.9.3 adds some
extra security checks related to directory and file permissions -- you
must have exclusive ownership of any directory that keychain uses to store
pidfiles, or the script will abort. Also see the B<--absolute> option.

=item B<--env> I<filename>

After parsing options, keychain will load additional environment
settings from "filename".  By default, if "--env" is not given, then
keychain will attempt to load from F<~/.keychain/[hostname]-env> or
alternatively F<~/.keychain/env>.  The purpose of this file is to
override settings such as PATH, in case ssh is stored in
a non-standard place.

=item B<--eval>

Keychain will print lines to be evaluated in the shell on stdout.  It
respects the SHELL environment variable to determine if Bourne shell
or C shell output is expected.

=item B<--extended>

This enables extended command-line key processing with more features,
and is a replacement for the old C<--confhost> option. When specified,
each key specified on the command-line must have a prefix to explicitly
categorize it. SSH keys must have a prefix of "sshk:" immediately
followed by the path or key name (the part after the "sshk:" is processed
just like a SSH key is without the C<--extended> option). GPG keys must
be in the format "gpgk:" immediately followed by the 8 or 16-character
fingerprint. If "host:<hostname>" is specified, then Keychain will
extract the SSH configuration for the specified hostname, grab all
identityfile options (private keys) specified, and these keys will be
included in the set of keys to be loaded by keychain. This allows
multiple keys of multiple types, including SSH-keys-by-host, to be
specified together, which wasn't possible with C<--confhost>.

=item B<--gpg2>

This option changes the default gpg calls to use gpg2 instead to support
distributions such as Ubuntu which has both gpg and gpg2

=item B<-h --help>

Show help that looks remarkably like this man-page. As of 2.6.10,
help is sent to stdout so it can be easily piped to a pager.

=item B<--host> I<name>

Set alternate hostname for creation of pidfiles

=item B<--ignore-missing>

Don't warn if some keys on the command-line can't be found.  This is
useful for situations where you have a shared .bash_profile, but your
keys might not be available on every machine where keychain is run.

=item B<-l --list>

List signatures of all active SSH keys, and exit, similar to "ssh-add -l".

=item B<-L --list-fp>

List fingerprints of all active SSH keys, and exit, similar to "ssh-add -L".

=item B<--lockwait> I<seconds>

How long to wait for the lock to become available.  Defaults to 5
seconds. Specify a value of zero or more. If the lock cannot be
acquired within the specified number of seconds, then this keychain
process will forcefully acquire the lock.

=item B<--noask>

This option tells keychain do everything it normally does (ensure
ssh-agent is running, set up the F<~/.keychain/[hostname]-{c}sh> files)
except that it will not prompt you to add any of the keys you
specified if they haven't yet been added to ssh-agent.

=item B<--nocolor>

Disable color highlighting for non ANSI-compatible terms.

=item B<--nogui>

Don't honor SSH_ASKPASS, if it is set.  This will cause ssh-add to
prompt on the terminal instead of using a graphical program.

=item B<--noinherit>

Don't inherit any agent processes, overriding the default behavior
of inheriting all non-forwarded ssh-agent and any existing
gpg-agent processes. Also see L<AGENT DETECTION AND STARTUP ALGORITHM>.

=item B<--nolock>

Don't attempt to use a lockfile while manipulating files, pids and
keys.

=item B<--query>

Keychain will print lines in KEY=value format representing the values
which are set by the agents.

=item B<-Q --quick>

If an ssh-agent process is running then use it.  Don't verify the list
of keys, other than making sure it's non-empty.  This option avoids
locking when possible so that multiple terminals can be opened
simultaneously without waiting on each other. See the
L</THE QUICK SHORT-CIRCUIT> section for more information regarding
how this fits into the overall startup algorithm.

=item B<-q --quiet>

Only print messages in case of warning, error or required interactivity. As of
version 2.6.10, this also suppresses "Identities added" messages for ssh-agent.

=item B<-k --stop> I<which>

Kill currently running ssh-agent processes and exit.

Note that previous versions of keychain (2.8.5 and earlier) allowed
killing of gpg-agent as well. This functionality was removed as
ssh-agent and gpg-agent have a bit different design philosophies
and you almost always only have at most one gpg-agent running at
a time. Use "killall gpg-agent" if you really want to kill gpg-agent.
However, since this option also removes pidfiles, it will remove
any gpg-agent processes adopted by keychain that were being used to
store ssh keys.

The following values are valid for "which" which controls which
ssh-agents to target:

=over 9

=item all

Kill all ssh-agent processes and quit keychain immediately.  Prior to
keychain-2.5.0, this was the behavior of the bare "--stop" option.

=item others

Kill agent processes other than the ones keychain is providing.  Prior
to keychain-2.5.0, keychain would do this automatically.  The new
behavior requires that you specify it explicitly if you want it.

=item mine

Kill keychain's agent processes, leaving other agents alone.

=back

=item B<--ssh-agent-socket> I<path>

Use this option to specify the path to the socket file that you would
like ssh-agent to create and use as its official socket. By default,
ssh-agent will create its own socket file, typically in /tmp.

=item B<--ssh-allow-forwarded>

By default, keychain will not use a forwarded ssh-agent connection,
which is a ssh-agent socket created by SSH that has no associated
local process. To permit keychain to use a forwarded ssh-agent
connection, specify this option. If a SSH-forwarded socket is used,
it will not be persisted in the pidfiles, as it is not likely to
be available outside of the currently-active SSH session.

=item B<--ssh-allow-gpg>

Would you like to have keychain use an already-running gpg-agent to
store your SSH keys, rather than spawning a new ssh-agent? This option
does just that. When this option is specified, keychain will
accept an SSH_AUTH_SOCK environment variable in its environment, even
if it was created by gpg-agent. Modern versions of gpg-agent are also
able to store SSH keys. By default, keychain has a special
check to avoid using a gpg-agent that has set the SSH_AUTH_SOCK
environment variable, and will instead spawn its own ssh-agent. With
this option enabled, this restriction is turned off.
Please note that this option does not actually instruct keychain to I<spawn> a
gpg-agent for storing SSH keys if no agent is available -- if you want that,
see the B<--ssh-spawn-gpg> option, below.

ALSO NOTE: When a gpg-agent is adopted for ssh-agent duties in this way, the
F<~/.keychain/${HOSTNAME}-sh> pidfile will be updated to reference the
gpg-agent socket, so it will be seamlessly used by future cron jobs needing
an ssh-agent, as well as by future invocations of keychain, as long as the
B<--ssh-allow-gpg> or B<--ssh-spawn-gpg> (which implies B<--ssh-allow-gpg>)
are specified.

=item B<--ssh-spawn-gpg>

This is the option to use if you're really on-board with using gpg-agent
as a replacement for ssh-agent. Not only will keychain use a running
gpg-agent if found as per the B<--ssh-allow-gpg>, but if it needs to spawn
a new ssh-agent, it will go ahead and spawn a gpg-agent in its place,
and use it instead. Also see notes for the B<--ssh-allow-gpg> option,
as this option also implies B<--ssh-allow-gpg>.

=item B<--ssh-rm -r> I<keys>

Only perform the single action of removing the specified cached keys from the
running ssh-agent, and then exit.

=item B<--systemd>

Inject environment variables into the systemd --user session.

=item B<--timeout> I<minutes>

Allows a timeout to be set for identities added to ssh-agent. When this option
is used with a keychain invocation that starts ssh-agent itself, then keychain
uses the appropriate ssh-agent option to set the default timeout for ssh-agent.
The --timeout option also gets passed to ssh-add invocations, so any keys added
to a running ssh-agent will be individually configured to have the timeout
specified, overriding any ssh-agent default.

Most users can simply use the timeout setting they desire and get the result
they want -- with all identities having the specified timeout, whether added by
keychain or not. More advanced users can use one invocation of keychain to set
the default timeout, and optionally set different timeouts for keys added by
using a subsequent invocation of keychain.

=item B<-V --version>

Show version information.

=item B<--wipe> I<which>

Only perform the single action of wiping all agent's cached keys. Specify
'ssh', 'gpg' or 'all' for SSH keys, GPG keys and all agents respectively.
Also see the C<--ssh-rm> action and the C<--clear> option.

=back

=head1 EXAMPLES

This snippet should work in most shells to load two ssh keys and one gpg
key:

    eval `keychain --eval id_rsa id_dsa 0123ABCD`

For the fish shell, use the following format:

    if status --is-interactive
        keychain --eval --quiet -Q id_rsa | source
    end

If you have trouble with that in csh:

    setenv SHELL /bin/csh
    eval `keychain --eval id_rsa id_dsa 0123ABCD`

This is equivalent for Bourne shells (including bash and zsh) but
doesn't use keychain's --eval feature:

    keychain id_rsa id_dsa 0123ABCD
    [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`
    [ -f $HOME/.keychain/$HOSTNAME-sh ] && \
	    . $HOME/.keychain/$HOSTNAME-sh

This is equivalent for C shell (including tcsh):

    keychain id_rsa id_dsa 0123ABCD
    host=`uname -n`
    if (-f $HOME/.keychain/$host-csh) then
	    source $HOME/.keychain/$host-csh
    endif

Likewise, the following commands can be used in fish:

    keychain id_rsa id_dsa 0123ABCD
    test -z "$hostname"; and set hostname (uname -n)
    if test -f "$HOME/.keychain/$hostname-fish"
        source $HOME/.keychain/$hostname-fish
    end

To load keychain variables from a script (for example from cron) and
abort unless id_dsa is available:

    # Load keychain variables and check for id_dsa
    [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`
    . $HOME/.keychain/$HOSTNAME-sh 2>/dev/null
    ssh-add -l 2>/dev/null | grep -q id_dsa || exit 1

=head1 SEE ALSO

L<ssh-agent(1)>, L<gpg-agent(1)>, L<ssh-add(1)>, L<ssh(1)>

=head1 NOTES

Keychain was created and is currently maintained by Daniel Robbins. To report a
bug or request an enhancement, use the issue tracker at
L<https://github.com/danielrobbins/keychain>.

Keychain includes bash completion support for command-line options, SSH keys,
GPG keys, and extended mode prefixes (C<sshk:>, C<gpgk:>, C<host:>). The
completion script is included in the source tarball at
C<completions/keychain.bash>. For installation instructions, see the README
file or run C<make install-completions>.

The former Funtoo Linux wiki page is preserved only as an historical reference:
L<https://www.funtoo.org/Funtoo:Keychain>.
