source: trunk/third/ssh/ssh-add.1 @ 12646

.\"  -*- nroff -*-
.\"
.\" ssh-add.1
.\"
.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
.\"
.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
.\"                    All rights reserved
.\"
.\" Created: Sat Apr 22 23:55:14 1995 ylo
.\"
.\" $Id: ssh-add.1,v 1.1.1.2 1999-03-08 17:42:59 danw Exp $
.\" $Log: not supported by cvs2svn $
.\" Revision 1.5  1998/07/08 00:40:34  kivinen
.\"     Changed to do similar commercial #ifdef processing than other
.\"     files.
.\"
.\" Revision 1.4  1997/04/27  21:48:43  kivinen
.\"     Added F-SECURE stuff.
.\"
.\" Revision 1.3  1997/04/23 00:03:50  kivinen
.\"     Documented -p flag.
.\"
.\" Revision 1.2  1997/03/25 05:41:32  kivinen
.\"     Changed ylo's email to @ssh.fi.
.\"
.\" Revision 1.1.1.1  1996/02/18 21:38:13  ylo
.\"     Imported ssh-1.2.13.
.\"
.\" Revision 1.5  1995/08/31  09:22:20  ylo
.\"     Proofreading fixes.
.\"
.\" Revision 1.4  1995/08/29  22:30:37  ylo
.\"     Improved manual pages from Andrew Macpherson.
.\"
.\" Revision 1.3  1995/08/21  23:27:06  ylo
.\"     Minor additions.
.\"
.\" Revision 1.2  1995/07/13  01:36:56  ylo
.\"     Removed "Last modified" header.
.\"     Added cvs log.
.\"
.\" $Endlog$
.\"
.\"
.\"
.\"
.\" #ifndef F_SECURE_COMMERCIAL
.TH SSH-ADD 1 "November 8, 1995" "SSH" "SSH"
.\" #endif F_SECURE_COMMERCIAL

.SH NAME
ssh-add \- adds identities for the authentication agent

.SH SYNOPSIS
.B ssh-add
[\c
.B \-p\c
]
[\c
.B \-l\c
]
[\c
.B \-d\c
]
[\c
.B \-D\c
]
[\c
.B file\c
\&.\|.\|.\|]

.SH DESCRIPTION 
.LP
.B Ssh-add
adds identities to the authentication agent,
.B ssh-agent.
When run without arguments, it adds the file
.IR $HOME/\s+2.\s0ssh/identity ".
Alternative file names can be given on the
command line.  If any file requires a passphrase,
.B ssh-add
asks for the passphrase from the user.  If the -p option is given then
the passphrase is read from stdin, otherwise if the user is using X11,
the passphrase is requested using a small X11 program; otherwise it is
read from the user's tty.  (Note: it may be necessary to redirect stdin
from /dev/null to get the passphrase requested using X11.)
.LP
The authentication agent must be running and must be an ancestor of
the current process for
.B ssh-add
to work.

.SH OPTIONS
.TP 0.5i
.B \-p
Read passphrase from stdin (or pipe).
.TP
.B \-l
Lists all identities currently represented by the agent.
.TP
.B \-d
Instead of adding the identity, removes the identity from the agent.
.TP
.B \-D
Deletes all identities from the agent.

.SH RETURN STATUS

.B Ssh-add
returns one of the following exit statuses.  These may be useful in scripts.
.IP 0
The requested operation was performed successfully.
.IP 1
No connection could be made to the authentication agent.  Presumably
there is no authentication agent active in the execution environment
of
.B ssh-add.
.IP 2
The user did not supply a required passphrase.
.IP 3
An identify file could not be found, was not readable, or was in
bad format.
.IP 4
The agent does not have the requested identity.
.IP 5
An unspecified error has occurred; this is a catch-all for errors not
listed above.
.RT

.SH FILES
.TP 
.I \&$HOME/\s+2.\s0ssh/identity
Contains the RSA authentication identity of the user.  This file
should not be readable by anyone but the user.  It is possible to
specify a passphrase when generating the key; that passphrase will be
used to encrypt the private part of this file.  This is the
default file added by
.B ssh-add
when no other files have been specified.
.IP
If
.B ssh-add
needs a passphrase, it will read the passphrase from the current
terminal if it was run from a terminal.  If
.B ssh-add
does not have a terminal associated with it but
.SM DISPLAY\s0
is set, it
will open an X11 window to read the passphrase.  This is particularly
useful when calling
.B ssh-add
from a .Xsession or related script.  (Note that on some machines it
may be necessary to redirect the input from /dev/null to make this work.)

.SH AUTHOR
.LP
Tatu Ylonen <ylo@ssh.fi>

.SH SEE ALSO
.BR ssh-agent (1),
.BR ssh-keygen (1),
.BR ssh (1),
.BR sshd (8)