1AUTOSSH(1)                BSD General Commands Manual               AUTOSSH(1)
2

NAME

4     autossh — monitor and restart ssh sessions
5

SYNOPSIS

7     autossh [-V] [-M port[:echo_port]] [-f] [SSH_OPTIONS]
8

DESCRIPTION

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
13     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
19     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

CONTROLLING SSH

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
31     1.      If the ssh process exited normally (for example, someone typed
32             "exit" in an interactive session), autossh exits rather than
33             restarting;
34
35     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
39     3.      If autossh itself receives a SIGUSR1 signal, it kills the child
40             ssh process and starts a new one;
41
42     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
47     5.      If the child ssh process dies for any other reason, autossh will
48             attempt to start a new one.
49
50   Startup behaviour
51     If the ssh session fails with an exit status of 1 on the very first try,
52     autossh
53
54     1.      will assume that there is some problem with syntax or the connec‐
55             tion setup, and will exit rather than retrying;
56
57     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
68   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
75   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
82     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
86     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

OPTIONS

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
101             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
107             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
113             The echo service may also be something more complicated: perhaps
114             a daemon that monitors a group of ssh tunnels.
115
116             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
124     -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 difference between -f with autossh, and -f with ssh:
127             when used with autossh ssh will be unable to ask for passwords or
128             passphrases. When -f is used, the "starting gate" time (see
129             AUTOSSH_GATETIME) is set to 0.
130
131     -V      causes autossh to display its version number and exit.
132

ENVIRONMENT

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
139     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
144     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
149     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
156     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
160     AUTOSSH_LOGFILE
161             Specifies that autossh should use the named log file, rather than
162             syslog.
163
164     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
169     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
174     AUTOSSH_MESSAGE
175             Append message to echo message sent when testing connections.
176
177     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
184     AUTOSSH_PATH
185             Specifies the path to the ssh executable, in case it is different
186             than the path compiled in.
187
188     AUTOSSH_PIDFILE
189             Write autossh pid to specified file.
190
191     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
198     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

ENVIRONMENT

205     There are two particular OpenSSH options that are useful when using
206     autossh : ExitOnForwardFailure=yes on the client side to make sure for‐
207     wardings have succeeded when autossh assumes the connection is setup
208     properly.  ClientAliveInterval on the server side to make sure the lis‐
209     tening socket is closed on the server side if the connection closes on
210     the client side.
211

AUTHOR

213     autossh was written by Carson Harding.
214

SEE ALSO

216     ssh(1), ssh_config(5,) sshd_config(5,) ssh-add(1), ssh-agent(1),
217     ssh-keygen(1), cygrunsrv(1).
218
219BSD                              Mar 18, 2018                              BSD
Impressum