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.
66 Continued failures
68 If the ssh connection fails and attempts to restart it fail in quick suc‐
69 cession, autossh will start delaying its attempts to restart, gradually
70 backing farther and farther off up to a maximum interval of the autossh
71 poll time (usually 10 minutes). autossh can be "prodded" to retry by
72 signalling it, perhaps with SIGHUP ("kill -HUP").
73 Connection setup
75 As connections must be established unattended, the use of autossh
76 requires that some form of automatic authentication be set up. The use of
77 RSAAuthentication with ssh-agent is the recommended method. The example
78 wrapper script attempts to check if there is an agent running for the
79 current environment, and to start one if there isn't.
80 It cannot be stressed enough that you must make sure ssh works on its
82 own, that you can set up the session you want before you try to run it
83 under autossh
84 If you are tunnelling and using an older version of ssh that does not
86 support the -N flag, you should upgrade (your version has security
87 flaws). If you can't upgrade, you may wish to do as rstunnel does, and
88 give ssh a command to run, such as "sleep 99999999999".
89
91 -M port[:echo_port]
92 specifies the base monitoring port to use. Without the echo port,
93 this port and the port immediately above it ( port + 1) should be
94 something nothing else is using. autossh will send test data on
95 the base monitoring port, and receive it back on the port above.
96 For example, if you specify "-M 20000", autossh will set up for‐
97 wards so that it can send data on port 20000 and receive it back
98 on 20001.
99 Alternatively, a port for a remote echo service may be specified.
101 This should be port 7 if you wish to use the standard inetd echo
102 service. When an echo port is specified, only the specified mon‐
103 itor port is used, and it carries the monitor message in both
104 directions.
105 Many people disable the echo service, or even disable inetd, so
107 check that this service is available on the remote machine. Some
108 operating systems allow one to specify that the service only lis‐
109 ten on the localhost (loopback interface), which would suffice
110 for this use.
111 The echo service may also be something more complicated: perhaps
113 a daemon that monitors a group of ssh tunnels.
114 Setting the monitor port to 0 turns the monitoring function off,
116 and autossh will only restart ssh upon ssh's exit. For example,
117 if you are using a recent version of OpenSSH, you may wish to
118 explore using the ServerAliveInterval and ServerAliveCountMax
119 options to have the SSH client exit if it finds itself no longer
120 connected to the server. In many ways this may be a better solu‐
121 tion than the monitoring port.
122 -f causes autossh to drop to the background before running ssh. The
124 -f flag is stripped from arguments passed to ssh. Note that there
125 is a crucial a difference between -f with autossh, and -f with
126 ssh: when used with autossh ssh will be unable to ask for pass‐
127 words or passphrases.
128 -V causes autossh to display its version number and exit.
130
132 Other than the flag to set the connection monitoring port, autossh uses
133 environment variables to control features. ssh seems to be still collect‐
134 ing letters for options, and this seems the easiest way to avoid colli‐
135 sions.
136 AUTOSSH_DEBUG
138 If this variable is set, the logging level is set to to
139 LOG_DEBUG, and if the operating system supports it, syslog is set
140 to duplicate log entries to stderr.
141 AUTOSSH_GATETIME
143 Specifies how long ssh must be up before we consider it a suc‐
144 cessful connection. The default is 30 seconds. Note that if
145 AUTOSSH_GATETIME is set to 0, then not only is the gatetime be‐
146 haviour turned off, but autossh also ignores the first run fail‐
147 ure of ssh. This may be useful when running autossh at boot.
148 AUTOSSH_LOGLEVEL
150 Specifies the log level, corresponding to the levels used by sys‐
151 log; so 0-7 with 7 being the chattiest.
152 AUTOSSH_LOGFILE
154 Specifies that autossh should use the named log file, rather than
155 syslog.
156 AUTOSSH_MAXSTART
158 Specifies how many times ssh should be started. A negative number
159 means no limit on the number of times ssh is started. The default
160 value is -1.
161 AUTOSSH_MESSAGE
163 Append message to echo message sent when testing connections.
164 AUTOSSH_NTSERVICE
166 (Cygwin only.) When set to "yes" , autossh sets up to run as an
167 NT service under cygrunsrv. This adds the -N flag for ssh if not
168 already set, sets the log output to stdout, and changes the be‐
169 haviour on ssh exit so that it will restart even on a normal
170 exit.
171 AUTOSSH_PATH
173 Specifies the path to the ssh executable, in case it is different
174 than the path compiled in.
175 AUTOSSH_PIDFILE
177 Write autossh pid to specified file.
178 AUTOSSH_POLL
180 Specifies the connection poll time in seconds; default is 600
181 seconds. If the poll time is less than twice the network time‐
182 outs (default 15 seconds) the network timeouts will be adjusted
183 downward to 1/2 the poll time.
184 AUTOSSH_FIRST_POLL
186 Specifies the time to wait before the first connection test.
187 Thereafter the general poll time is used (see AUTOSSH_POLL
188 above).
189 AUTOSSH_PORT
191 Sets the connection monitoring port. Mostly in case ssh appropri‐
192 ates -M at some time. But because of this possible use,
193 AUTOSSH_PORT overrides the -M flag. A value of 0 turns the moni‐
194 toring function off.
195
197 autossh was written by Carson Harding.
198
200 ssh(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), cygrunsrv(1).
201BSD Jul 20, 2004 BSD