1AUTOSSH(1) BSD General Commands Manual AUTOSSH(1)
2
4 autossh — monitor and restart ssh sessions
5
7 autossh [-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 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_PATH
138 Specifies the path to the ssh executable, in case it is different
139 than the path compiled in.
140 AUTOSSH_POLL
142 Specifies the connection poll time in seconds; default is 600
143 seconds. If the poll time is less than twice the network time‐
144 outs (default 15 seconds) the network timeouts will be adjusted
145 downward to 1/2 the poll time.
146 AUTOSSH_LOGLEVEL
148 Specifies the log level, corresponding to the levels used by sys‐
149 log; so 0-7 with 7 being the chattiest.
150 AUTOSSH_LOGFILE
152 Specifies that autossh should use the named log file, rather than
153 syslog.
154 AUTOSSH_DEBUG
156 If this variable is set, the logging level is set to to
157 LOG_DEBUG, and if the operating system supports it, syslog is set
158 to duplicate log entries to stderr.
159 AUTOSSH_PORT
161 Sets the connection monitoring port. Mostly in case ssh appropri‐
162 ates -M at some time. But because of this possible use,
163 AUTOSSH_PORT overrides the -M flag. A value of 0 turns the moni‐
164 toring function off.
165 AUTOSSH_GATETIME
167 Specifies how long ssh must be up before we consider it a suc‐
168 cessful connection. The default is 30 seconds. Note that if
169 AUTOSSH_GATETIME is set to 0, then not only is the gatetime be‐
170 haviour turned off, but autossh also ignores the first run fail‐
171 ure of ssh. This may be useful when running autossh at boot.
172 AUTOSSH_MAXSTART
174 Specifies how many times ssh should be started. A negative number
175 means no limit on the number of times ssh is started. The default
176 value is -1.
177 AUTOSSH_NTSERVICE
179 (Cygwin only.) When set to "yes" , autossh sets up to run as an
180 NT service under cygrunsrv. This adds the -N flag for ssh if not
181 already set, sets the log output to stdout, and changes the be‐
182 haviour on ssh exit so that it will restart even on a normal
183 exit.
184
186 autossh was written by Carson Harding.
187
189 ssh(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), cygrunsrv(1).
190BSD Jul 20, 2004 BSD