keychain.1

.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
.br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
.br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "keychain 1"
.TH keychain 1 "2018-01-24" "2.8.5" "http://www.funtoo.org"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
keychain \- re\-use ssh\-agent and/or gpg\-agent between logins
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
keychain\ [\ \-hklQqV\ ]\ [\ \-\-clear\ \-\-confhost\ \-\-gpg2\ \-\-help\ \-\-ignore\-missing\ \-\-list
\&\-\-noask\ \-\-nocolor\ \-\-nogui\ \-\-nolock\ \-\-quick\ \-\-quiet\ \-\-version\ ]
[\ \-\-agents\ \fIlist\fR\ ]\ [\ \-\-attempts\ \fInum\fR\ ]\ [\ \-\-dir\ \fIdirname\fR\ ]
[\ \-\-host\ \fIname\fR\ ]\ [\ \-\-lockwait\ \fIseconds\fR\ ]
[\ \-\-stop\ \fIwhich\fR\ ]\ [\ \-\-timeout\ \fIminutes\fR\ ]\ [\ keys...\ ]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
keychain is a manager for ssh-agent, typically run from ~/.bash_profile.  It
allows your shells and cron jobs to easily share a single ssh-agent process.  By
default, the ssh-agent started by keychain is long-running and will continue to
run, even after you have logged out from the system.  If you want to change
this behavior, take a look at the \-\-clear and \-\-timeout options, described
below.
.PP
When keychain is run, it checks for a running ssh-agent, otherwise it starts
one.  It saves the ssh-agent environment variables to
~/.keychain/${\s-1HOSTNAME\s0}\-sh, so that subsequent logins and non-interactive
shells such as cron jobs can source the file and make passwordless ssh
connections.
.PP
In addition, when keychain runs, it verifies that the key files specified on
the command-line are known to ssh-agent, otherwise it loads them, prompting you
for a password if necessary. Typically, private 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. If just a private key filename is used,
which is typical usage, keychain will look for the specified private key
files in ~/.ssh, ~/.ssh2, or with the \-c/\-\-confhost option, inspect the
~/.ssh/config file and use the IdentityFile option to determine the location of
the private key. Private keys can be symlinks to the actual private key.
.PP
Keychain expects associated public key files to exist in the same directory as
the private key files, with a .pub extension.  If the private key is a symlink,
the public key can be found alongside the symlink, or in the same directory as
the symlink target (This capability requires the 'readlink' command to be
available on the system.)
.PP
As an additional feature, if a private key has an extension \*(L".ext\*(R", keychain
will look for privkey.ext.pub first, and if not found, will look for
privkeyname.pub.
.PP
Keychain also supports gpg-agent in the same ways that ssh-agent is
supported.  By default keychain attempts to start ssh-agent only. 
You can modify this behavior using the \-\-agents
option.
.PP
Keychain supports most UNIX-like operating systems, including Cygwin.
It works with Bourne-compatible, csh-compatible and fish shells.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-\-agents\fR \fIlist\fR" 4
.IX Item "--agents list"
Start the agents listed.  By default keychain will start ssh-agent
if it is found in your path. The list should be comma-separated, 
for example \*(L"gpg,ssh\*(R"
.IP "\fB\-\-attempts\fR \fInum\fR" 4
.IX Item "--attempts num"
Try num times to add keys before giving up.  The default is 1.
.IP "\fB\-\-clear\fR" 4
.IX Item "--clear"
Delete all of ssh-agent's keys.  Typically this is used in
\&.bash_profile.  The theory behind this is that keychain should assume
that you are an intruder until proven otherwise.  However, while this
option increases security, it still allows your cron jobs to use your
ssh keys when you're logged out.
.IP "\fB\-\-confhost\fR" 4
.IX Item "--confhost"
By default, keychain will look for key pairs in the ~/.ssh/ directory.
The \-\-confhost option will inform keychain to look in ~/.ssh/config
for IdentityFile settings defined for particular hosts, and use these
paths to locate keys.
.IP "\fB\-\-confirm\fR" 4
.IX Item "--confirm"
Keys are subject to interactive confirmation by the \s-1SSH_ASKPASS\s0
program before being used for authentication.  See the \-c option for
\&\fIssh\-add\fR\|(1).
.IP "\fB\-\-absolute\fR" 4
.IX Item "--absolute"
Any arguments to \*(L"\-\-dir\*(R" are interpreted to be absolute. The default
behavior is to append \*(L"/.keychain\*(R" to the argument for backwards
compatibility.
.IP "\fB\-\-dir\fR \fIdirname\fR" 4
.IX Item "--dir dirname"
Keychain will use dirname rather than \f(CW$HOME\fR/.keychain
.IP "\fB\-\-query\fR" 4
.IX Item "--query"
Keychain will print lines in KEY=value format representing the values
which are set by the agents.
.IP "\fB\-\-eval\fR" 4
.IX Item "--eval"
Keychain will print lines to be evaluated in the shell on stdout.  It
respects the \s-1SHELL\s0 environment variable to determine if Bourne shell
or C shell output is expected.
.IP "\fB\-\-env\fR \fIfilename\fR" 4
.IX Item "--env filename"
After parsing options, keychain will load additional environment
settings from \*(L"filename\*(R".  By default, if \*(L"\-\-env\*(R" is not given, then
keychain will attempt to load from ~/.keychain/[hostname]\-env or
alternatively ~/.keychain/env.  The purpose of this file is to
override settings such as \s-1PATH,\s0 in case ssh is stored in
a non-standard place.
.IP "\fB\-\-gpg2\fR" 4
.IX Item "--gpg2"
This option changes the default gpg calls to use gpg2 instead to support
distributions such as Ubuntu which has both gpg and gpg2
.IP "\fB\-h \-\-help\fR" 4
.IX Item "-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.
.IP "\fB\-\-host\fR \fIname\fR" 4
.IX Item "--host name"
Set alternate hostname for creation of pidfiles
.IP "\fB\-\-ignore\-missing\fR" 4
.IX Item "--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.
.IP "\fB\-\-inherit\fR \fIwhich\fR" 4
.IX Item "--inherit which"
Attempt to inherit agent variables from the environment.  This can be
useful in a variety of circumstances, for example when ssh-agent is
started by gdm.  The following values are valid for \*(L"which\*(R":
.RS 4
.IP "\fBlocal\fR" 12
.IX Item "local"
Inherit when a pid (e.g. \s-1SSH_AGENT_PID\s0) is set in the environment.
This disallows inheriting a forwarded agent.
.IP "\fBany\fR" 12
.IX Item "any"
Inherit when a sock (e.g. \s-1SSH_AUTH_SOCK\s0) is set in the environment.
This allows inheriting a forwarded agent.
.IP "\fBlocal-once\fR" 12
.IX Item "local-once"
Same as \*(L"local\*(R", but only inherit if keychain isn't already providing
an agent.
.IP "\fBany-once\fR" 12
.IX Item "any-once"
Same as \*(L"any\*(R", but only inherit if keychain isn't already providing an
agent.
.RE
.RS 4
.Sp
By default, keychain\-2.5.0 and later will behave as if \*(L"\-\-inherit
local-once\*(R" is specified.  You should specify \*(L"\-\-noinherit\*(R" if you
want the older behavior.
.RE
.IP "\fB\-l \-\-list\fR" 4
.IX Item "-l --list"
List signatures of all active \s-1SSH\s0 keys, and exit, similar to \*(L"ssh-add \-l\*(R".
.IP "\fB\-L \-\-list\-fp\fR" 4
.IX Item "-L --list-fp"
List fingerprints of all active \s-1SSH\s0 keys, and exit, similar to \*(L"ssh-add \-L\*(R".
.IP "\fB\-\-lockwait\fR \fIseconds\fR" 4
.IX Item "--lockwait 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.
.IP "\fB\-\-noask\fR" 4
.IX Item "--noask"
This option tells keychain do everything it normally does (ensure
ssh-agent is running, set up the ~/.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.
.IP "\fB\-\-nocolor\fR" 4
.IX Item "--nocolor"
Disable color highlighting for non ANSI-compatible terms.
.IP "\fB\-\-nogui\fR" 4
.IX Item "--nogui"
Don't honor \s-1SSH_ASKPASS,\s0 if it is set.  This will cause ssh-add to
prompt on the terminal instead of using a graphical program.
.IP "\fB\-\-noinherit\fR" 4
.IX Item "--noinherit"
Don't inherit any agent processes, overriding the default 
\&\*(L"\-\-inherit local-once\*(R"
.IP "\fB\-\-nolock\fR" 4
.IX Item "--nolock"
Don't attempt to use a lockfile while manipulating files, pids and
keys.
.IP "\fB\-k \-\-stop\fR \fIwhich\fR" 4
.IX Item "-k --stop which"
Kill currently running agent processes.  The following values are
valid for \*(L"which\*(R":
.RS 4
.IP "all" 9
.IX Item "all"
Kill all agent processes and quit keychain immediately.  Prior to
keychain\-2.5.0, this was the behavior of the bare \*(L"\-\-stop\*(R" option.
.IP "others" 9
.IX Item "others"
Kill agent processes other than the one 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.
.IP "mine" 9
.IX Item "mine"
Kill keychain's agent processes, leaving other agents alone.
.RE
.RS 4
.RE
.IP "\fB\-\-systemd\fR" 4
.IX Item "--systemd"
Inject environment variables into the systemd \-\-user session.
.IP "\fB\-Q \-\-quick\fR" 4
.IX Item "-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.
.IP "\fB\-q \-\-quiet\fR" 4
.IX Item "-q --quiet"
Only print messages in case of warning, error or required interactivity. As of
version 2.6.10, this also suppresses \*(L"Identities added\*(R" messages for ssh-agent.
.IP "\fB\-\-timeout\fR \fIminutes\fR" 4
.IX Item "--timeout 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.
.Sp
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.
.IP "\fB\-V \-\-version\fR" 4
.IX Item "-V --version"
Show version information.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
This snippet should work in most shells to load two ssh keys and one gpg
key:
.PP
.Vb 1
\&    eval \`keychain \-\-eval id_rsa id_dsa 0123ABCD\`
.Ve
.PP
For the fish shell, use the following format:
.PP
.Vb 3
\&    if status \-\-is\-interactive
\&        keychain \-\-eval \-\-quiet \-Q id_rsa | source
\&    end
.Ve
.PP
If you have trouble with that in csh:
.PP
.Vb 2
\&    setenv SHELL /bin/csh
\&    eval \`keychain \-\-eval id_rsa id_dsa 0123ABCD\`
.Ve
.PP
This is equivalent for Bourne shells (including bash and zsh) but
doesn't use keychain's \-\-eval feature:
.PP
.Vb 6
\&    keychain id_rsa id_dsa 0123ABCD
\&    [ \-z "$HOSTNAME" ] && HOSTNAME=\`uname \-n\`
\&    [ \-f $HOME/.keychain/$HOSTNAME\-sh ] && \e
\&            . $HOME/.keychain/$HOSTNAME\-sh
\&    [ \-f $HOME/.keychain/$HOSTNAME\-sh\-gpg ] && \e
\&            . $HOME/.keychain/$HOSTNAME\-sh\-gpg
.Ve
.PP
This is equivalent for C shell (including tcsh):
.PP
.Vb 8
\&    keychain id_rsa id_dsa 0123ABCD
\&    host=\`uname \-n\`
\&    if (\-f $HOME/.keychain/$host\-csh) then
\&            source $HOME/.keychain/$host\-csh
\&    endif
\&    if (\-f $HOME/.keychain/$host\-csh\-gpg) then
\&            source $HOME/.keychain/$host\-csh\-gpg
\&    endif
.Ve
.PP
To load keychain variables from a script (for example from cron) and
abort unless id_dsa is available:
.PP
.Vb 4
\&    # 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
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIssh\-agent\fR\|(1)
.SH "NOTES"
.IX Header "NOTES"
Keychain was created and is currently maintained by Daniel Robbins. If you need
to report a bug or request an enhancement, please post to the Funtoo Linux
bug tracker <http://bugs.funtoo.org>.  For more information
about keychain, please visit <http://www.funtoo.org/Keychain>.