1
2autossh Version 1.4
3-------------------
4
5Building and Installing Autossh
6--------------------------------
7
8With version 1.4, autossh now uses autoconf. So the build procedure
9is now the well-known:
10
11 ./configure
12 make
13 make install
14
15Look at autossh.host for an example wrapper script.
16
17
18Usage
19-----
20 autossh [-M <port>[:echo_port]] [-f] [SSH OPTIONS]
21
22Description
23-----------
24
25autossh is a program to start a copy of ssh and monitor it, restarting
26it as necessary should it die or stop passing traffic.
27
28The original idea and the mechanism were from rstunnel (Reliable SSH
29Tunnel). With version 1.2 the method changed: autossh now uses ssh to
30construct a loop of ssh forwardings (one from local to remote, one
31from remote to local), and then sends test data that it expects to get
32back. (The idea is thanks to Terrence Martin.)
33
34With version 1.3, a new method is added (thanks to Ron Yorston): a
35port may be specified for a remote echo service that will echo back
36the test data. This avoids the congestion and the aggravation of
37making sure all the port numbers on the remote machine do not
38collide. The loop-of -forwardings method remains available for
39situations where using an echo service may not be possible.
40
41autossh 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
87All other arguments are passed to ssh. There are a number of
88other settings, but these are all controlled through environment
89variables. ssh seems to be appropriating more and more letters for
90options, and this seems the easiest way to avoid collisions.
91
92autossh tries to distinguish the manner of death of the ssh process it
93is 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
110Startup 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
126Continued 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
135Connection Setup
136----------------
137
138As connections must be established unattended, the use of autossh
139requires that some form of automatic authentication be set up. The use
140of RSAAuthentication with ssh-agent is the recommended method. The
141example wrapper script attempts to check if there is an agent running
142for the current environment, and to start one if there isn't.
143
144It cannot be stressed enough that you must make sure ssh works on its
145own, that you can set up the session you want before you try to
146run it under autossh.
147
148If you are tunnelling and using an older version of ssh that does not
149support the -N flag, you should upgrade (your version has security
150flaws). If you can't upgrade, you may wish to do as rstunnel does, and
151give ssh a command to run, such as "sleep 99999999999".
152
153Disabling connection monitoring
154-------------------------------
155
156A monitor port value of "0" ("autossh -M 0") will disable use of
157the monitor ports; autossh will then only react to signals and the
158death of the ssh process.
159
160Environment Variables
161---------------------
162
163The 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
209SSH Options
210------------------
211
212There are two particular OpenSSH options that are useful when using
213autossh:
214
2151) ExitOnForwardFailure=yes on the client side to make sure forwardings
216have succeeded when autossh assumes the connection is setup properly.
217
2182) ClientAliveInterval on the server side to make sure the listening
219socket is closed on the server side if the connection closes on the
220client side.
221
222Logging and Syslog
223------------------
224
225autossh logs to syslog using the LOG_USER facility. Your syslog may
226have to be configured to accept messages for this facility. This is
227usually done in /etc/syslog.conf.
228
229--
230Kudos and raspberries to harding [at] motd.ca
231