| 1 |
|
| 2 |
autossh Version 1.4 |
| 3 |
------------------- |
| 4 |
|
| 5 |
Building and Installing Autossh |
| 6 |
-------------------------------- |
| 7 |
|
| 8 |
With version 1.4, autossh now uses autoconf. So the build procedure |
| 9 |
is now the well-known: |
| 10 |
|
| 11 |
./configure |
| 12 |
make |
| 13 |
make install |
| 14 |
|
| 15 |
Look at autossh.host for an example wrapper script. |
| 16 |
|
| 17 |
|
| 18 |
Usage |
| 19 |
----- |
| 20 |
autossh [-M <port>[:echo_port]] [-f] [SSH OPTIONS] |
| 21 |
|
| 22 |
Description |
| 23 |
----------- |
| 24 |
|
| 25 |
autossh is a program to start a copy of ssh and monitor it, restarting |
| 26 |
it as necessary should it die or stop passing traffic. |
| 27 |
|
| 28 |
The original idea and the mechanism were from rstunnel (Reliable SSH |
| 29 |
Tunnel). With version 1.2 the method changed: autossh now uses ssh to |
| 30 |
construct a loop of ssh forwardings (one from local to remote, one |
| 31 |
from remote to local), and then sends test data that it expects to get |
| 32 |
back. (The idea is thanks to Terrence Martin.) |
| 33 |
|
| 34 |
With version 1.3, a new method is added (thanks to Ron Yorston): a |
| 35 |
port may be specified for a remote echo service that will echo back |
| 36 |
the test data. This avoids the congestion and the aggravation of |
| 37 |
making sure all the port numbers on the remote machine do not |
| 38 |
collide. The loop-of -forwardings method remains available for |
| 39 |
situations where using an echo service may not be possible. |
| 40 |
|
| 41 |
autossh has only three arguments of its own: |
| 42 |
|
| 43 |
-M <port>[:echo_port], to specify the base monitoring port to use, or |
| 44 |
alternatively, to specify the monitoring port and echo service |
| 45 |
port to use. |
| 46 |
|
| 47 |
When no echo service port is specified, this port and the port |
| 48 |
immediately above it (port# + 1) should be something nothing |
| 49 |
else is using. autossh will send test data on the base monitoring |
| 50 |
port, and receive it back on the port above. For example, if you |
| 51 |
specify "-M 20000", autossh will set up forwards so that it can |
| 52 |
send data on port 20000 and receive it back on 20001. |
| 53 |
|
| 54 |
Alternatively a port for a remote echo service may be |
| 55 |
specified. This should be port 7 if you wish to use the |
| 56 |
standard inetd echo service. When an echo port is specified, |
| 57 |
only the specified monitor port is used, and it carries the |
| 58 |
monitor message in both directions. |
| 59 |
|
| 60 |
Many people disable the echo service, or even disable inetd, |
| 61 |
so check that this service is available on the remote |
| 62 |
machine. Some operating systems allow one to specify that the |
| 63 |
service only listen on the localhost (loopback interface), |
| 64 |
which would suffice for this use. |
| 65 |
|
| 66 |
The echo service may also be something more complicated: |
| 67 |
perhaps a daemon that monitors a group of ssh tunnels. |
| 68 |
|
| 69 |
-M 0 will turn the monitoring off, and autossh will only |
| 70 |
restart ssh on ssh exit. |
| 71 |
|
| 72 |
For example, if you are using a recent version of OpenSSH, you |
| 73 |
may wish to explore using the ServerAliveInterval and |
| 74 |
ServerAliveCountMax options to have the SSH client exit if it |
| 75 |
finds itself no longer connected to the server. In many ways |
| 76 |
this may be a better solution than the monitoring port. |
| 77 |
|
| 78 |
-f Causes autossh to drop to the background before running ssh. The |
| 79 |
-f flag is stripped from arguments passed to ssh. Note that there |
| 80 |
is a crucial difference between the -f with autossh, and -f |
| 81 |
with ssh: when used with autossh, ssh will be *unable* to ask for |
| 82 |
passwords or passphrases. When -f is used, the "starting gate" |
| 83 |
time (see AUTOSSH_GATETIME) will be set to 0. |
| 84 |
|
| 85 |
-V to have autossh display its version and exit. |
| 86 |
|
| 87 |
All other arguments are passed to ssh. There are a number of |
| 88 |
other settings, but these are all controlled through environment |
| 89 |
variables. ssh seems to be appropriating more and more letters for |
| 90 |
options, and this seems the easiest way to avoid collisions. |
| 91 |
|
| 92 |
autossh tries to distinguish the manner of death of the ssh process it |
| 93 |
is monitoring and act appropriately. The rules are: |
| 94 |
|
| 95 |
- If the ssh process exited normally (for example, someone typed |
| 96 |
"exit" in an interactive session), autossh exits rather than |
| 97 |
restarting; |
| 98 |
- If autossh itself receives a SIGTERM, SIGINT, or a SIGKILL |
| 99 |
signal, it assumes that it was deliberately signalled, and exits |
| 100 |
after killing the child ssh process; |
| 101 |
- If autossh itself receives a SIGUSR1 signal, it will kill the child |
| 102 |
ssh process and start a new one; |
| 103 |
- Periodically (by default every 10 minutes), autossh attempts to pass |
| 104 |
traffic on the monitor forwarded port. If this fails, autossh will |
| 105 |
kill the child ssh process (if it is still running) and start a new |
| 106 |
one; |
| 107 |
- If the child ssh process dies for any other reason, autossh will |
| 108 |
attempt to start a new one. |
| 109 |
|
| 110 |
Startup behaviour: |
| 111 |
|
| 112 |
- If the ssh session fails with an exit status of 1 on the very first |
| 113 |
try, autossh will assume that there is some problem with syntax or |
| 114 |
the connection setup, and will exit rather than retrying; |
| 115 |
- There is now a "starting gate" time. If the first ssh process fails |
| 116 |
within the first few seconds of being started, autossh assumes that |
| 117 |
it never made it "out of the starting gate", and exits. This is to handle |
| 118 |
initial failed authentication, connection, etc. This time is 30 seconds |
| 119 |
by default, and can be adjusted (see the AUTOSSH_GATETIME environment |
| 120 |
variable below). |
| 121 |
- NOTE: If AUTOSSH_GATETIME is set to 0, then BOTH of the above |
| 122 |
behaviours are disabled. This is useful for, for example, |
| 123 |
having autossh start on boot. The "starting gate" time is |
| 124 |
also set to 0 with the -f flag to autossh is used. |
| 125 |
|
| 126 |
Continued failures: |
| 127 |
|
| 128 |
- If the ssh connection fails and attempts to restart it fail in |
| 129 |
quick succession, autossh will start delaying its attempts to |
| 130 |
restart, gradually backing farther and farther off up to a |
| 131 |
maximum interval of the autossh poll time (usually 10 minutes). |
| 132 |
autossh can be "prodded" to retry by signalling it, perhaps with |
| 133 |
SIGHUP ("kill -HUP"). |
| 134 |
|
| 135 |
Connection Setup |
| 136 |
---------------- |
| 137 |
|
| 138 |
As connections must be established unattended, the use of autossh |
| 139 |
requires that some form of automatic authentication be set up. The use |
| 140 |
of RSAAuthentication with ssh-agent is the recommended method. The |
| 141 |
example wrapper script attempts to check if there is an agent running |
| 142 |
for the current environment, and to start one if there isn't. |
| 143 |
|
| 144 |
It cannot be stressed enough that you must make sure ssh works on its |
| 145 |
own, that you can set up the session you want before you try to |
| 146 |
run it under autossh. |
| 147 |
|
| 148 |
If you are tunnelling and using an older version of ssh that does not |
| 149 |
support the -N flag, you should upgrade (your version has security |
| 150 |
flaws). If you can't upgrade, you may wish to do as rstunnel does, and |
| 151 |
give ssh a command to run, such as "sleep 99999999999". |
| 152 |
|
| 153 |
Disabling connection monitoring |
| 154 |
------------------------------- |
| 155 |
|
| 156 |
A monitor port value of "0" ("autossh -M 0") will disable use of |
| 157 |
the monitor ports; autossh will then only react to signals and the |
| 158 |
death of the ssh process. |
| 159 |
|
| 160 |
Environment Variables |
| 161 |
--------------------- |
| 162 |
|
| 163 |
The following environment variables can be set: |
| 164 |
|
| 165 |
AUTOSSH_DEBUG - sets logging level to LOG_DEBUG, and if |
| 166 |
the operating system supports it, sets |
| 167 |
syslog to duplicate log entries to stderr. |
| 168 |
AUTOSSH_FIRST_POLL - time to initial poll (default is as |
| 169 |
AUTOSSH_POLL below). |
| 170 |
AUTOSSH_GATETIME - how long ssh must be up before we consider |
| 171 |
it a successful connection. Default is 30 |
| 172 |
seconds. If set to 0, then this behaviour |
| 173 |
is disabled, and as well, autossh will retry |
| 174 |
even on failure of first attempt to run ssh. |
| 175 |
AUTOSSH_LOGFILE - sets autossh to use the named log file, |
| 176 |
rather than syslog. |
| 177 |
AUTOSSH_LOGLEVEL - log level, they correspond to the levels |
| 178 |
used by syslog; so 0-7 with 7 being the |
| 179 |
chattiest. |
| 180 |
AUTOSSH_MAXLIFETIME - Sets the maximum number of seconds the process |
| 181 |
should live for before killing off the ssh child |
| 182 |
and exiting. |
| 183 |
AUTOSSH_MAXSTART - specifies how many times ssh should be started. |
| 184 |
A negative number means no limit on the number |
| 185 |
of times ssh is started. The default value is -1. |
| 186 |
AUTOSSH_MESSAGE - append a custom message to the echo string (max 64 |
| 187 |
bytes). |
| 188 |
AUTOSSH_NTSERVICE - when set to "yes" , setup autossh to run as an |
| 189 |
NT service under cygrunsrv. This adds the -N flag |
| 190 |
for ssh if not already set, sets the log output |
| 191 |
to stdout, and changes the behaviour on ssh exit |
| 192 |
so that it will restart even on a normal exit. |
| 193 |
AUTOSSH_PATH - path to the ssh executable, in case |
| 194 |
it is different than that compiled in. |
| 195 |
AUTOSSH_PIDFILE - write autossh pid to specified file. |
| 196 |
AUTOSSH_POLL - poll time in seconds; default is 600. |
| 197 |
Changing this will also change the first |
| 198 |
poll time, unless AUTOSSH_FIRST_POLL is |
| 199 |
used to set it to something different. |
| 200 |
If the poll time is less than twice the |
| 201 |
network timeouts (default 15 seconds) the |
| 202 |
network timeouts will be adjusted downward |
| 203 |
to 1/2 the poll time. |
| 204 |
AUTOSSH_PORT - set monitor port. Mostly in case ssh |
| 205 |
appropriates -M at some time. But because |
| 206 |
of this possible use, AUTOSSH_PORT overrides |
| 207 |
the -M flag. |
| 208 |
|
| 209 |
SSH Options |
| 210 |
------------------ |
| 211 |
|
| 212 |
There are two particular OpenSSH options that are useful when using |
| 213 |
autossh: |
| 214 |
|
| 215 |
1) ExitOnForwardFailure=yes on the client side to make sure forwardings |
| 216 |
have succeeded when autossh assumes the connection is setup properly. |
| 217 |
|
| 218 |
2) ClientAliveInterval on the server side to make sure the listening |
| 219 |
socket is closed on the server side if the connection closes on the |
| 220 |
client side. |
| 221 |
|
| 222 |
Logging and Syslog |
| 223 |
------------------ |
| 224 |
|
| 225 |
autossh logs to syslog using the LOG_USER facility. Your syslog may |
| 226 |
have to be configured to accept messages for this facility. This is |
| 227 |
usually done in /etc/syslog.conf. |
| 228 |
|
| 229 |
-- |
| 230 |
Kudos and raspberries to harding [at] motd.ca |