autossh — monitor and restart ssh sessions

autossh was written by Carson Harding.

SSHexitsautossh  tries  to  distinguish  the  manner  of  death  of  the  ssh  process  it  is monitoring and act
       appropriately. The rules are:

       1.      If the ssh process exited normally (for example, someone typed "exit" in an interactive session),
               autossh exits rather than restarting;

       2.      If autossh itself receives a SIGTERM, SIGINT, or  a  SIGKILL  signal,  it  assumes  that  it  was
               deliberately signalled, and exits after killing the child ssh process;

       3.      If autossh itself receives a SIGUSR1 signal, it kills the child ssh process and starts a new one;

       4.      Periodically  (by  default  every  10  minutes),  autossh attempts to pass traffic on the monitor
               forwarded port. If this fails, autossh will kill the child ssh process (if it is  still  running)
               and start a new one;

       5.      If the child ssh process dies for any other reason, autossh will attempt to start a new one.

   Startupbehaviour
       If the ssh session fails with an exit status of 1 on the very first try, autossh

       1.      will  assume that there is some problem with syntax or the connection setup, and will exit rather
               than retrying;

       2.      There is a "starting gate" time. If the first ssh process fails within the first few  seconds  of
               being  started, autossh assumes that it never made it "out of the starting gate", and exits. This
               is to handle initial failed authentication, connection, etc. This time is 30 seconds by  default,
               and can be adjusted (see the AUTOSSH_GATETIME environment variable below). If AUTOSSH_GATETIME is
               set  to  0,  then  both  behaviours  are  disabled: there is no "starting gate", and autossh will
               restart even if ssh fails on the first run with an exit status of 1. The "starting gate" time  is
               also set to 0 when the -f flag to autossh is used.

   Continuedfailures
       If  the  ssh  connection  fails  and  attempts to restart it fail in quick succession, autossh will start
       delaying its attempts to restart, gradually backing farther and farther off up to a maximum  interval  of
       the  autossh poll time (usually 10 minutes).  autossh can be "prodded" to retry by signalling it, perhaps
       with SIGHUP ("kill -HUP").

   Connectionsetup
       As connections must be established unattended, the use of autossh requires that some  form  of  automatic
       authentication  be  set  up.  The  use of RSAAuthentication with ssh-agent is the recommended method. The
       example wrapper script attempts to check if there is an agent running for the current environment, and to
       start one if there isn't.

       It cannot be stressed enough that you must make sure ssh works on its  own,  that  you  can  set  up  the
       session you want before you try to run it under autossh

       If  you  are  tunnelling  and using an older version of ssh that does not support the -N flag, you should
       upgrade (your version has security flaws). If you can't upgrade, you may wish to do as rstunnel does, and
       give ssh a command to run, such as "sleep 99999999999".

       The  debian  version  of  autossh  uses  a  wrapper to automatically select a free monitoring port and -M
       overrides AUTOSSH_PORT, see /usr/share/doc/autossh/README.Debian for further information.

autossh  is  a program to start a copy of ssh and monitor it, restarting it as necessary should it die or
       stop passing traffic.

       The original idea and the mechanism were from rstunnel (Reliable SSH Tunnel). With version 1.2 of autossh
       the method changed: autossh uses ssh to construct a loop of ssh forwardings (one from  local  to  remote,
       one  from  remote to local), and then sends test data that it expects to get back. (The idea is thanks to
       Terrence Martin.)

       With version 1.3, a new method is added (thanks to Ron Yorston): a port may be  specified  for  a  remote
       echo  service that will echo back the test data. This avoids the congestion and the aggravation of making
       sure all the port numbers on the remote machine do not collide. The  loop-of-forwardings  method  remains
       available for situations where using an echo service may not be possible.

       There are two particular OpenSSH options that are useful when using autossh : ExitOnForwardFailure=yes on
       the  client  side  to  make  sure forwardings have succeeded when autossh assumes the connection is setup
       properly.  ClientAliveInterval on the server side to make sure the listening  socket  is  closed  on  the
       server side if the connection closes on the client side.

       autossh — monitor and restart ssh sessions

-Mport[:echo_port]
               specifies the base monitoring port to use.  Without  the  echo  port,  this  port  and  the  port
               immediately  above  it  ( port + 1) should be something nothing else is using.  autossh will send
               test data on the base monitoring port, and receive it back on the port above. For example, if you
               specify “-M20000”, autossh will set up forwards so that it can  send  data  on  port  20000  and
               receive it back on 20001.

               Alternatively,  a  port  for a remote echo service may be specified. This should be port 7 if you
               wish to use the standard inetd echo service.  When an echo port is specified, only the  specified
               monitor port is used, and it carries the monitor message in both directions.

               Many  people  disable  the  echo  service,  or  even disable inetd, so check that this service is
               available on the remote machine. Some operating systems allow one to  specify  that  the  service
               only listen on the localhost (loopback interface), which would suffice for this use.

               The  echo  service may also be something more complicated: perhaps a daemon that monitors a group
               of ssh tunnels.

               Setting the monitor port to 0 turns the monitoring function off, and autossh  will  only  restart
               ssh  upon  ssh's exit. For example, if you are using a recent version of OpenSSH, you may wish to
               explore using the ServerAliveInterval and ServerAliveCountMax options to have the SSH client exit
               if it finds itself no longer connected to the server. In many ways this may be a better  solution
               than the monitoring port.

       -f      causes  autossh  to  drop  to  the  background  before  running ssh. The -f flag is stripped from
               arguments passed to ssh. Note that there is a crucial difference between -f with autossh, and  -f
               with  ssh: when used with autossh ssh will be unable to ask for passwords or passphrases. When -f
               is used, the "starting gate" time (see AUTOSSH_GATETIME) is set to 0.

       -V      causes autossh to display its version number and exit.

ssh(1), ssh_config(5,) sshd_config(5,) ssh-add(1), ssh-agent(1), ssh-keygen(1), cygrunsrv(1).

Debian                                            Mar 18, 2018                                        AUTOSSH(1)

autossh [-V] [-Mport[:echo_port]] [-f] [SSH_OPTIONS]