.\" This file is in the public domain.
.\"
.Dd June 1, 2006
.Dt MOUSSH 1
.Os NetBSD 1.4T
.Sh NAME
.Nm moussh
.Nd secure shell
.Sh SYNOPSIS
.Nm
.Op Ar options
.Op Ar host
.Op Ar command
.Sh DESCRIPTION
.Nm
is an implementation of the Secure Shell protocol.  It can run in
various modes, most commonly client, in which it connects to a server
machine and runs a command or an interactive login, but it has many
other modes of operation (some of which are used only rarely).
.Sh GETTING STARTED
To get started using
.Nm
as a user for remote login and command execution, read the
.Sx CLIENT MODE
section and, probably, the
.Sx KEY GENERATION
section.  You quite likely want to read the
.Sx AUTHENTICATION AGENT
section as well.
.Pp
To get started using
.Nm
as a sysadmin setting up remote access, read the above and also the
.Sx SERVER MODE
section.
.Sh OPERATING MODES
There are many options which set the operation mode:
.Bl -tag -width indent
.It Fl keygen
Generates a key.  The key type must be specified, either with
.Fl keytype
or with the config file (see the
.Sx CONFIG FILE
section for more).  See the
.Sx KEY GENERATION
section for more.
.It Fl agent
Runs as an authentication agent (see the
.Sx AUTHENTICATION AGENT
section for more).
.It Fl server
Runs as a server.  The server does not automatically fork by default;
when using
.Fl server ,
you normally want to either configure it to (see the
.Fl f
command-line flag and the
.Li auto-bg
config-file variable) or have the shell background the command.  See
the
.Sx SERVER MODE
section for more.
.It Fl setpass
.It Fl setpassphrase
Changes the passphrase protecting an existing public key.  See the
.Sx KEY GENERATION
section for more.
.It Fl setcomm
.It Fl setcomment
Changes the comment field of an existing public key.  See the
.Sx KEY GENERATION
section for more.
.It Fl add
Adds a key to an existing authentication agent (see the
.Sx AUTHENTICATION AGENT
section for more).
.It Fl list
Lists the keys held by an existing authentication agent (see the
.Sx AUTHENTICATION AGENT
section for more).
.It Fl delete
Deletes a key from an existing authentication agent (see the
.Sx AUTHENTICATION AGENT
section for more).
.It Fl delete-all
Deletes all keys from an existing authentication agent (see the
.Sx AUTHENTICATION AGENT
section for more).
.It Fl import
Imports a public key from the standard public-key interchange format to
.Nm moussh Ap s
format.  Public keys are read from stdin in the standard interchange
format and written to stdout in
.Nm moussh Ap s
format.  See the
.Sx PUBLIC-KEY INTERCHANGE
section for more.
.It Fl export
Exports a public key from
.Nm moussh Ap s
format to the standard public-key interchange format.  Public keys are
read from stdin in
.Nm moussh Ap s
format and written to stdout in the standard interchange format.  See
the
.Sx PUBLIC-KEY INTERCHANGE
section for more.
.It Fl kfp
.It Fl fingerprint
Reads public key data from standard input, as for
.Fl export ,
printing the fingerprint of each data blob read.
.It Fl share-kill
Tries to connect to a connection-sharing server as if it were operating
in client mode, but, if it succeeds, it asks the server thus contacted
to die.  Note that killing the server this way will unceremoniously
break all connections using it.  The server may be configured to ignore
such requests; whether or not the request is ignored,
.Nm
will exit after making the request.  If the connection fails,
.Nm
assumes no server is running and exits anyway (it does print a
complaint to stderr, but its exit code is zero, indicating success).
If the request is ignored, nothing happens.  See the
.Li ignore-kill
variable in the
.Sx CONFIG FILE
section for how to configure the server to ignore kill requests.
.It Fl share-stop
Tries to connect to a connection-sharing server as if it were operating
in client mode, but, if it succeeds, it asks the server thus contacted
to stop accepting new clients.  The server may be configured to ignore
such requests; whether or not the request is ignored,
.Nm
will exit after making the request.  If the connection fails,
.Nm
assumes no server is running and exits anyway (it does print a
complaint to stderr, but its exit code is zero, indicating success).
If the request is ignored, nothing happens.  See the
.Li ignore-stop
variable in the
.Sx CONFIG FILE
section for how to configure the server to ignore stop requests.
.Pp
This is just like
.Fl share-kill
except that it doesn't affect existing sharing clients (the sharing
server immediately stops accepting new sharing clients, but stays
around servicing existing clients until they are all gone).
.It Fl share-drop
Tries to connect to a connection-sharing server as if it were operating
in client mode, but, if it succeeds, it asks the server thus contacted
to drop all existing clients.  The server may be configured to ignore
such requests; whether or not the request is ignored,
.Nm
will exit after making the request.  If the connection fails,
.Nm
assumes no server is running and exits anyway (it does print a
complaint to stderr, but its exit code is zero, indicating success).
If the request is ignored, nothing happens.  See the
.Li ignore-drop
variable in the
.Sx CONFIG FILE
section for how to configure the server to ignore drop requests.
.Pp
This is just like
.Fl share-kill ,
in that it kills off existing shared connections, except that it
doesn't kill off the sharing server itself.  (This is not a common
operation; don't worry if you don't see any use for it.)
.It Fl kh Ar op
Operates on the known-hosts database.  See the
.Sx KNOWN-HOSTS DATABASE
section for more.
.It Fl ia
Invokes interactive-agent mode.  Connects to the authentication agent
and invokes an interactive command-line mode.  This does not work
through agent forwarding.  See the
.Sx INTERACTIVE AGENT
section for more.
.El
.Lp
If none of these options are given,
.Nm
will run in client mode.  See the
.Sx CLIENT MODE
section for more.
.Sh OTHER OPTIONS
.Nm
accepts a large number of options.  Most of them are meaningful in only
a small number of modes (often only one); they are actually accepted in
all modes but do not affect anything except when running in the mode
they are designed for.  Options that apply to some but not all modes
are mentioned in multiple sections below; some options which apply in
all (or almost all) modes with identical semantics are listed here.
.Bl -tag -width indent
.It Fl sshdir Ar dir
Gives a directory
.Pf ( Ar dir )
where
.Nm
will find various administrative files.  In most cases, this defaults
to
.Ev $HOME Ns Pa /.moussh ,
but in server mode when running as root it defaults to
.Pa /local/etc/moussh .
This directory is spoken of as SSHDIR below.  (Both these paths are the
distribution defaults; they can be changed at compile time.)
.It Fl config Ar path
Tells
.Nm
where to find its config file.  See the
.Sx CONFIG FILE
section for more.
.It Fl noconfig
Specifies that
.Nm
is not to read any config file at all.  This is equivalent to
.Fl config Pa /dev/null
(except for cases where
.Pa /dev/null
refers to something unusual).
.It Fl syslog
.It Fl nosyslog
Causes
.Nm
to, or not to, send log-type messages to the logs with
.Xr syslog 3 ,
as described in the
.Sx SERVER MODE
section, regardless of operation mode.
.It Fl V Ar arg
Turns on debugging verbosity, as controlled by
.Ar arg .
.Ar arg
is a whitespace-separated list of
.\" Growl.  ".Sq clause Ns \&s" produces `clauses', not `clause's!
.So clause
.Sc Ns \&s
(whitespace needs to be quoted for most shells, but this is rarely a
practical inconvenience because you can simply specify more than one
.Ar V
option).  Each
.Sq clause
is a comma-separated list of debugging keywords, with an optional equal
sign and a destination appended:
.D1 Fl V Ar name,name,name Ns Op Ar =destination
This turns on verbose output for all the
.Ar name Ns s
specified, sending the output to
.Ar destination
(which can be a file name,
.Sq \&-
for stdout, or
.Sq \&- Ns Ar N
for file descriptor
.Ar N ,
such as
.Sq \&-2
for standard error).  If no
.Ar destination
is given, output goes to standard error.  If the same
.Ar destination
is used more than once, it is treated as if it had been given only
once, with a merged list of keywords, but the strings given must be
identical.  Even file names as similar as
.Pa foo
and
.Pa ./foo
will be considered as different; writing to the same file twice
(whether by such means or through symbolic links or whatever) is likely
to produce garbled debugging output.  Note also that while an omitted
destination sends output to the same place that specifying
.Sq \&-2
does, they are considered different for purposes of destination
merging; similarly,
.Sq \&-
and
.Sq \&-1
are distinct.  A given verbosity keyword may be given with multiple
different destinations; output for that keyword will then go to all
those destinations.
.Pp
The list of valid debugging keywords is not given here, since it
changes relatively quckly; use
.Bk -words
.Sq Fl V Ar \&?
.Ek
(which may need to be quoted to get it past your shell) to get a help
message,
.Bk -words
.Sq Fl V Ar examples
.Ek
to see a few examples, or
.Bk -words
.Sq Fl V Ar keys
.Ek
to get a list of valid keywords.  (When one of these special cases is
used,
.Nm
does not actually start.)
.It Fl v
This is entirely equivalent to
.Fl V Ar default .
.It Fl cmd
.It Fl \&-
Either of these marks the end of the arguments to
.\" Growl.  ".Nm ;" isn't recognized as "no argument but with punctuation".
.Nm moussh ;
further arguments, if any, are interpreted in a mode-specific manner.
(For example, in client mode, they are taken as a command to execute on
the server; in
.Fl add
mode, they are taken as key files containing keys to be added.)
.It Fl nointer
Disables user interaction.  This includes prompting for things such as
key passphrases and
.Sq Fl nohk Ar prompt ;
some (presumably) sensible action is taken in each such case.  About
the only user interaction it does not disable is communication between
the user and whatever is running on the remote machine (in client mode).
.It Fl no-private
Disables attempts to use private requests and algorithms (anything
using the DNS extensibility mechanism, basically).  This should never
be needed, but at least one commercial server is known to break when
faced with such names.  This disables non-stock agent and X forwarding
and certain other things (such as a request used to make up for missing
pseudo-terminal modes in the protocol).  Its disabling of private
algorithms operates by removing them from the default lists; they can
be explicitly added back again later.
.Pp
This does not actually disable all such extensions; there are some
where the initiative is taken by the peer rather than by
.Nm moussh ,
and those are not affected.
.El
.Sh CLIENT MODE
Client mode is the commonest mode.  In this mode, a connection is made
to a remote host and (usually) a command executed or a remote login
session started.  This mode is indicated by the absence of any of the
operating-mode-setting options (see the
.Sx OPERATING MODES
section, above).
.Pp
If the command name (technically, the last component of
.Li argv[0] )
is neither
.Sq ssh
nor
.Sq moussh ,
it is taken to specify a host name to connect to (but see the
.Fl nohost
option).  If no host name is specified when the first non-flag argument
is encountered, that argument is taken as a host name.  The first
non-flag argument encountered with a host name specified is taken as
both marking the end of the arguments to
.Nm
itself and as indicating that
.Nm
is to run a command remotely instead of performing an interactive
login; all further arguments are taken as the remote command string.
Beware of shell quoting conventions; like most remote command execution
programs,
.Nm
simply takes the arguments as it finds them on the command line and
pastes them together with a single space as separator and passes the
result as the command string to execute.
.Pp
Options with meaning in client mode:
.Bl -tag -width indent
.It Fl host Ar arg
Specifies that the remote host is to be
.Ar arg .
See the above description of remote host name determination for more.
.It Fl nohost
Cancels any previously-specified host name, regardless of source.  This
can cancel any of the three ways of specifying the host name, though it
is really designed to deal with the case where
.Nm
is installed with a basename that it does not recognize and thus takes
as a host name, but specifying a host name on the command line is
desired.
.It Fl port Ar p
Specifies a port number for the remote connection.  By default,
.Nm
uses port 22, the port assigned for the Secure Shell protocol.
.Fl port
may be used more than once; each port is tried, in order, until a
successful connection is obtained or the list is exhausted.  (All
addresses are tried with the first port, then all addresses are tried
with the next port, etc, not conversely.)
.It Fl l Ar username
.It Fl user Ar username
.It Fl remuser Ar username
Specifies the user to (try to) authenticate as on the remote system.
The default is taken from the
.Ev USER
environment variable.
.It Fl e Ar escchar
.It Fl esc Ar escchar
Specifies an escape character for use when doing an interactive login.
The
.Ar escchar
argument can be the word
.Sq none ,
which specifies that no escape character is to be used (which means
both that the connection is then 8-bit-transparent and that there is no
way to break back to the local host without tearing down the remote
login).  If
.Ar escchar
is a single-character string, that character is used.  If it is a
.Sq \*(ua
followed by a single character, the corresponding control character is
used (by masking off all but the low five bits, except that
.Sq \*(ua\&?
turns into DEL).  If it is a single character with
.Sq c-
and/or
.Sq m-
prefix(es), the single character is modified by processing as described
for
.Sq \*(ua ,
if
.Sq c-
is given, and setting the high bit, if
.Sq m-
is given, then used.  If it is
.Sq 0x
(or
.Sq 0X )
followed by two hexadecimal digits, the character with that value is
used.  Anything that does not fit one of these descriptions is an
error.
.It Fl n
Specifies that the client is to ignore its input.  (It actually works
internally by redirecting input from
.Pa /dev/null . )
.It Fl f
Makes the client auto-background itself once it has completed startup
and established any forwarding specified on the command line.  (It also
redirects its standard output and error to
.Pa /dev/null
at the same time.)
.It Fl L Xo
.Sm off
.Op Ar listenhost/
.Ar listenport/connecthost/connectport
.Sm on
.Xc
.It Fl R Xo
.Sm off
.Op Ar listenhost/
.Ar listenport/connecthost/connectport
.Sm on
.Xc
These enable TCP connection forwarding.  The local process (if
.Fl L )
or the remote process (if
.Fl R )
is instructed to listen for connections on port
.Ar listenport ,
address
.Ar listenhost
(if given, or a wildcard address if not); when a connection occurs, it
is forwarded to the other end, which then connects to address
.Ar connecthost
port
.Ar connectport
and forwards data transparently both ways.
.It Fl LL Ar arg
.It Fl RR Ar arg
These are just like
.Fl L
and
.Fl R
except that if the forwarding cannot be established,
.Nm
exits (with
.Fl L
and
.Fl R ,
if the forwarding cannot be established,
.Nm
carries on without the forwarding).
.It Fl fwd Ar what
.It Fl fwdonce Ar what
.It Fl nofwd Ar what
Indicates that the thing identified by
.Ar what
is to be forwarded
.Pf ( Fl fwd )
or is not to be forwarded
.Pf ( Fl nofwd )
through the connection.
.Fl fwdonce
is like
.Fl fwd
except that a forwarding that works for only the first attempted
connection is requested instead of a normal forwarding.  (Stock agent
forwarding does not support this, so when stock agent forwarding is in
use,
.Fl fwdonce
is implemented by having the client reject all but the first forwarded
agent connection.
.Nm
implements a private request for agent forwarding that does not have
this problem, and works correctly through connection sharing besides.)
These options support the question-mark convention (see the
.Sx STRING LISTS
section).  They are a little like
.Fl L
and
.Fl R ,
but are designed for forwarding things (like authentication agent
connections) which are more complicated to forward than simply passing
data blindly over a TCP connection.  (For example, some implementations
do not use TCP for authentication agent connections.)
.It Fl share-server Ar path
Causes this process to become a connection-sharing server.
.Ar path
specifies the rendezvous point where clients can contact this server.
Any command given will be ignored; all that is used is the remote host.
See the
.Sx CONNECTION SHARING
section for more.
.It Fl auto-share-timeout secs
Sets the timeout for a connection-sharing server.  If
.Ar secs
seconds pass no shared connections being present through the sharing
server, it will exit.  See the
.Sx CONNECTION SHARING
section for more.
.It Fl share-client Ar path
Causes this process to be a connection-sharing client.
.Ar path
is the rendezvous path where it can find the connection-sharing server.
See the
.Sx CONNECTION SHARING
section for more.
.It Fl auto-share Ar path Ar lockpath
Does automatic connection-sharing.
.Ar path
is the connection-sharing rendezvous point path;
.Ar lockpath
is a path to a plain file which is used as a lock file to deal with
certain race conditions (and thus must be on a filesystem which
supports locking; see
.Xr flock 2 ) .
See the
.Sx CONNECTION SHARING
section for more.
.It Fl no-share
Disables all the connection sharing modes
.Pf ( Fl share-server ,
.Fl share-client ,
and
.Fl auto-share ) .
This is useful to override earlier options turning them on; it can also
be noticed by the config file.  See the
.Sx CONNECTION SHARING
and
.Sx CONFIG FILE
sections for more.
.It Fl share-path Ar path
Sets the connection-sharing rendezvous path.  This can override an
earlier option setting the path (and can in turn be overridden by a
later option).  Examples of other such options are
.Fl auto-share
and
.Fl share-server .
.It Fl nothing
Normally, the client either does an interactive login to, or runs a
command on, the server machine.  Sometimes this is undesirable, such as
when the point is merely to establish TCP forwarding with
.Fl L
or
.Fl R .
.Fl nothing
specifies that rather than starting a command or an interactive login,
the client is to just sit there.  The only way to make it exit is to
send it a signal (such as a keyboard interrupt) or arrange for the
connection to die.
.It Fl just-die
is similar to
.Fl nothing
in that it specifies that no command or login is to be done on the
server machine.  However, rather than sitting idle, the client is to
just exit.  This option is designed for use with
.Fl auto-share
mode (see the
.Sx CONNECTION SHARING
section), where the idea is to provoke creation of a sharing server
without actually doing anything with it, and without doing anything if
a sharing server is already running.
.It Fl kex Ar arg
This option controls key-exchange algorithm negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl hk Ar arg
This option controls host key algorithm negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl enc Ar arg
.It Fl enc-c2s Ar arg
.It Fl enc-s2c Ar arg
These options control encryption algorithm negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl mac Ar arg
.It Fl mac-c2s Ar arg
.It Fl mac-s2c Ar arg
These options control MAC (Message Authentication Code) algorithm
negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl comp Ar arg
.It Fl comp-c2s Ar arg
.It Fl comp-s2c Ar arg
These options control compression algorithm negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl ua Ar arg
This option controls user-authentication algorithm choice.  The
argument is processed as described in the
.Sx ALGORITHM NEGOTIATION
section, but the resulting list is not used to negotiate in the manner
described there; rather, it determines the list of algorithms the
client attempts to authenticate to the server with.
.It Fl lang Ar arg
.It Fl lang-c2s Ar arg
.It Fl lang-s2c Ar arg
These options control the language lists sent to the peer during key
exchange.  Two lists are sent, one for use in the client-to-server
direction, the other for use in the server-to-client direction;
.Fl lang
specifies both, with
.Fl lang-c2s
and
.Fl lang-s2c
specifying the lists individually.  This is useful only in relatively
rare circumstances; both lists are normally left empty.
.It Fl hkdb Ar path
Specifies where the database of known host keys is.  This is a file in
which is kept all known host keys, for verification that the host
contacted is the host it should be.  If not set, this defaults to
.Dv SSHDIR Ns Pa /known-hosts .
See the
.Sx KNOWN-HOSTS DATABASE
section for more.
.It Fl nohk Ar action
Specifies what to do if no key is found in the known host keys database
for the host being contacted.
.Ar action
is a keyword specifying what to do, and can be
.Bl -tag -width indent
.It prompt
Ask the user what to do.  (This is the default.)
.It yes
Continue with the connection, but don't save the key.
.It no
Don't continue with the connection.
.It save
Continue with the connection and save the key in the database.
.El
See the
.Sx KNOWN-HOSTS DATABASE
section for more.
.It Fl badhk Ar action
Specifies what to do if a key is found in the known host keys database
for the host supposedly being contacted, but it doesn't match the host
key offered by the host actually reached.
.Ar action
is a keyword specifying what to do, and can be
.Bl -tag -width indent
.It prompt
Ask the user what to do.  (This is the default.)
.It yes
Continue with the connection anyway, but don't save the key.
.It no
Don't continue with the connection.
.It replace
Continue with the connection anyway, replacing any keys found in the
database for this host and type.  THIS IS A DANGEROUS THING TO DO,
since it defeats the whole purpose of host keys to simply accept a
different host key from a host whose key is known.  You should do this
only if you're sure the new key is correct; doing it carelessly can
leave your connections to this host open to a man-in-the-middle
snooping attack.
.It replall
Continue with the connection anyway, replacing all keys found in the
database for this host, regardless of type.  THIS IS A DANGEROUS THING
TO DO, as for
.Sq replace
above.
.It add
Continue with the connection anyway, adding this key to the database
for this host, without deleting any keys.  THIS IS A DANGEROUS THING TO
DO, as for
.Sq replace
and
.Sq replall
above.
.El
See the
.Sx KNOWN-HOSTS DATABASE
section for more.
.It Fl randfile Ar path
Specifies where to find the randomness pool file.  This file is used by
the random number generator; it should be considered sensitive data,
since revealing it renders future random numbers (such as encryption
keys) highly guessable.  By default, this is in
.Dv SSHDIR Ns Pa /random-pool .
.It Fl authkeydir Ar path
This is the directory wherein authentication keys are found when the
name specified does not contain a slash.  See
.Fl authkey
for more.  This directory defaults to
.Dv SSHDIR .
.It Fl authkey Ar keyname
Use key
.Ar keyname
for authentication.  If this string contains a slash, it is used
unchanged to find the key; if not, it is looked for in the directory
specified by
.Fl authkeydir
(perhaps defaulted).
.It Fl noagent
Prevents any attempt to use keys from an authentication agent for
authentication, even if an agent is available.
.It Fl passphrase Ar phrase
Uses
.Ar phrase
as the passphrase for any keys that may need a passphrase to decrypt
the private portion.  If this option is used,
.Nm
destroys the command-line argument as soon as possible to limit
snooping with programs such as
.Xr ps 1 ,
but there is still a (usually small) window during which it may be
visible.  The possible security risk should be weighed carefully before
using it.
.It Fl tty
.It Fl no-tty
Force, or prevent, requesting a pseudo-tty from the server.  By
default, a pseudo-tty is requested when doing an interactive login but
not in other cases.
.It Fl keepalive-net
.It Fl kan
Turn on network-level keepalives for the server connection.  (When used
with connection sharing, this applies to the connection between the
sharing server and the real server, not the connection between the
sharing client and the sharing server.  As this implies, it takes
effect only when it's given on the run that actually starts a sharing
server.)
.It Fl keepalive-ssh Ar N
.It Fl kas Ar N
Turn on ssh-level keepalives.  This uses the
.Dv IGNORE
message, sending one every
.Ar N
seconds (regardless of any other activity).  While values of
.Ar N
as low as 1 are accepted, they will impair performance.
.Pp
Note that if the client is stopped (such as when it is suspended under
a job-control shell) it will not send keepalives while it is stopped.
(If connection sharing is in use, it's the sharing server whose
activity is affected by this option.)
.Pp
Traffic generated by this option is entirely one-way at the protocol
level, though at the TCP level it will provoke at least ACK packets in
return if the connection is operating normally.
.It Fl fork-pause Ar N
Delays N seconds in the child after any
.Xr fork 2
operation.  This option is designed to allow time to attach to the
child with a debugger; it is not intended for normal operation.
.El
.Sh CONNECTION SHARING
The authentication and key-exchange process is a relatively slow one,
and can take a significant amount of time when slow machines are
involved.  However, the way the protocol is designed, there is no
reason why one connection can't serve for multiple logins and/or
command executions.
.Pp
.Nm
supports sharing a single connection among multiple client runs this
way.  When sharing, there is one process on the client machine which
handles the actual network connection, multiplexing it among the
various conceptual connections using it, plus one client process per
conceptual connection.  This way authentication (and to a large extent,
key exchange) can be done once and the resulting access shared.
.Pp
Of course, there is a downside to this: it weakens security.  This is
unavoidable; whenever a client process can gain remote access without
itself authenticating, there is a risk that an intruder can use the
same channel to do likewise.  As a result, the paths mentioned below,
especially the rendezvous path, should be protected carefully against
unauthorized use.  The sharing server process does not do any further
authentication on connections made through the rendezvous point (such
as checking that they are running as the same user the sharing process
is running as); this is deliberate, so that careful use of permissions
(such as group access bits) can allow certain connections to be shared
among a wider clientele.  But it does mean that you want to be very
careful whom you allow to access the paths you specify.
.Pp
The sharing server and its clients rendezvous on an
.Dv AF_LOCAL
socket (see
.Xr unix 4 ) .
The path to this socket is the argument to
.Fl share-client
and
.Fl share-server ,
and the first argument to
.Fl auto-share .
The sharing server can be run either manually, with
.Fl share-server ,
or automatically as needed, with
.Fl auto-share .
(There are config-file analogs of all these options; see the
.Sx CONFIG FILE
section for details.)
.Pp
When run manually, one run is done with
.Fl share-server ,
which establishes the connection, authenticates, sets up the rendezvous
point, and waits.  Clients are then run with
.Fl share-client ;
they simply connect to the rendezvous point and speak a private
protocol with the sharing server, who then multiplexes all the clients
over the server connection.
.Pp
More convenient, in most circumstances, is auto-sharing mode.  This is
invoked with
.Fl auto-share ,
which takes two paths, first a rendezvous point path and second a
lock-file path.  When run this way, it first tries to act as an
ordinary sharing client, but if there appears to be no sharing server
running at that rendezvous point, it forks a process to be the sharing
server and then proceeds as if it had been running all along.  The lock
path must name a file, which is used as a lock file to deal with
certain race conditions (such as two auto-share clients starting
simultaneously in the absence of a pre-existing sharing server); this
lock file must be on a filesystem which supports
.Xr flock 2 Ns No \&-style
locking, but its contents are irrelevant and can be anything or
nothing.  If it does not exist, it will be created (with no contents)
the first time it's needed (if it cannot be created, this is a fatal
error).
.Pp
To help prevent long-idle sharing servers from holding connections open
indefinitely, tying up resources on both ends, the sharing code also
supports a timeout.  This is not set by default; when set (see the
.Fl auto-share-timeout
option and the
.Li auto-share-timeout
config-file variable), it specifies how long a sharing server will
stick around without any clients.  If, after that long after the last
client went away, the sharing server still has no clients, it will
exit.  If this value is set negative, it is effectively infinity;
setting it to zero is legal and causes the sharing server to exit as
soon as it has no clients.  The number is in seconds.
.Pp
Auto-sharing and manually-specified sharing clients and servers may be
freely intermixed (with the same rendezvous point), except of course
that a manually-specified sharing client will not work unless there is
actually a server running at the rendezvous point, and there is a
slight chance of a race condition leading to two sharing servers if a
manually-specified server starts at the same time as an auto-sharing
server, or of a client seeing its connection drop ungracefully if a
manually-specified client starts just as a auto-sharing server's
timeout expires.  (Dealing with these races is what the auto-sharing
mode lock file is for.)
.Pp
The command-line form of sharing is rather inconvenient.  Sharing is
really designed for use from the config file (see the
.Sx CONFIG FILE
section).
.Pp
Connection sharing is incompatible with the standard forms of agent
forwarding, because there is no way for the multiplexer to tell which
of its clients a given agent request belongs with.  Because of this,
.Nm
actually uses private requests to implement agent forwarding in a way
that does work with connection sharing.  For the sake of compatability,
if the private request is refused,
.Nm
will retry with the standard request if connection sharing is not
involved.
.Pp
X11 forwarding is a more complicated question.  In principle it is
possible to use the standard requests even through connection sharing.
However, doing so is complicated enough that
.Nm
does not try to do it, though it does handle standard X forwarding when
not connection-sharing.  The private requests it prefers to use instead
are designed to work well with connection sharing.
.Pp
There is also the
.Fl no-share
option, which disables all the connection sharing options.  (There is
no config-file option analogous to
.Fl no-share ,
since the config file can just explicitly set the various sharing
option variables false.)
.Sh SERVER MODE
In server mode, ie, when run with
.Fl server ,
.Nm
runs as a server, accepting connections and implementing the server
side of the protocol.  This also causes
.Nm
to change its usual logging behaviour.  Normally, log-type information
is written to standard error by default.  In this mode, such messages
are by default sent to the logs with
.Xr syslog 3 ,
using log levels
.Dv LOG_INFO
through
.Dv LOG_ERR
(depending on the message) and facility
.Dv LOG_AUTH
(or, for some messages,
.Dv LOG_AUTHPRIV ) .
This can be controlled (regardless of operation mode) with the
.Fl syslog
and
.Fl nosyslog
options; only the default differs between server mode and other modes.
Not all messages are affected; logging to syslog is designed for server
mode, and messages which are unlikely or impossible in server mode will
normally go to stderr regardless of
.Fl syslog ,
but messages which are generated in server and other modes will usually
be affected even when not in server mode.
.Pp
Options that function in server mode:
.Bl -tag -width indent
.It Fl port Ar p
Specifies a port to listen on.  Multiple
.Fl port
options may be given to listen on multiple ports.  By default.
.Nm
listens on port 22, the port assigned for the Secure Shell protocol.
In server mode, the argument may include an address as well, in the
form
.Ar address/port ,
in which case
.Nm
listens only on that address (the port, but not the slash, may be
omitted, in which case the default port is used); if no
.Ar address/
part is given, a wildcard address is used, thus listening on all
available addresses.
.It Fl f
Makes the server auto-background itself once it has completed startup.
.It Fl kex Ar arg
This option controls key-exchange algorithm negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl hk Ar arg
This option controls host key algorithm negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl enc Ar arg
.It Fl enc-c2s Ar arg
.It Fl enc-s2c Ar arg
These options control encryption algorithm negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl mac Ar arg
.It Fl mac-c2s Ar arg
.It Fl mac-s2c Ar arg
These options control MAC (Message Authentication Code) algorithm
negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl comp Ar arg
.It Fl comp-c2s Ar arg
.It Fl comp-s2c Ar arg
These options control compression algorithm negotiation.  See the
.Sx ALGORITHM NEGOTIATION
section for more.
.It Fl ua Ar arg
This option controls user-authentication algorithm choice.  The
argument is processed as described in the
.Sx ALGORITHM NEGOTIATION
section, but the resulting list is not used to negotiate in the manner
described there; rather, it determines the list of user authentication
algorithms the server will support.
.It Fl lang Ar arg
.It Fl lang-c2s Ar arg
.It Fl lang-s2c Ar arg
These options control the language lists sent to the peer during key
exchange.  Two lists are sent, one for use in the client-to-server
direction, the other for use in the server-to-client direction;
.Fl lang
specifies both, with
.Fl lang-c2s
and
.Fl lang-s2c
specifying the lists individually.  This is useful only in relatively
rare circumstances; both lists are normally left empty.
.It Fl randfile Ar path
Specifies where to find the randomness pool file.  This file is used by
the random number generator; it should be considered sensitive data,
since revealing it renders future random numbers (such as encryption
keys) highly guessable.  By default, this is in
.Dv SSHDIR Ns Pa /random-pool .
.It Fl hostkeydir Ar path
Specifies where to find the host's host key(s).  Every supported host
key algorithm has a file name under which it looks for a host key in
this directory.  This defaults to
.Pa /local/etc/moussh/hostkeys
(in the distribution; it can be changed at compile time).
.It Fl oneconn
This tells
.Nm
to accept only one client connection, and to avoid forking a server
process to process it - instead the main process shuts down its
listening sockets and becomes the server process for the connection.
(This is intended to make certain debugging operations easier; it is
not intended for normal use, though someone could conceivably find a
use for it.)
.It Fl fwd Ar what
.It Fl nofwd Ar what
Indicates that forwarding is to be permitted
.Pf ( Fl fwd )
or denied
.Pf ( Fl nofwd ) ,
if the client requests it, for the thing identified by
.Ar what .
These options support the question-mark convention (see the
.Sx STRING LISTS
section).  See also the client-mode interpretation of these flags.
.It Fl fwdonce Ar what
This option is for use in client mode; it is recognized, but has no
effect, in server mode.
.It Fl neverauth
Prevents authentication from succeeding, ever, no matter what
authentication information is presented.  (This is intended for
interoperability testing of the layers that can be tested without
authenticating, not for normal operation, though conceivably it may
find some other use such as honeypots.)
.El
.Sh KEY GENERATION
When operating in key generation mode, with
.Fl keygen
given,
.Nm
generates a public/private key pair and writes them to a pair of files.
Also described in this section are passphrase changing
.Pf ( Fl setpass )
and comment changing
.Pf ( Fl setcomm ) .
Options with meaning in key-generation mode are:
.Bl -tag -width indent
.It Fl randfile Ar path
Specifies where to find the randomness pool file.  This file is used by
the random number generator; it should be considered sensitive data,
since revealing it renders future random numbers (such as encryption
keys) highly guessable.  By default, this is in
.Dv SSHDIR Ns Pa /random-pool .
.It Fl keytype Ar type
Gives the type of key to generate.  This is a short name, such as
.Sq rsa ,
which identifies the public-key algorithm for which a key pair is to be
generated.  This option supports the question-mark convention (see the
.Sx STRING LISTS
section).
.It Fl keysize Ar bits
Give the size of the key to be generated, in bits.  Every key type has
a default size, but you can override it with this option.  There may be
a minimum on key sizes; whether this is true, and what the minimum is,
may vary depending on the key type.  It generally is far too small to
provide anything near security in practice.
.It Fl keyfile-pub Ar path
.It Fl keyfile-priv Ar path
.It Fl keyfile Ar path
These specify where to write the resulting key pair.
.Fl keyfile-pub
specifies where to write the public portion of the key;
.Fl keyfile-priv
specifies where to write the private portion.
.Fl keyfile
is equivalent to specifying both of the other two with the same value,
and is the usual way to give key file names; the detailed flags should
be needed only in very unusual circumstances.
.Pp
Regardless of how they are specified, the public key file name will
have
.Sq Pa .pub
appended and the private key file name will have
.Sq Pa .priv
appended.  If the name contains a slash, it is used directly;
otherwise, it is interpreted as relative to
.Dv SSHDIR .
If either portion is unspecified, a default (which depends on the key
type) will be used.
.It Fl passphrase Ar phrase
Gives a passphrase with which the private portion of the generated key
is encrypted when writing it to its file.  If this option is used,
.Nm
destroys the command-line argument as soon as possible to limit
snooping with programs such as
.Xr ps 1 ,
but there is still a (usually small) window during which it may be
visible.  The only case where it is perfectly safe to use this flag is
when specifying an empty passphrase (which means that the private
portion of the key is not encrypted).  Host keys must use empty
passphrases; authentication keys may too, but doing so leaves the key
open to compromise by anyone who can read the file (including by
reading the disk directly).  The possible security risk should be
weighed carefully before deciding how to proceed here.
.It Fl comment Ar comm
Gives a comment which is to be attached to the generated key.  If not
given, a default is generated from from the
.Ev USER
environment variable and the hostname (as obtained by
.Xr gethostname 3 ) .
.It Fl keyvalues
Normally, the generated values for the key (e.g., n, e, and d for RSA
keys) are not written anywhere but the output files.  With this option,
they are printed to standard output as well.  (The details of the
output produced will depend on the key type.)
.El
.Lp
When changing a passphrase with
.Fl setpass ,
relevant options are:
.Bl -tag -width indent
.It Fl keyfile Ar filename
.It Fl keyfile-priv Ar filename
These function as described above for key generation, except that the
private file name determined is where to find the key whose passphrase
is to be changed, rather than where to write a generated key.  (The
public portion is not affected and its filename does not need to be
correct.)
.It Fl passphrase Ar phrase
This specifies the new passphrase.  Security concerns very similar to
those for key-generation mode, above, apply here.  If
.Fl nointer
is given,
.Fl passphrase
must also be given.
.El
.Lp
When changing a comment with
.Fl setcomm ,
relevant options are:
.Bl -tag -width indent
.It Fl keyfile Ar filename
.It Fl keyfile-pub Ar filename
These function as described above for key generation, except that the
public file name determined is where to find the key whose comment is
to be changed, rather than where to write a generated key.  (The
private portion is not affected and its filename does not need to be
correct.)
.It Fl comment Ar phrase
This specifies the new comment.  If
.Fl nointer
is given,
.Fl comment
must also be given.
.El
.Sh ALGORITHM NEGOTIATION
There are various algorithms which are negotiated between the server
and client.  These are key-exchange, host key, encryption, MAC, and
compression algorithms; the last three of these are actually negotiated
in pairs, once for each direction (client-to-server and
server-to-client), making a total of eight algorithm lists.  For each
of these lists, there is a set of algorithms the code supports; some
subset of this set is offered to the peer during negotiation.  (The
algorithm actually chosen in each case is the first algorithm on the
client's list that's also present on the server's list.)
.Pp
In each case there are command-line options to control the lists
offered.  The procedure in each case is that the list starts with a
default list, including all the supported algorithms (or nearly all;
for example,
.Dq none
encryption is not present in the default encryption algorithm list).
This list is then modified by applying the command-line options in
turn; after this processing is done, the resulting list is what is
offered during negotiation.
.Pp
In each case, the command-line option controls what list(s) the
modification applies to.  For key-exchange
.Pf ( Fl kex )
and
host key
.Pf ( Fl hk ) ,
this is simple; for the other six lists, there are six options
.Pf ( Fl enc-c2s ,
.Fl enc-s2c ,
.Fl mac-c2s ,
.Fl mac-s2c ,
.Fl comp-c2s ,
and
.Fl comp-s2c )
that control them similarly, but there are also three options
.Pf ( Fl enc ,
.Fl mac ,
and
.Fl comp )
for which the modification specified is applied to both of the relevant
lists.  The argument to the command-line flag indicates how the
affected list (lists) is (are) to be modified.
.Pp
These options support the question-mark convention (see the
.Sx STRING LISTS
section).  Besides that, the argument can be:
.Bl -bullet
.It
.Sq DEFAULT
(must be in all caps), which discards the current list and replaces it
with the default list.
.It
.Sq CLEAR
(must be in all caps), which clears the current list and leaves it
empty (presumably to be further modified by more options).
.It
A comma-separated list of algorithm names
.Pf ( Ar alg,alg,alg,... ) ,
which discards the current list and replaces it with the list given.
The first-listed algorithm is in the most-preferred spot.
.It
.Sq \&+
followed by a comma-separated list of algorithm names, which moves the
listed algorithms to the more-preferred end of the list, adding them to
the list if necessary.  The first-listed algorithm ends up in the
most-preferred spot.
.It
.Sq \&+-
followed by a comma-separated list of algorithm names, which moves the
listed algorithms to the less-preferred end of the list, adding them to
the list if necessary.  The first-listed algorithm ends up most
preferred of the listed algorithms.
.It
.Sq \&-
followed by a comma-separated list of algorithm names, which removes
the listed algorithms from the list entirely.  An unrecognized
algorithm name is an error, but a recognized algorithm that is not
currently in the list is not.
.El
.Lp
Anything else is an error.
.Sh STRING LISTS
Several options take a keyword or list of keywords.  These generally
support something called the question-mark convention.  This is that if
the argument consists of a single question mark (which may need to be
quoted, eg,
.Li \e?\&
or
.Li \&"?" ,
depending on the shell in use),
.Nm
will print a list of recognized keywords (and then will not start).
.Sh PUBLIC-KEY INTERCHANGE
.Nm
works with public keys in a one-line text format which typically uses
very long lines (thousand-character lines are not unusual).  This is
not the defined public-key interchange format.  To promote
interoperability with other implementations,
.Nm
has operating modes which convert between the two formats; see the
.Fl import
and
.Fl export
flags in the
.Sx OPERATING MODES
section.  In
.Nm moussh Ap s
format, every key has an associated
.Sq comment ,
which is an arbitrary string that presumably means something to humans
who work with the key.
.Pp
When a key is exported to interchange format, the comment is converted
to a
.Dq Comment:
header; a
.Dq Subject:
header is also generated if a user name has been specified with
.Fl l ,
.Fl user ,
or
.Fl remuser
(which are described in the
.Sx CLIENT MODE
section, since they are primarily for client-mode use), or with their
config-file analogs (see the
.Sx CONFIG FILE
section).
.Pp
When importing a key from interchange format, the
.Dq Comment:
header, if present, is converted to the key's comment; all other
headers are ignored.
.Pp
There is no interchange format defined for private-key data, so there
is no analog to
.Fl import
or
.Fl export
for the private portion of a key pair.
.Sh AUTHENTICATION AGENT
When the private portion of an identity key is protected by a
passphrase (which should normally be done for the sake of security), it
can be tedious to have to type the passphrase every time you use the
key.  To help with this problem, the authentication agent was invented.
This is a process which sits around holding authentication keys and
performing public-key operations with them as needed on request from
clients.  Once the agent has been given the private portion of the key,
it does not give it out to anyone, but is willing to use it.  While
this offers some convenience to local users, its major advantage is for
remote sessions: a client's connection to the authentication agent can
be forwarded through an ssh connection, so that an agent on the local
machine can be used by a client running on a remote machine, without
having to allow the remote machine to ever have a copy of the relevant
private-key data.  (This is an example of what is known as
.Dq single sign-on ,
since you have to give the key's passphrase only once, when decrypting
the key to install it in the agent.)  The agent persists until the
command it was told to run (usually a shell) exits, at which point it
exits and throws away its copies of all the data it was saving.
.Pp
Keys in the agent can have constraints, which restrict them in various
ways.  If no constraints are specified when adding keys, the keys are
not restricted; to specify constraints when adding keys, use
.Fl constraint ,
which takes an argument describing the desired constraints (see its
description below for more).
.Pp
In this implementation, an agent is started with the
.Fl agent
flag.  This sets up the agent and then runs the command given on the
command line, or the shell found in the
.Ev SHELL
environment variable if no command is specified.  (If
.Ev SHELL
isn't set either,
.Pa /bin/sh
is used.)  The agent provides an environment variable,
.Ev SSH_AGENT ,
holding the data necessary to contact the agent; this must be in the
environment for the rest of the agent mechanisms to work right.  The
agent holds no keys when it first starts up; any desired keys must be
added after startup.
.Pp
Various of the operating modes manipulate the agent (and produce errors
if the agent environment variable is missing or an agent can't be
contacted using the data in it).  Specifically:
.Bl -tag -width indent
.It Fl add
This adds keys to the agent.  The command-line arguments are taken as
names of keys; they are read (prompting for their passphrases if
necessary) and installed into the agent.  See
.Fl authkey
in the
.Sx CLIENT MODE
section for a description of how the files are located from the key
name.
.Pp
If no key names are given on the command line,
.Nm
tries the default file name for each supported key algorithm, behaving
as if those names had been specified on the command line.
.Pp
For completely automated use of keys with passphrases,
.Fl passphrase
can be given to provide the passphrase to be used for any keys that
need passphrases.  Caveats similar to the use of
.Fl passphrase
in client mode apply; see the
.Fl passphrase
description in the
.Sx CLIENT MODE
section for more.
.It Fl delete
This deletes keys from the agent.  The command-line arguments are taken
as names of keys; their public parts are read and used to delete those
keys from the agent.  (The private part is not needed, so no passphrase
is necessary.)  See
.Fl authkey
in the
.Sx CLIENT MODE
section for a description of how the files are located from the key
name.
.Pp
If no arguments are given, one delete is performed, and the key for it
is read from the standard input.  This is how to delete a key you have
in the agent but don't have a convenient public-key file for: use
.Fl list
with
.Fl long
to print all the keys, pick out the one you want to delete with a tool
such as
.Xr grep 1 ,
and pipe it into a
.Fl delete
run with no arguments.  You can also use a public-key file on stdin;
this can sometimes be more convenient than using
.Fl delete
in the normal way.
.Pp
A key is considered to match if its key data matches; the comment does
not need to match.
.It Fl delete-all
This deletes all keys from the agent.
.It Fl list
This lists the keys the agent holds.  If the agent holds no keys, a
message saying so is printed; otherwise, one line per key is printed,
giving the key type and comment.  If
.Fl long
is also given, the output format changes.  The message in the no-keys
case is suppressed, and the public-key data blob is printed as well as
the key type and comment for each key.  Each line of
.Fl list
.Fl long
output, if extracted and put in a file by itself, will be a valid
public key file.
.El
.Pp
If agent forwarding is enabled (which it is by default), arrangements
are made when a remote command execution or remote login is done such
that the agent functionality is transparently available to the remote
side.  The remote server establishes an agent listener in whatever its
local fashion is, with connections forwarded to the local agent through
the connection.  This can be controlled with the
.Fl fwd
and
.Fl nofwd
flags; to the client, they control whether forwarding is requested,
while to the server, the control whether forwarding is permitted if the
client requests it.
.Pp
Other options which affect agent mode are listed here.  (Some of them
are also mentioned above.)
.Bl -tag -width indent
.It Fl authkey
This affects how operations that read key files find their files; see
its description in the
.Sx CLIENT MODE
section for more.
.It Fl passphrase
This can be used to automate use of keys with passphrases.  It carries
security risks in most situations; see its description in the
.Sx CLIENT MODE
section for more.
.It Fl long
This affects how
.Fl list
prints keys; see the description of
.Fl list
above for more.
.It Fl constraint
This specifies constraints when adding keys with
.Fl add .
It takes an argument specifying the constraint(s) desired.  If multiple
conflicting constraints are specified, either on a single option or on
multiple options, they are processed left-to-right, with the last
specification for any particular constraint governing.  The argument to
.Fl constraint
is a comma-separated list of options.  Options can be:
.Bl -tag -width indent
.It Li time\&= Ns Sy time
Specifies that the key expires after
.Sy time ;
it may not be used after its timeout expires.  The time interval may be
given as a number of seconds, or it may be a value built up from counts
and units, such as
.Sq 2d12h
or
.Sq 4h15m45s .
The units supported are weeks
.Pf ( Sq w ) ,
days
.Pf ( Sq d ) ,
hours
.Pf ( Sq h ) ,
minutes
.Pf ( Sq m ) ,
and seconds
.Pf ( Sq s ) .
A value of zero indicates no timeout.
.It Li use\&= Ns Sy count
Specifies that the key may be used no more than
.Sy count
times.  To specify no limit, use a
.Sy count
of
.Sq inf .
.It Li fwd\&= Ns Sy count
Specifies that the key may not be used through more than
.Sy count
agent forwardings.  To specify no limit, use a
.Sy count
of
.Sq inf .
.It Li confirm= Ns Sy yesno
Key use by the agent may be set to require interactive confirmation
before operations are performed.  By default, this is not required;
this constraint allows to specify that it is.  If
.Sy yesno
is
.Sq yes ,
confirmation is required; if it is
.Sq no ,
not.
.El
.Pp
Note that
.Fl constraint
must appear before any key filenames on the command line, since the
first such filename stops option parsing; all remaining arguments are
taken as key filenames.
.El
.Sh INTERACTIVE AGENT
There is an interactive interface to the authentication agent.  This is
invoked with the
.Fl ia
flag.  The interactive agent inteface allows direct commands to the
agent to do things like show keys and be notified of client actions.
There is internal help available; use a lone ? to get started.
.Sh KNOWN-HOSTS DATABASE
.Nm
maintains a list of known host keys (by default, this is stored in
.Dv SSHDIR Ns Pa /known-hosts ;
see the
.Fl hkdb
option and the
.Li host-key-db
config-file variable for how to change its location).  These are used
to verify that the server actually contacted is the one desired, that
is, to foil man-in-the-middle attacks on the protocol.  Because of the
importance of such attacks (there is at least one canned attack kit
known to exist in the wild designed to mount such attacks against an
older protocol version), correct use of the known-hosts database is
crucial to proper security.
.Pp
Ideally, you should obtain the correct host key for the server you wish
to contact through some out-of-band means.  However, this is rarely
feasible, except for high-risk and/or high-value connections, where the
additional security is worth the inconvenience; most applications will
accept slightly weakened security for the sake of convenience.  Most
ssh implementations, including
.Nm moussh ,
allow you to simply assume that you reach the server you mean to the
first time you connect, rememebring the host key for later connections.
(The risk here is that that first connection could suffer a MitM
attack.)  Fortunately, even in relatively high-risk cases, it is often
feasible to ensure that the first connection is difficult to attack,
even if later ones aren't so secure; for example, a roaming user's
laptop could make its first connection over a relatively secure LAN,
saving the host key for verifying later connections over the open
Internet.
.Pp
.Nm moussh Ap s
known-hosts database saves keys (usually only one, but potentially
many) for each host.  When connecting to a server, if the server host
is in the database, the offered host key is checked against the
database.  What happens if the server host is not in the database is
configurable, as is what happens if the offered host key doesn't match
what's in the database.  By default, the user is prompted in either of
those cases; this can be modified with the
.Fl nohk
and
.Fl badhk
command-line flags and the
.Li no-hk-action
and
.Li bad-hk-action
config-file settings.
.Pp
When the host isn't in the database, there are really only three
options: abort the connection, save the key and continue, and continue
without saving the key.  In addition to reporting the host-key
fingerprint,
.Nm
also checks to see if the key is known for any other hosts (in case you
are contacting an already-known server via a name that isn't in the
database yet).
.Pp
The case where the server is in the database but the host key obtained
from the connection doesn't match what's in the database is much more
serious.  This is exactly what will happen if a MitM attack is
attempted, but there are other things that can produce it, such as the
server being reinstalled with new host keys.  Unless you know that the
host key has changed, you should be extremely suspicious in this case.
See the
.Fl badhk
option for a list of the available actions in this case.
.Pp
.Nm
supports rudimentary but sufficient operations on the known-hosts
database.  These are accessed via the
.Fl kh
operation mode.  This option takes an argument specifying what to do
with the database; some of them take additional arguments.  This
supports the question-mark convention (see the
.Sx STRING LISTS
section).
.Pp
In order to use this effectively, you will need to understand a
subtlety: it is actually not hosts that are stored in the database, but
host/port pairs, since connecting to a different port may reach a
different ssh installation, for any of various reasons (chroot, NAT,
etc).  Thus,
.Sq host
above should really be understood to refer to a hostname/port pair,
and, in the descriptions below, a host can be either a bare host name
or a host/port pair, with a slash between them.  The individual
operation descriptions say what happens if a bare host name is used;
since, theoretically, a hostname may contain a slash, specifying a
single dash
.Sq \&\-
as a port is semantically equivalent to omitting the port.  (A port
number can never contain a slash, so there is no ambiguity if the
string contains multiple slashes.)  Specifically, the possibilities
are:
.Bl -tag -width indent
.It Fl kh Li import Ar host
Imports a key.  A public-key data blob is read from stdin and is added
to the database for the specified
.Ar host .
The port number defaults to 22 if not given.
.It Fl kh Li export Ar host
Exports keys.  All keys in the database for the specified
.Ar host
are extracted and printed to stdout (in no particular order).  If no
port number is given, keys are printed for all port numbers for which
the database contains anything.
.It Fl kh Li clear Ar host
Clears all keys for the specified
.Ar host .
If no port number is given, an error occurs (it would be more logically
consistent to either default to 22 or delete keys for all ports; this
action was chosen to limit the damage from likely mistakes).
.It Fl kh Li delete Ar host
Reads a public-key data blob from stdin; if that key is in the database
for the specified
.Ar host ,
it is deleted.  (If not, a message is printed and nothing is done.)  If
no port number is specified, the key is deleted for all ports for which
it's found.
.It Fl kh Li ports Ar host
.Pf ( Ar host
must not include a port number.)  All port numbers for which the
database contains any keys for the specified
.Ar host
are printed, one per line.  (Just the port numbers are printed; the
host name is not repeated.)
.It Fl kh Li find
A public-key data blob is read from stdin and all host/port pairs for
which that key is in the database are printed.
.It Fl kh Li hosts
Prints a list of hosts for which keys are known, one per line.
.El
.Pp
Host names are treated as opaque strings;
.Pa bigbox
and
.Pa bigbox.example.com
are considered distinct, even if they refer to the same host.
.Sh CONFIG FILE
.Nm
includes a configuration file capability.  Almost all of the
command-line options have config-file analogs (the most notable
exceptions are the ones which set the operation mode, but there are a
few other exceptions, such as
.Fl V
and
.Fl config ) .
.Pp
.Nm
looks for its config file in the path specified by
.Fl config .
If
.Fl config
is not given,
.Nm
looks at the environment variable
.Ev SSH_CONFIG ;
if that is not set, it uses
.Dv SSHDIR Ns Pa /config .
The config file can also be suppressed completely with
.Fl noconfig ,
which is semantically equivalent to using an empty config file
(somewhat like what
.Fl config Pa /dev/null
will normally do).
.Pp
When a config file is read, it is taken as a script in a very simple
scripting language.  This language has only four constructs:
.Bl -bullet
.It
Comments.  Any line that is completely blank, or whose first
non-whitespace character is NUL,
.Sq \&# ,
or
.Sq \&; ,
is a comment and is ignored.
.It
Conditionals.  Lines of the form
.Bl -tag -compact -width indent
.It ""
.Li if Sy expression
.It ""
.Li else
.It ""
.Li elif Sy expression
.It ""
.Li endif
.El
control the execution of lines within them in the usual way.  See below
for more details on
.Sy expression Ns s .
.It
Assignments.  These lines are of the form
.Bk -words
.Sq Va variable No \&= Sy expression
.Ek
or
.Bk -words
.So Va variable No \&=
.Sc ,
.Ek
and are the way the config file influences operation.  (The second
form, with no
.Sy expression ,
causes the
.Va variable
to lose any config-file setting, reverting to the state it would have
in the absence of any config-file setting (which may be unset or may
have a value).)
.It
Macro definitions.  These lines are of the form
.Bk -words
.Sq Va variable No \&: Sy expression ;
.Ek
see below for more.
.El
.Pp
Line continuation is supported; if the last character on a line is a
backslash (\&\e), the backslash and the line break following it are
deleted, thus pasting the line and the following line together.  This
happens before any parsing is attempted.
.Pp
Expressions are made up in the usual way from constants, operators, and
parentheses.  Values can be of six types: boolean, integer, string,
address, CIDR block, and set; sets must have all their members of the
same type, and are unordered.  Integer constants are written in the
usual way in decimal, possibly prefixed with a minus sign for negative
numbers.  String constants are written surrounded with either single
(\&') or double (\&") quotes.  There is no mechanism for escaping
characters within string constants; if a string needs to contain both
\&' and \&" characters, it must be built up using string concatenation.
Newlines and NULs cannot appear in strings.  Boolean constants are
.Li \&.true
and
.Li \&.false ,
with the obvious meanings.  There are no address, CIDR, or set
constants, though a call to the appropriate function with a suitable
argument amounts to much the same thing.  The operators, in order of
tightness of binding, tightest to loosest and with operators of equal
tightness on the same line, are:
.Bl -tag -compact -width indent
.It ""
.Li \&? \&[] \&\-
.It ""
.Li \&{:}
.It ""
.Li \&* \&/
.It ""
.Li \&+ \&\-
.It ""
.Li \&.
.It ""
.Li \&@ \&~ \&== \&!@ \&!~ \&!=
.It ""
.Li \&!
.It ""
.Li \&& \&&&
.It ""
.Li \&| \&||
.El
\&!, \&?, and the first \&\- are unary, and \&[] is variable; the rest
are binary.
Their meanings:
.Bl -tag -width indent
.It Li \&? Va variable
Returns true if 
.Va variable
is set, false if not.
.It Sy expr1 Li \&@ Sy expr2
This expression has two forms.  If
.Sy expr2
is an IP network in CIDR notation (syntactically, an address followed
by a slash and a mask width), then
.Sy expr1
must be an IP address (in string form), and the return value is
.Li \&.true
if the address in
.Sy expr1
falls into the network described by
.Sy expr2 ,
.Li \&.false
otherwise.  Otherwise, both expressions are taken as domains, and the
return value is
.Li \&.true
if
.Sy expr1
is equal to or under the domain
.Sy expr2 ,
.Li \&.false
otherwise.  In this form, if
.Sy expr2
begins with a dot and
.Sy expr1
doesn't, but they are otherwise equal, the expression returns
.Li \&.false ,
so prefixing
.Sy expr2
with a dot serves, in practice, to remove the
.Sq "equal to"
case from the foregoing.
.It Sy expr1 Li \&!@ Sy expr2
Identical to
.Li \&! \&(
.Sy expr1
.Li \&@
.Sy expr2
.Li \&) .
.It Sy expr1 Li \&~ Sy expr2
Returns
.Li \&.true
if the string
.Sy expr1
matches the regular expression
.Sy expr2 ,
.Li \&.false
otherwise.
.It Sy expr1 Li \&!~ Sy expr2
Identical to
.Li \&! \&(
.Sy expr1
.Li \&~
.Sy expr2
.Li \&) .
.It Sy expr1 Li \&== Sy expr2
Returns
.Li \&.true
if the string
.Sy expr1
equals the string
.Sy expr2 ,
.Li \&.false
otherwise.  (This is limited to strings; values of other types will be
converted to strings.)
.It Sy expr1 Li \&!= Sy expr2
Identical to
.Li \&! \&(
.Sy expr1
.Li \&==
.Sy expr2
.Li \&) .
.It Li \&! Sy expr
Returns
.Li \&.true
if
.Sy expr
is false,
.Li \&.false
otherwise.
.It Sy expr1 Li \&& Sy expr2
Returns
.Li \&.false
if either
.Sy expr1
or
.Sy expr2
is false,
.Li \&.true
otherwise.  (This operator can also be spelled \&&&.)
.It Sy expr1 Li \&| Sy expr2
Returns
.Li \&.true
if either
.Sy expr1
or
.Sy expr2
is true,
.Li \&.false
otherwise.  (This operator can also be spelled \&||.)
.It Sy expr1 Li \&. Sy expr2
Treats
.Sy expr1
and
.Sy expr2
as strings, and returns the concatenation of the two.
.It Sy expr1 Li \&+ Sy expr2
.It Sy expr1 Li \&\- Sy expr2
.It Sy expr1 Li \&* Sy expr2
.It Sy expr1 Li \&/ Sy expr2
These perform integer arithmetic.  \&\- can also be used as a unary
operator to negate a number.
.It Xo
.Sy expr1
.Li \&{
.Sy expr2
.Li \&:
.Sy expr3
.Li \&}
.Xc
Returns
.Sy expr2
if
.Sy expr1
is true,
.Sy expr3
if not.  Note that this operator is marked as binding fairly tightly;
since it is mostly self-delimiting, this really means just that the
condition part,
.Sy expr1 ,
often needs parens around it.
.It Xo
.Li \&[
.Sy name
.Sy arg ,
.Sy arg , No ...
.Li \&]
.Xc
Calls a function.  The
.Li name
specifies which function.  Depending on the function, there may be
restrictions on the number of arguments.  The value returned depends on
the function and arguments.  Currently defined functions are:
.Bl -tag -width indent
.It Li lc
Takes exactly one argument.  Return value: the argument, converted to a
string, then converted to lower case.
.It Li env
Takes one or two arguments.  The first (or only) argument is converted
to a string and then looked up as an environment variable.  The return
value is the result of the environment lookup, or, if the variable is
not set in the environment, the second argument (which need not be of
any particular type).  If there is no second argument, it is as if a
zero-length string were passed as the second argument.
.It Li type
Takes exactly one argument.  The return value is a string giving the
type of the argument:
.Sq boolean ,
.Sq string ,
.Sq integer ,
.Sq address ,
.Sq cidr ,
or
.Sq set .
.It Li matchsub
Takes three or four arguments: string, pattern, replacement, and
possibly a failure value.  The pattern, which must be a string, is
treated as a regular expression; the string is matched against it.  If
the match succeeds, the matched portion of the string is replaced with
the replacement string, processed to replace escapes (as described
below) with the corresponding strings from the match.  If the match
fails, the failure value is returned; if there is no failure value, the
default is to return the string unchanged.  This is analogous to the
.Li s
operation in editors such as
.Xr sed 1
or
.Xr ed 1 ,
but the details are different (for example, in the replacement, what
.Xr sed 1
writes as
.Ql \&&
must be written as
.Ql \&\e0
instead).
.Pp
The escapes in the replacement string take two forms: either a
backslash,
.Ql \&\e ,
followed by a single digit, in which case the digit gives the number of
the matched string to use, or a backslash followed by multiple digits
in parens, as in
.Ql \&\e(14) ,
which are similar but allow for multi-digit numbers.  (What results if
a backslash is not followed by one of those two forms is not defined;
it will be some string, but no promises are made about what string.)
.It Li bool
Returns its argument, converted to a boolean.
.It Li str
Returns its argument, converted to a string.
.It Li int
Returns its argument, converted to an integer.
.It Li addr
Returns its argument, converted to an address.
.It Li cidr
Returns its argument, converted to an CIDR.
.It Li set
Constructs and returns a set containing all the arguments (which must
all be of the same type).
.It Li in
Tests whether a set (the first argument) contains a particular object
(the second argument).
.It Li rdns
Takes an address, or something which can be converted to an address,
and does a reverse-DNS lookup on it, returning a set containing all the
resulting DNS names, as strings.  (The resulting set may be empty.)
.It Li fdns
Takes a DNS name, as a string, and does a forward-DNS lookup on it,
returning a set containing all the resulting addresses.  (The resulting
set may be empty.)
.It Li map
Takes five arguments: a return dummy variable, which must be a
\&$-prefixed convenience variable, an iteration dummy variable, which
must also be a \&$-prefixed convenience variable, an iteration
expression, an initial value, and a set.  It first saves the state of
the dummy variables.  Then it loops through the set, assigning each
element in turn to the iteration variable, evaluating the iteration
expression, and assigning the result to the return variable.  When it's
done, it restores the dummy variables and returns the last value of the
return variable (ie, just before restoration).  The iteration exprssion
will normally use the return and iteration variables in some way, but
it does not have to.
.Pp
A variable defined as a macro cannot be used as a dummy variable
argument; the macros will be expanded instead.  (A variable defined as
a macro can appear textually if the expansion results in a suitable
variable, but it is the result of the expansion that is used, not the
macro variable.)
.It Li md5
Converts its argument to a string and returns the MD5 hash of that
string, as a 32-character hexadecimal string.
.It Li sha1
Converts its argument to a string and returns the SHA-1 hash of that
string, as a 40-character hexadecimal string.
.El
.El
.Pp
Macro definitions make a variable equivalent to an expression.
Whenever the variable is used, it is as if the expression were
substituted.  (This is different from an assignment in that the
expression is evaluated when the variable is used, rather than when it
is set.)  Only convenience variables (names beginning with
.Sq \&$ ,
see below) may be macros.  Note that macro expansions are effectively
surrounded by parens; the expansion must be a complete expression, and
is not subject to precedence lossage the way it would be with a purely
text-based macro facility.  (For example, after
.D1 \&$x \&: 3 \&+ 3
.D1 \&$y \&= \&$x \&* 2
then
.Li \&$y
will be 12, not 9, and
.D1 \&$x \&: 3 \&+
is an error, even if \&$x is used in a way like
.D1 \&$y = \&$x 7
that would work with a purely text-based macro facility.)
.Pp
When an expression is tested for its truth value, such as happens for
.Li if
and
.Li elif
lines or for the
.Li \&!\&
operator, whether it is considered true or false depends on its type
and value.  Booleans, of course, treat
.Li \&.true
as true and
.Li \&.false
as false.  Integers treat zero as false and anything else as true.
Strings treat the zero-length string as false and anything else as
true.
.Pp
When a value must be converted to a string, such as for string
concatenation,
.Li \&.true
converts to the string
.Li \&".true"
and
.Li \&.false
to
.Li \&".false" ;
integers convert to their decimal representations in the usual way; and
strings are unchanged.
.Pp
.Nm
defines many variables.  The config file can also use as many other
variables as it wishes for its own convenience, but their names must
begin with
.Sq \&$ .
The built-in variables (those with names not beginning with
.Sq \&$ )
have various semantics.  Some of them provide information from
.Nm
to the config file; others provide ways for the config file to control
.Nm moussh Ap s
behaviour.  Most of the latter are read/write, though some
(particularly those with semantics that do not match the traditional
idea of a variable) are write-only.  The
.Nm moussh Ns -defined
variables, their access (R for read-only, W for write-only, and RW for
read/write), and their semantics, are as follows.  When a variable is
described as equivalent to a particular command-line flag, see the flag
for more; unless otherwise specified, a boolean variable is normally
.Li \&.false
with the command-line flag setting it to
.Li \&.true ,
and with whatever setting results from the command line potentially
overridden by the config file; a string variable is normally
.Li \&"" ,
with the command-line flag setting to the argument given (and, again,
the config file being capable of overriding this); a keyword variable
is (for these purposes) just like a string variable except that its
value is restricted to be one of a small set of strings; an integer
variable is similar, except that command-line arguments for it must be
integers, and config-file setting values are converted to integers.
.Pp
Note that because the config file is processed after the command line,
config-file settings can override command-line settings.  You usually
want to be careful to set variables in the config file only when
they're not already set.
.Pp
Write-only variables that are
.Sq convenience
variables, setting multiple other variables
.Pf ( Li lang
is an example) are write-only because there is no clear way to choose
what value to make them read as when the variables they control are set
to different values.  Write-only variables that manipulate lists of
values (such as
.Li port
or
.Li kex )
are write-only because it would be difficult or impossible to make
reading their values work sanely; the config-file language does not
have any direct way to represent lists.
.Bl -tag -width indent
.It Li opmode No (R)
Contains the operating mode, as a keyword, one of:
.Li client ,
.Li keygen ,
.Li setpass ,
.Li setcomm ,
.Li agent ,
.Li add ,
.Li list ,
.Li delete ,
.Li delete-all ,
.Li server ,
.Li import ,
.Li export ,
.Li fingerprint ,
.Li share-kill ,
or
.Li share-stop .
(The last three exist because
.Fl kfp ,
.Fl share-kill ,
and
.Fl share-stop
are implemented as operation modes.)
.It Li host No (R)
Contains the remote host name, as specified by the command line, if
there is one (it's unset if not).  This is usually set in client mode
and unset in the other modes, but it can be unset even in client mode,
such as if
.Fl nohost
is used but no host name is specified after it.
.It Li host-type No (R)
Contains a keyword describing how
.Li host
got its value, one of
.Ql none
.Pf ( Li host
is not set),
.Ql argv
.Pf ( Li host
was set from
.Li argv[0] ) ,
.Ql bare
.Pf ( Li host
was set by an argument appearing with no flag, when no host was
specified), or
.Ql flag
.Pf ( Li host
was set by the
.Fl host
flag).
.It Li local-ip No (R)
The IP address of the local end of the network connection, as a string.
Set only in modes for which there is a connection.
.It Li local-port No (R)
The port number of the local end of the network connection, as an
integer.  Set only in modes for which there is a connection.
.It Li remote-ip No (R)
The IP address of the remote end of the network connection, as a
string.  Set only in modes for which there is a connection.
.It Li remote-port No (R)
The port number of the remote end of the network connection, as an
integer.  Set only in modes for which there is a connection.
.It Li remote-version-entire No (R)
The remote end's version string, as a single string.  Set only in modes
for which there is a connection.
.It Li remote-version-proto No (R)
The protocol version portion of the remote end's version string.  Set
only in modes for which there is a connection.
.It Li remote-version-sw No (R)
The software version portion of the remote end's version string.  Set
only in modes for which there is a connection.
.It Li remote-version-comment No (R)
The comment portion of the remote end's version string.  Set only in
modes for which there is a connection.
.It Li connect-to No (RW)
In client mode, the host or address to connect to, as a string.  If
this is not set,
.Li host Ap s
value is used.  No meaning in other modes.
.It Li chroot No (RW)
In server mode, a boolean which indicates whether the server should
.Xr chroot 2
to the user's home directory.  When this is done, it is done
immediately before switching to the user's UID.  It also is done only
when the server is running as root.  It is done before loading the
user's individual config file (which is always looked for in
.Pa \&.moussh/config
relative to the user's home directory).
.It Li agent-dir No (RW)
String.  This specifies the directory in which authentication-agent
sockets are to be created.  When this variable is set, the string must
refer to something that either already exists and is a directory, or
does not exist and can be created with
.Xr mkdir 2 .
When this variable is not set,
.Nm
constructs a directory name in
.Pa /tmp
based on the current user-ID (see
.Xr getuid 2 ) ,
adding a conflict-resolution letter if necessary until it finds
something that either is a directory owned by the current user or does
not exist but can be created with
.Xr mkdir 2 ,
or until it's tried all 52 different conflict-resolution letters with
no success.
.Pp
Note that when the variable is set, there is no check that the
directory is owned by the current user.  Note also that there is no
check on any directory's permissions; this is deliberate, to permit an
authentication agent to be shared deliberately.
.Pp
When
.Nm
creates an agent directory, it does so by simply calling
.Xr mkdir 2 ,
with 0700 as the second argument.
.Pp
If the variable is set and refers to something that does not pass the
test above, or if the variable is not set and
.Nm
is unable to find or create a suitable directory, agent setup fails:
when running as an agent,
.Nm
does not start, and when running as a server and trying to set up agent
forwarding, the agent forwarding request is rejected.
.It Li auto-bg No (RW)
Boolean, equivalent to the
.Fl f
command-line flag.
.It Li use-syslog No (RW)
Boolean, equivalent to the
.Fl syslog
command-line flag (and complementary to the
.Fl nosyslog
command-line flag).
.It Li do-nothing No (RW)
Boolean, equvialent to the
.Fl nothing
command-line flag.
.It Li just-die No (RW)
Boolena, equivalent to the
.Fl just-die
command-line flag.
.It Li never-auth No (RW)
Boolean, equivalent to the
.Fl neverauth
command-line flag.
.It Li no-agent No (RW)
Boolean, equivalent to the
.Fl noagent
command-line flag.
.It Li no-input No (RW)
Boolean, equivalent to the
.Fl n
command-line flag.
.It Li one-conn No (RW)
Boolean, equivalent to the
.Fl oneconn
command-line flag.
.It Li share-client No (RW)
Boolean.  Setting this true invokes shared-connection client mode.  The
.Fl share-client
command-line flag sets this true and sets
.Li share-path
to the argument string.
.It Li share-server No (RW)
Boolean.  Setting this true invokes shared-connection server mode.  The
.Fl share-server
command-line flag sets this true and sets
.Li share-path
to the argument string.
.It Li auto-share-timeout No (RW)
This integer variable actually controls the timeout value described for
.Fl auto-share-timeout .
It defaults to \&-1; the command-line flag simply sets the variable.
.It Li share-path No (RW)
This string variable holds the rendezvous path for connection-sharing
modes.  The same variable is used for all modes; when connection
sharing is specified by a command-line flag, the rendezvous path is
stored in this variable.
.It Li auto-share No (RW)
Boolean.  Setting this true invokes auto-connection-sharing (see the
.Sx CONNECTION SHARING
section for more); the
.Fl auto-share
command-line flag does this (and also sets the
.Li share-path
and
.Li auto-share-path
variables).  To actually usefully use auto-shared mode from the config
file, you need to set
.Li auto-share
to
.Li \&.true
and also set appropriate strings in
.Li share-path
and
.Li auto-share-path .
.It Li auto-share-path No (RW)
When auto-shared mode is in use by the client, this is where the lock
path described in the
.Sx CONNECTION SHARING
section comes from.  This variable is not set by default; the
.Fl auto-share
command-line flag sets this, among other things.
.It Li ignore-kill No (RW)
Boolean.  Used only in shared-server mode (either auto-shared or
manually specified).  Defaults false; when set true (which cannot be
done except by the config file), the sharing server ignores kill
requests (see the
.Fl share-kill
option).
.It Li ignore-stop No (RW)
Boolean.  Used only in shared-server mode (either auto-shared or
manually specified).  Defaults false; when set true (which cannot be
done except by the config file), the sharing server ignores stop
requests (see the
.Fl share-stop
option).
.It Li ignore-drop No (RW)
Boolean.  Used only in shared-server mode (either auto-shared or
manually specified).  Defaults false; when set true (which cannot be
done except by the config file), the sharing server ignores drop
requests (see the
.Fl share-drop
option).
.It Li user No (RW)
String.  Equivalent to the
.Fl user
command-line flag (or its other spellings) for most modes; for server
mode, this is set when an authentication request is received (before
the authentication exchange occurs).  See also the
.Li user-exists
and
.Li user-authenticated
booleans.
.It Li user-exists No (RO)
Boolean.  Set in server mode to indicate whether a local user exists
with a name matching the
.Li user
variable's value.
.It Li user-authenticated No (RO)
Boolean.  Set in server mode to indicate whether a local user has
authenticated.
.Pf ( Li user
is set before authentication occurs.)
.It Li user-uid No (RO)
Intever.  Set in server mode to the UID of the user for whom
authentication is being attempted.  This differs from
.Li uid
in that it is set when the username is received, before authentication
occurs, whereas
.Li uid
is set only after authentication succeeds.  Also,
.Li user-uid
is set only in server mode when a username has been received, whereas
.Li uid
is always set.
.Pf ( Li user
is set before authentication occurs.)
.It Li auth-alg No (RW)
String.  This is set to the name of the authentication algorithm method
in use when doing authentication in the server.  (This is set only if
the authentication method is about to be tried.  In particular, it is
not set if the requested authentication method is unknown, disabled, or
otherwise unusable.)
.It Li auth-attempts No (RO)
Integer.  In server mode, set to the number of authentication attempts
so far (1 for the first, 2 for the second, etc) for this connection,
regardless of algorithm, username, etc.  Exactly what constitutes an
"attempt" is algorithm-specific, but it will typically be offering a
password, a public key, etc.
.It Li auth-alg-attempts No (RO)
Integer.  In server mode, set to the number of authentication attempts
so far for the current authentication algorithm (1 for the first, 2 for
the second, etc) for this connection.  This is basically an
algorithm-specific version of
.Li auth-attempts .
Each algorithm retains memory of the number of times it has been tried,
even if other algorithms are tried in between.
.It Li lang-c2s No (RW)
String.  Equivalent to the
.Fl lang-c2s
command-line flag.
.It Li lang-s2c No (RW)
String.  Equivalent to the
.Fl lang-s2c
command-line flag.
.It Li host-key-db No (RW)
String.  Equivalent to the
.Fl hkdb
command-line flag.
.It Li no-hk-action No (RW)
Keyword.  Equivalent to the
.Fl nohk
command-line flag.
.It Li bad-hk-action No (RW)
Keyword.  Equivalent to the
.Fl badhk
command-line flag.
.It Li random-pool No (RW)
String.  Equivalent to the
.Fl randfile
command-line flag.
.It Li auth-key-dir No (RW)
String.  Equivalent to the
.Fl authkeydir
command-line flag.
.It Li host-key-dir No (RW)
String.  Equivalent to the
.Fl hostkeydir
command-line flag.
.It Li sshdir No (RW)
String.  Equivalent to the
.Fl sshdir
command-line flag, but note that it affects only uses of the value that
occur after it's set; in particular, setting this in the config file is
too late to cause a config file somewhere else to be read.
.It Li key-type No (RW)
Keyword.  Equivalent to the
.Fl keytype
command-line flag.
.It Li key-size No (RW)
Integer.  Equivalent to the
.Fl keysize
command-line flag.
.It Li key-file-public No (RW)
String.  Equivalent to the
.Fl keyfile-pub
command-line flag.
.It Li key-file-private No (RW)
String.  Equivalent to the
.Fl keyfile-priv
command-line flag.
.It Li key-values No (RW)
Boolean.  Equivalent to the
.Fl keyvalues
command-line flag.
.It Li escape No (RW)
String.  Equivalent to the
.Fl esc
command-line flag.
.It Li passphrase No (RW)
String.  Equivalent to the
.Fl passphrase
command-line flag, but the security exposures are different: there is
no risk of snooping with programs like
.Xr ps 1 ,
but the passphrase must appear in the clear in the config file, and
thus is exposed to anyone who can read the config file.
.It Li comment No (RW)
String.  Equivalent to the
.Fl comment
command-line flag.
.It Li no-interaction No (RW)
Boolean.  Equivalent to the
.Fl nointer
command-line flag.
.It Li list-long No (RW)
Boolean.  Equivalent to the
.Fl long
command-line flag.
.It Li uid No (RO)
The current user-ID, as an integer.  Note that this will often change
in server mode when a user authenticates.
.It Li home No (RW)
This string variable holds the homedir of the user whose name is in the
.Li user
variable in server modes.  While the variable is read-write,
.Nm
never makes any use of its value.  It is provided to the config file
for its own use, and its writability is for convenience rather than to
permit controlling anything with the value.  This variable is set when
.Li user-exists
is set true; if
.Li user-exists
is set false, this variable is not set.
.It Li shell No (RW)
This string variable holds the shell of the user whose name is in the
.Li user
variable in server modes.  While the variable is read-write,
.Nm
never makes any use of its value.  It is provided to the config file
for its own use, and its writability is for convenience rather than to
permit controlling anything with the value.  This variable is set when
.Li user-exists
is set true; if
.Li user-exists
is set false, this variable is not set.
.It Li lang No (W)
Setting this variable is equivalent to setting both
.Li lang-c2s
and
.Li lang-s2c
to the value given.
.It Li key-file No (W)
Setting this variable is equivalent to setting both
.Li key-file-public
and
.Li key-file-private
to the value given.
.It Li fwd No (W)
Setting this variable controls the same forwarding the
.Fl fwd
and
.Fl nofwd
command-line flags do, but in a somewhat different way.  It must be set
to a name suitable for use with the command-line flags, but with a
.Ql \&+
or
.Ql \&-
prepended.  (For example, to enable
.Ql agent
forwarding, as
.Bk -words
.Fl fwd Ar agent
.Ek
would, use
.Bk -words
.Li fwd \&= \&"+agent" . )
.Ek
.It Li port No (W)
Setting this integer variable is equivalent to passing the
.Fl port
command-line flag, except that there is no config-file analog to the
capability provided in server mode by
.Ar address/
prefixes.
.It Li auth-key-file No (W)
Setting this string variable is equivalent to passing the
.Fl authkey
command-line flag.
.It Li alg-kex No (W)
Setting this string variable is equivalent to passing the
.Fl kex
command-line flag.
.It Li alg-hk No (W)
Setting this string variable is equivalent to passing the
.Fl hk
command-line flag.
.It Li alg-enc-c2s
Setting this string variable is equivalent to passing the
.Fl enc-c2s
command-line flag.
.It Li alg-enc-s2c
Setting this string variable is equivalent to passing the
.Fl enc-s2c
command-line flag.
.It Li alg-enc
Setting this string variable is equivalent to passing the
.Fl enc
command-line flag.
.It Li alg-mac-c2s
Setting this string variable is equivalent to passing the
.Fl mac-c2s
command-line flag.
.It Li alg-mac-s2c
Setting this string variable is equivalent to passing the
.Fl mac-s2c
command-line flag.
.It Li alg-mac
Setting this string variable is equivalent to passing the
.Fl mac
command-line flag.
.It Li alg-comp-c2s
Setting this string variable is equivalent to passing the
.Fl comp-c2s
command-line flag.
.It Li alg-comp-s2c
Setting this string variable is equivalent to passing the
.Fl comp-s2c
command-line flag.
.It Li alg-comp
Setting this string variable is equivalent to passing the
.Fl comp
command-line flag.
.It Li alg-ua
Setting this string variable is equivalent to passing the
.Fl ua
command-line flag.
.It Li request-pty
Boolean.  Equivalent to the
.Fl tty
and
.Fl no-tty
command-line flags.
.It Li fork-pause
Integer.  Equivalent to the
.Fl fork-pause
command-line flag.
.It Li no-private
Boolean.  Equivalent to the
.Fl no-private
command-line flag.
.El
.Sh ENVIRONMENT
.Nm
uses, and sometimes sets, various environment variables.  Here is a
full list.
.Bl -tag -width indent
.It Ev DISPLAY
This is read in client mode by the X11 forwarding code to find the
display to forward; in server mode, it is set to the proxy server when
X11 forwarding is being done.
.It Ev HOME
This is read by client mode to provide it to the config file (see the
.Sx CONFIG FILE
section) and is read by all modes in most circumstances to determine
SSHDIR (see the
.Fl sshdir
option in the
.Sx OTHER OPTIONS
section).  It is set by server mode to the home directory of the user
the client authenticated as.
.It Ev SHELL
This is used by the authentication agent when no command is specified.
It is also read by client mode to provide it to the config file (see
the
.Sx CONFIG FILE
section).  It is set by server mode to the shell of the user whom the
client authenticated as.
.It Ev SSH_AGENT
This is set by the authentication agent for the command it runs; the
various agent client operations (both agent-specific operations such as
.Fl add
mode and routine agent use by client-mode operation) read it to find
the agent.  In server mode, this is set to point to the agent proxy
when agent forwarding is being done.
.It Ev SSH_CLIENT
This is not read by
.Nm
at all; it is set by server mode to a string consisting of the
client-side host address, client-side port number, server-side host
address, and server-side port number, all in numeric form, in that
order, separated by single spaces.  For example, if a client on
10.0.0.1 port 12345 connects to a
.Nm
server running on 10.20.30.40 port 22,
.Ev SSH_CLIENT
is set to
.Li \&"10.0.0.1\ 12345\ 10.20.30.40\ 22\&" .
.It Ev SSH_TTY
This is not read by
.Nm
at all; it is set by server mode, when a pseudo-tty is in use (which
it usually will be), to the name of the pseudo-tty device (such as
.Pa /dev/ttyp7 ) .
.It Ev TERM
This is read by client mode to pass the terminal type to the server.
In server mode, this is set to the terminal type sent by the client.
.It Ev USER
This is read by key generation when
.Fl comment
is not provided; it is also read by client mode to provide it to the
config file (see the
.Sx CONFIG FILE
section).  It is set by server mode to the name of the user the client
authenticated as.
.El
.\" .Sh EXAMPLES
.\" .Sh FILES
.\" .Sh SEE ALSO
.Sh STANDARDS
.Nm
is believed to conform to the latest Internet-Drafts from the IETF
SECSH working group (which are in the process of becoming Draft
Standard RFCs at this writing), except as noted.
.Sh HISTORY
The first versions of the Secure Shell protocol were invented by Tatu
Ylonen.  These versions are undocumented except for the source code as
far as I know.  The protocol evolved in the SECSH working group of the
IETF; version 2 is what
.Nm
implements.
.Sh AUTHORS
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .
.\" .Sh DIAGNOSTICS
.\" .Sh ERRORS
.Sh BUGS
There is no way to find out the minimum key sizes for the various key
algorithms.
.Pp
There is currently no support whatsoever for starting subsystems (such
as described in connect-25).
.Pp
There should be a way to have
.Fl delete
take keys from stdin, rather than requiring that they be in files.
.Pp
Config-file variables like
.Li port
and
.Li kex
should be read/write.