=======
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>.

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

Runtime requirements:
  cygwin
  openssh

Build requirements:
  cygport
  gcc
  make
  binutils
  
Build instructions:
  unpack autossh-1.4d-1-src.tgz
    if you use setup to install this src package, it will be
    unpacked under /usr/src automatically
  cd /usr/src
  cygport autossh.cygport all

This will create:
  /usr/src/autossh-1.4d-1.tar.xz
  /usr/src/autossh-1.4d-1-src.tar.xz

Or use 'cygport autossh.cygport prep' to get a patched source
directory.

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

Files included in the binary distribution:

  /usr/bin/autossh.exe
  /usr/share/doc/Cygwin/autossh.README (this file)
  /usr/share/doc/autossh/CHANGES
  /usr/share/doc/autossh/COPYING
  /usr/share/doc/autossh/README
  /usr/share/doc/autossh/README.Cygwin (this file)
  /usr/share/doc/autossh/examples/autossh.host
  /usr/share/doc/autossh/examples/rscreen
  /usr/share/man/man1/autossh.1.gz

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

Cygwin version history:

2014-09-11  1.4d-1:
* New upstream release.
* Update cygport build script to newer style.

1.4c-1:
* New upstream release: minor updates.
* First release for x86_64.

1.4b-1:
- New upstream release: bug fix, and a couple of new options.
- Updated recommendation for autossh + cygrunsrv, below (added '--dep tcpip'
  to cygrunsrv).
- Change to cygport build method.

1.4a-1:
- New upstream release: bug fixes.

1.4-1:
- New upstream release: bug fixes.

1.3-2:
- Clarified the instructions for running autossh as an NT system service 
using cygrunsrv (below).
- Added a note in the man page, pointing the user to this file.

1.3-1:
- New upstream release.  New feature: use a remote echo server instead of
a loop of port forwardings.  See the man page for details.

1.2g-5:
- Patch: fix heap corruption and segfaults caused by freeing memory 
allocated by the cygwin DLL
(http://sourceware.org/ml/cygwin/2005-03/msg00639.html).

1.2g-4:
- Changed to generic build script method for package building.
- Combined all Cygwin-specific docs (README.Cygwin, NEWS.Cygwin, 
autossh.README) into autossh.README (this file).

1.2g-3:
- Revised README.Cygwin to more clearly describe the NT service mode.
- Added /usr/share/doc/autossh/NEWS.Cygwin

1.2g-2:
- Expanded /usr/share/doc/autossh/README.Cygwin, to describe the NT
service mode and how to use it with cygrunsrv.

1.2g-1:
- Initial build.

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

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.
