1AUTOSSH(1) BSD General Commands Manual AUTOSSH(1)
2
4 autossh — monitor and restart ssh sessions
5
7 autossh [-V] [-M port[:echo_port]] [-f] [SSH_OPTIONS]
8
10 autossh is a program to start a copy of ssh and monitor it, restarting it
11 as necessary should it die or stop passing traffic.
12 The original idea and the mechanism were from rstunnel (Reliable SSH Tun‐
14 nel). With version 1.2 of autossh the method changed: autossh uses ssh to
15 construct a loop of ssh forwardings (one from local to remote, one from
16 remote to local), and then sends test data that it expects to get back.
17 (The idea is thanks to Terrence Martin.)
18 With version 1.3, a new method is added (thanks to Ron Yorston): a port
20 may be specified for a remote echo service that will echo back the test
21 data. This avoids the congestion and the aggravation of making sure all
22 the port numbers on the remote machine do not collide. The loop-of-for‐
23 wardings method remains available for situations where using an echo ser‐
24 vice may not be possible.
25
27 SSH exits
28 autossh tries to distinguish the manner of death of the ssh process it is
29 monitoring and act appropriately. The rules are:
30 1. If the ssh process exited normally (for example, someone typed
32 "exit" in an interactive session), autossh exits rather than
33 restarting;
34 2. If autossh itself receives a SIGTERM, SIGINT, or a SIGKILL sig‐
36 nal, it assumes that it was deliberately signalled, and exits
37 after killing the child ssh process;
38 3. If autossh itself receives a SIGUSR1 signal, it kills the child
40 ssh process and starts a new one;
41 4. Periodically (by default every 10 minutes), autossh attempts to
43 pass traffic on the monitor forwarded port. If this fails,
44 autossh will kill the child ssh process (if it is still running)
45 and start a new one;
46 5. If the child ssh process dies for any other reason, autossh will
48 attempt to start a new one.
49 Startup behaviour
51 If the ssh session fails with an exit status of 1 on the very first try,
52 autossh
53 1. will assume that there is some problem with syntax or the connec‐
55 tion setup, and will exit rather than retrying;
56 2. There is a "starting gate" time. If the first ssh process fails
58 within the first few seconds of being started, autossh assumes
59 that it never made it "out of the starting gate", and exits. This
60 is to handle initial failed authentication, connection, etc. This
61 time is 30 seconds by default, and can be adjusted (see the
62 AUTOSSH_GATETIME environment variable below). If AUTOSSH_GATETIME
63 is set to 0, then both behaviours are disabled: there is no
64 "starting gate", and autossh will restart even if ssh fails on
65 the first run with an exit status of 1. The "starting gate" time
66 is also set to 0 when the -f flag to autossh is used.
67 Continued failures
69 If the ssh connection fails and attempts to restart it fail in quick suc‐
70 cession, autossh will start delaying its attempts to restart, gradually
71 backing farther and farther off up to a maximum interval of the autossh
72 poll time (usually 10 minutes). autossh can be "prodded" to retry by
73 signalling it, perhaps with SIGHUP ("kill -HUP").
74 Connection setup
76 As connections must be established unattended, the use of autossh
77 requires that some form of automatic authentication be set up. The use of
78 RSAAuthentication with ssh-agent is the recommended method. The example
79 wrapper script attempts to check if there is an agent running for the
80 current environment, and to start one if there isn't.
81 It cannot be stressed enough that you must make sure ssh works on its
83 own, that you can set up the session you want before you try to run it
84 under autossh
85 If you are tunnelling and using an older version of ssh that does not
87 support the -N flag, you should upgrade (your version has security
88 flaws). If you can't upgrade, you may wish to do as rstunnel does, and
89 give ssh a command to run, such as "sleep 99999999999".
90
92 -M port[:echo_port]
93 specifies the base monitoring port to use. Without the echo port,
94 this port and the port immediately above it ( port + 1) should be
95 something nothing else is using. autossh will send test data on
96 the base monitoring port, and receive it back on the port above.
97 For example, if you specify "-M 20000", autossh will set up for‐
98 wards so that it can send data on port 20000 and receive it back
99 on 20001.
100 Alternatively, a port for a remote echo service may be specified.
102 This should be port 7 if you wish to use the standard inetd echo
103 service. When an echo port is specified, only the specified mon‐
104 itor port is used, and it carries the monitor message in both
105 directions.
106 Many people disable the echo service, or even disable inetd, so
108 check that this service is available on the remote machine. Some
109 operating systems allow one to specify that the service only lis‐
110 ten on the localhost (loopback interface), which would suffice
111 for this use.
112 The echo service may also be something more complicated: perhaps
114 a daemon that monitors a group of ssh tunnels.
115 Setting the monitor port to 0 turns the monitoring function off,
117 and autossh will only restart ssh upon ssh's exit. For example,
118 if you are using a recent version of OpenSSH, you may wish to
119 explore using the ServerAliveInterval and ServerAliveCountMax
120 options to have the SSH client exit if it finds itself no longer
121 connected to the server. In many ways this may be a better solu‐
122 tion than the monitoring port.
123 -f causes autossh to drop to the background before running ssh. The
125 -f flag is stripped from arguments passed to ssh. Note that there
126 is a crucial a difference between -f with autossh, and -f with
127 ssh: when used with autossh ssh will be unable to ask for pass‐
128 words or passphrases. When -f is used, the "starting gate" time
129 (see AUTOSSH_GATETIME) is set to 0.
130 -V causes autossh to display its version number and exit.
132
134 Other than the flag to set the connection monitoring port, autossh uses
135 environment variables to control features. ssh seems to be still collect‐
136 ing letters for options, and this seems the easiest way to avoid colli‐
137 sions.
138 AUTOSSH_DEBUG
140 If this variable is set, the logging level is set to to
141 LOG_DEBUG, and if the operating system supports it, syslog is set
142 to duplicate log entries to stderr.
143 AUTOSSH_FIRST_POLL
145 Specifies the time to wait before the first connection test.
146 Thereafter the general poll time is used (see AUTOSSH_POLL
147 below).
148 AUTOSSH_GATETIME
150 Specifies how long ssh must be up before we consider it a suc‐
151 cessful connection. The default is 30 seconds. Note that if
152 AUTOSSH_GATETIME is set to 0, then not only is the gatetime be‐
153 haviour turned off, but autossh also ignores the first run fail‐
154 ure of ssh. This may be useful when running autossh at boot.
155 AUTOSSH_LOGLEVEL
157 Specifies the log level, corresponding to the levels used by sys‐
158 log; so 0-7 with 7 being the chattiest.
159 AUTOSSH_LOGFILE
161 Specifies that autossh should use the named log file, rather than
162 syslog.
163 AUTOSSH_MAXLIFETIME
165 Sets the maximum number of seconds that the program should run.
166 Once the number of seconds has been passed, the ssh child will be
167 killed and the program will exit.
168 AUTOSSH_MAXSTART
170 Specifies how many times ssh should be started. A negative number
171 means no limit on the number of times ssh is started. The default
172 value is -1.
173 AUTOSSH_MESSAGE
175 Append message to echo message sent when testing connections.
176 AUTOSSH_NTSERVICE
178 (Cygwin only.) When set to "yes" , autossh sets up to run as an
179 NT service under cygrunsrv. This adds the -N flag for ssh if not
180 already set, sets the log output to stdout, and changes the be‐
181 haviour on ssh exit so that it will restart even on a normal
182 exit.
183 AUTOSSH_PATH
185 Specifies the path to the ssh executable, in case it is different
186 than the path compiled in.
187 AUTOSSH_PIDFILE
189 Write autossh pid to specified file.
190 AUTOSSH_POLL
192 Specifies the connection poll time in seconds; default is 600
193 seconds. Unless AUTOSSH_FIRST_POLL is used, the first poll time
194 will set to match the poll time. If the poll time is less than
195 twice the network timeouts (default 15 seconds) the network time‐
196 outs will be adjusted downward to 1/2 the poll time.
197 AUTOSSH_PORT
199 Sets the connection monitoring port. Mostly in case ssh appropri‐
200 ates -M at some time. But because of this possible use,
201 AUTOSSH_PORT overrides the -M flag. A value of 0 turns the moni‐
202 toring function off.
203
205 autossh was written by Carson Harding.
206
208 ssh(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), cygrunsrv(1).
209BSD Jul 20, 2004 BSD