=======
autossh
=======

Automatically restart SSH sessions and tunnels.

autossh is a program to start an instance of ssh and monitor it,
restarting it as necessary should it die or stop passing traffic. 
autossh monitors connections by sending data through a loop of port
forwardings, and checking that the data returns.  autossh backs off on
the rate of connection attempts when experiencing rapid failures such as
connection refused.  It includes an NT service mode, which works well
for unattended operation as an NT system service using cygrunsrv.

Source homepage:    http://www.harding.motd.ca/autossh/
Source download:    http://www.harding.motd.ca/autossh/autossh-1.4c.tgz
Author:             Carson Harding <harding@motd.ca>
Cygwin maintainer:  Andrew Schulman <andrex@alumni.utexas.net>
License:            simple free license; see COPYING for details.

Please address questions and bug reports to the Cygwin mailing list
<cygwin@cygwin.com>.

-------------------------------------------------------------------------

Notes on autossh's NT service mode:

The Cygwin version of autossh includes an NT service mode.  The NT
service mode is intended to make autossh work well when run as a
system service, using cygrunsrv.  To install autossh as a system
service, first install the cygrunsrv package.  Then create the system
service by running, for example,

cygrunsrv \
  --install autossh \
  --path /usr/bin/autossh \
  --dep tcpip \
  --env "AUTOSSH_NTSERVICE=yes" \
  --args "-F /etc/autossh/ssh_config <target_host>" \
  <... other autossh args or environment settings ...>

You can then start the service either through the Windows service
management console, or by running "cygrunsrv --start autossh".  The service
will also start automatically at boot, unless you specify otherwise in the
installation command above.  For more information about cygrunsrv, see
/usr/share/doc/Cygwin/cygrunsrv.README.

(Note that if you run autossh as a system service, it will run by
default as user SYSTEM, unless you specify otherwise in the arguments
to cygrunsrv.  As a result, you must 'chown SYSTEM' any ssh keys used
by autossh, or ssh will repeatedly fail with a "Permission denied"
error.  You may need to chown SYSTEM other files used by autossh as
well.  If you later need to edit or delete those files, you'll have to
chown them back to another user first.)

Setting AUTOSSH_NTSERVICE=yes in the calling environment as above
isn't required, but it does change autossh's behavior in three useful
ways:

(1) Add an -N flag to each invocation of ssh, thus disabling shell
access.  The idea is that if you're running autossh as a system
service, you're using it to forward ports; it wouldn't make sense to
run a shell session as a system service.  (If you think this reasoning
is wrong, please send a bug report to the author or Cygwin maintainer,
and tell us what you're trying to do.)

(2) Send error messages to stdout.  cygrunsrv redirects stdout and
stderr to the service log file, e.g. /var/log/autossh.log.  So error
messages will go into the log file, which is much easier to peruse or
parse than the Windows error log GUI.  This behavior can be
overridden, however, by setting AUTOSSH_LOGFILE.

(3) Restart ssh even when the old ssh session exits cleanly.  The idea
is that if you're running autossh as a service, you want it to
maintain a connection regardless of why the old one shut down.  For
example, the child ssh process might exit cleanly if the remote host
shuts down temporarily.  In that case you'd want autossh to keep
trying, and reestablish the connection as soon as the remote host is
up again.  To keep autossh from hammering the remote host, you can
adjust AUTOSSH_POLL and AUTOSSH_GATETIME.

Of course, in order to run autossh successfully as a service, you'll
have to give it (and therefore ssh) enough information to make
unattended logins on the remote host: either a running ssh-agent, a
plaintext password, or an unencrypted private key file.  Unattended
logins carry inherent risks, but the risks can be minimized by, for
example, using an account with shell access disabled on the remote
host. For a full discussion of the unattended login problem, see
chapter 11 of "SSH, The Secure Shell: The Definitive Guide", 2nd ed.,
by R. Silverman and D. Barrett.
