Debian Codegraph @

README

raw
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