AUTOSSH(1)

NAME
autossh - monitor and restart ssh sessions

SYNOPSIS
autossh [-M port] [SSH_OPTIONS]

DESCRIPTION
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 changes: 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.)

CONTROLLING SSH

  SSH exits

autossh 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.  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;

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

  Startup behaviour

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

  Continued failures

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").

  Connection setup

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

OPTIONS

-M port
    specifies the base monitoring port to use. 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 "-M 20000", autossh will set up forwards so that it can send data on port 20000 and receive it back on 20001.

    Setting the port to 0 turns the monitoring function off, and autossh will only restart ssh upon ssh's exit.

-V  causes autossh to display its version and exit.

ENVIRONMENT
Other than the flag to set the connection monitoring port, autossh uses environment variables to control features. ssh seems to be still collecting letters for options, and this seems the easiest way to avoid collisions.

AUTOSSH_PATH
    Specifies the path to the ssh executable, in case it is different than the path compiled in.

AUTOSSH_POLL
    Specifies the connection poll time in seconds; default is 600 seconds.

AUTOSSH_LOGLEVEL
    Specifies the log level, corresponding to the levels used by syslog; so 0-7 with 7 being the chattiest.

AUTOSSH_LOGFILE
    Specifies that autossh should use the named log file, rather than syslog.

AUTOSSH_DEBUG
    If set this variable is set, the logging level is set to to LOG_DEBUG, and if the operating system supports it, syslog is set to duplicate log entries to stderr.

AUTOSSH_PORT
    Sets the connection monitoring port. Mostly in case ssh appropriates -M at some time. But because of this possible use, AUTOSSH_PORT overrides the -M flag. A value of 0 turns the monitoring function off.

AUTOSSH_GATETIME
    Specifies how long ssh must be up before we consider it a successful connection. The default is 30 seconds. Note that if AUTOSSH_GATETIME is set to 0, then not only is the gatetime behaviour turned off, but autossh also ignores the first run failure of ssh. This may be useful when running autossh at boot.

AUTHOR
autossh was written by Carson Harding.

SEE ALSO
ssh(1), ssh-add(1), ssh-agent(1), ssh-keygen(1).