##
##  ssh-keyman -- authentication key agent management
##  Copyright (c) 2002-2003 Ralf S. Engelschall <rse@engelschall.com>
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##
##  ssh-keyman.pod: Unix manual page (language: POD)
##

=pod

=head1 NAME

B<ssh-keyman> - authentication key agent management

=head1 SYNOPSIS

B<ssh-keyman> 
[B<-q>] 
[B<-c>] 
[B<-k>]
[B<-s>]
[B<-e>] 
[B<-d>]
[B<-a>]
[B<-l>]
[B<-i>]
[I<keyfile> ...]

B<ssh-keyman> 
B<-h>
B<-v>

=head1 DESCRIPTION

B<ssh-keyman> is a frontend to the B<ssh-agent> and B<ssh-add> commands
for managing a long-running B<ssh-agent> process. The idea is that
a single B<ssh-agent> process is kept persistently running across
multiple user login sessions in order to prevent the startup of multiple
B<ssh-agent> processes and to avoid having to enter pass-phrases more
often than really necessary from a security point of view.

The command line options can be combined and are executed internally in
the given order below.

=over 4

=item B<-q>, B<--quiet>

Quiet operation. Do not print verbose messages.

=item B<-c>, B<--cluster>

Cluster indicator. This forces the use of
B<$HOME/.ssh/agent->I<hostname> as the agent attachment informations
file instead of the default B<$HOME/.ssh/agent>. Use this if your home
directory is NFS-mounted on a cluster of desktops.

=item B<-k>, B<--kill>

Kill agent. This makes sure the B<ssh-agent> process
is no longer running.

=item B<-s>, B<--start>

Start agent. This makes sure the B<ssh-agent> process is
running. If not, it automatically spawns a new one.

=item B<-e>, B<--env>

Environment setup. This outputs to F<stdout> the Bourne-Shell commands
necessary to attach the current shell session to the B<ssh-agent>
process. The intended usage is "C<eval `B<ssh-keyman> -q -e -s`>" from
within B<$HOME/.xsession> or B<$HOME/.bash_login> scripts.

=item B<-d>, B<--delete>

Delete key. This deletes one or more (or all if not I<keyfile> arguments
are specified at all) from the B<ssh-agent> process.

=item B<-a>, B<--add>

Add key. This adds one or more keys (in I<keyfile>) to the B<ssh-agent>
process. If a key is already loaded, it is skipped and not reloaded.
Additionally, all specified keys are loaded with a single B<ssh-add>
call. This way the pass-phrase dialog is reduced to its possible
minimum.

=item B<-l>, B<--list>

List keys. This lists the currently available keys in the B<ssh-agent>
process.

=item B<-i>, B<--install>

Install public keys into remote account. This extracts the currently available public keys in the B<ssh-agent>
process and installs them into "C<~/.ssh/authorized_keys>" on a specified remote account.

=item B<-h>, B<--help>

Help information. Display a usage summary on F<stdout>.

=item B<-v>, B<--version>

Version information. Display a version summary on F<stdout>.

=back

=head1 EXAMPLE

F<.xsession>:

 eval `ssh-keyman -q -s -e`
 ssh-keyman -q -a </dev/null ~/.ssh/id_rsa ~/.ssh/id_dsa

F<.bash_login>:
 
 eval `ssh-keyman -q -s -e`

=head1 FILES

=over 4

=item B<$HOME/.ssh/agent>

The generated shell script for attaching the current shell
session (and all of its sub-processes) to the B<ssh-agent> process.
At any time this can be directly sourced from within the shell session
or indirectly through the B<ssh-keyman> B<-e> option.
This file is used if the cluster option B<-c> is not used.

=item B<$HOME/.ssh/agent->I<hostname>

The generated shell script for attaching the current shell
session (and all of its sub-processes) to the B<ssh-agent> process.
At any time this can be directly sourced from within the shell session
or indirectly through the B<ssh-keyman> B<-e> option.
This file is used if the cluster option B<-c> is used.

=back

=head1 SEE ALSO

B<ssh-agent>(1), B<ssh-add>(1).

=head1 HISTORY

B<ssh-keyman> was written in May 2002 by Ralf S. Engelschall
E<lt>rse@engelschall.comE<gt>. It was inspired by the similar program
B<keychain> from Daniel Robbins E<lt>drobbins@gentoo.orgE<gt>. The main
difference between B<keychain> and B<ssh-keyman> is that B<ssh-keyman>
uses a more orthogonal interface which even allows you to combine
multiple actions into a single call.

=cut