autossh —
monitor and restart ssh sessions
| autossh |
[-V]
[-M
port[:echo_port]]
[-f]
[SSH_OPTIONS]
|
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.
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.
- 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.
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.
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").
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".
-
-M
port[: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
“-M 20000”,
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.
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_DEBUG- If 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_FIRST_POLL- Specifies the time to wait before the first connection
test. Thereafter the general poll time is used (see AUTOSSH_POLL
below).
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.
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_MAXLIFETIME- Sets the maximum number of seconds that the program should
run. Once the number of seconds has been passed, the ssh child will be
killed and the program will exit.
AUTOSSH_MAXSTART- Specifies how many times ssh should be started. A negative
number means no limit on the number of times ssh is started. The default
value is -1.
AUTOSSH_MESSAGE- Append message to echo message sent when testing
connections.
AUTOSSH_NTSERVICE- (Cygwin only.) When set to "yes" , autossh sets
up to run as an NT service under cygrunsrv. This adds the
-N flag for ssh if not already set, sets the
log output to stdout, and changes the behaviour on ssh exit so that it
will restart even on a normal exit.
AUTOSSH_PATH- Specifies the path to the ssh executable, in case it is
different than the path compiled in.
AUTOSSH_PIDFILE- Write autossh pid to specified file.
AUTOSSH_POLL- Specifies the connection poll time in seconds; default is
600 seconds. Unless AUTOSSH_FIRST_POLL is used, the first poll time will
set to match the poll time. If the poll time is less than twice the
network timeouts (default 15 seconds) the network timeouts will be
adjusted downward to 1/2 the poll time.
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.
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.
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 was written by Carson Harding.
ssh(1),
ssh_config(5,)
sshd_config(5,)
ssh-add(1),
ssh-agent(1),
ssh-keygen(1),
cygrunsrv(1).