mirror of
https://github.com/kaboomserver/buildpack.git
synced 2024-07-07 20:14:45 +00:00
293 lines
10 KiB
Groff
293 lines
10 KiB
Groff
.\" -*- nroff -*-
|
|
.\"
|
|
.\" Author: Carson Harding
|
|
.\" Copyright (c) 2002-2018 Carson Harding. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $Id: autossh.1,v 1.24 2018/03/18 19:28:38 harding Exp $
|
|
.\"
|
|
.Dd Mar 18, 2018
|
|
.Dt AUTOSSH 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm autossh
|
|
.Nd monitor and restart ssh sessions
|
|
.Sh SYNOPSIS
|
|
.Nm autossh
|
|
.Op Fl V
|
|
.Op Fl M Ar port[:echo_port]
|
|
.Op Fl f
|
|
.Ar [SSH_OPTIONS]
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a program to start a copy of ssh and monitor it, restarting it as
|
|
necessary should it die or stop passing traffic.
|
|
.Pp
|
|
The original idea and the mechanism were from rstunnel (Reliable SSH
|
|
Tunnel). With version 1.2 of
|
|
.Nm
|
|
the method changed:
|
|
.Nm
|
|
uses ssh to construct a loop of ssh forwardings (one from local to
|
|
remote, one from remote to local), and then sends test data that it
|
|
expects to get back. (The idea is thanks to Terrence Martin.)
|
|
.Pp
|
|
With version 1.3, a new method is added (thanks to Ron Yorston): a
|
|
port may be specified for a remote echo service that will echo back
|
|
the test data. This avoids the congestion and the aggravation of
|
|
making sure all the port numbers on the remote machine do not
|
|
collide. The loop-of-forwardings method remains available for
|
|
situations where using an echo service may not be possible.
|
|
.Pp
|
|
.Sh CONTROLLING SSH
|
|
.Pp
|
|
.Ss SSH exits
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.Nm
|
|
tries to distinguish the manner of death of the ssh process it
|
|
is monitoring and act appropriately. The rules are:
|
|
.Bl -tag -width Ds
|
|
.It 1.
|
|
If the ssh process exited normally (for example, someone typed
|
|
"exit" in an interactive session),
|
|
.Nm
|
|
exits rather than restarting;
|
|
.It 2.
|
|
If
|
|
.Nm
|
|
itself receives a SIGTERM, SIGINT, or a SIGKILL signal, it assumes
|
|
that it was deliberately signalled, and exits after killing the child
|
|
ssh process;
|
|
.It 3.
|
|
If
|
|
.Nm
|
|
itself receives a SIGUSR1 signal, it kills the child ssh process and starts
|
|
a new one;
|
|
.It 4.
|
|
Periodically (by default every 10 minutes),
|
|
.Nm
|
|
attempts to pass traffic on the monitor forwarded port. If this fails,
|
|
.Nm
|
|
will kill the child ssh process (if it is still running) and start a new one;
|
|
.It 5.
|
|
If the child ssh process dies for any other reason,
|
|
.Nm
|
|
will attempt to start a new one.
|
|
.El
|
|
.Pp
|
|
.Ss Startup behaviour
|
|
.Pp
|
|
If the ssh session fails with an exit status of 1 on the very first
|
|
try,
|
|
.Nm
|
|
.Bl -tag -width Ds
|
|
.It 1.
|
|
will assume that there is some problem with syntax or the connection
|
|
setup, and will exit rather than retrying;
|
|
.It 2.
|
|
There is a "starting gate" time. If the first ssh process fails within
|
|
the first few seconds of being started,
|
|
.Nm
|
|
assumes that
|
|
it never made it "out of the starting gate", and exits. This is to handle
|
|
initial failed authentication, connection, etc. This time is 30 seconds
|
|
by default, and can be adjusted (see the AUTOSSH_GATETIME environment
|
|
variable below). If AUTOSSH_GATETIME is set to 0, then both behaviours
|
|
are disabled: there is no "starting gate", and autossh will restart even
|
|
if ssh fails on the first run with an exit status of 1. The "starting gate"
|
|
time is also set to 0 when the
|
|
.Fl f
|
|
flag to autossh is used.
|
|
.El
|
|
.Pp
|
|
.Ss Continued failures
|
|
.Pp
|
|
If the ssh connection fails and attempts to restart it fail in
|
|
quick succession,
|
|
.Nm
|
|
will start delaying its attempts to
|
|
restart, gradually backing farther and farther off up to a
|
|
maximum interval of the
|
|
.Nm
|
|
poll time (usually 10 minutes).
|
|
.Nm
|
|
can be "prodded" to retry by signalling it, perhaps with
|
|
SIGHUP ("kill -HUP").
|
|
.Pp
|
|
.Ss Connection setup
|
|
.Pp
|
|
As connections must be established unattended, the use of
|
|
.Nm
|
|
requires that some form of automatic authentication be set up. The use
|
|
of RSAAuthentication with ssh-agent is the recommended method. The
|
|
example wrapper script attempts to check if there is an agent running
|
|
for the current environment, and to start one if there isn't.
|
|
.Pp
|
|
It cannot be stressed enough that you must make sure ssh works on its
|
|
own, that you can set up the session you want before you try to
|
|
run it under
|
|
.Nm
|
|
.
|
|
.Pp
|
|
If you are tunnelling and using an older version of ssh that does not
|
|
support the
|
|
.Fl N
|
|
flag, you should upgrade (your version has security
|
|
flaws). If you can't upgrade, you may wish to do as rstunnel does, and
|
|
give ssh a command to run, such as "sleep 99999999999".
|
|
.Sh OPTIONS
|
|
.Bl -tag -width Ds
|
|
.It Fl M Ar port[:echo_port]
|
|
specifies the base monitoring port to use. Without the echo port,
|
|
this port and the port
|
|
immediately above it (
|
|
.Ar port
|
|
+ 1) should be something nothing else is
|
|
using.
|
|
.Nm
|
|
will send test data on the base monitoring port, and
|
|
receive it back on the port above. For example, if you specify "-M
|
|
20000",
|
|
.Nm
|
|
will set up forwards so that it can send data on port
|
|
20000 and receive it back on 20001.
|
|
.Pp
|
|
Alternatively, a port for a remote echo service may be specified. This
|
|
should be port 7 if you wish to use the standard inetd echo service.
|
|
When an echo port is specified, only the specified monitor port is
|
|
used, and it carries the monitor message in both directions.
|
|
.Pp
|
|
Many people disable the echo service, or even disable inetd, so check
|
|
that this service is available on the remote machine. Some operating
|
|
systems allow one to specify that the service only listen on the
|
|
localhost (loopback interface), which would suffice for this use.
|
|
.Pp
|
|
The echo service may also be something more complicated: perhaps
|
|
a daemon that monitors a group of ssh tunnels.
|
|
.Pp
|
|
Setting the monitor port to 0 turns the monitoring function off, and
|
|
autossh will only restart ssh upon ssh's exit. For example, if you are
|
|
using a recent version of OpenSSH, you may wish to explore using the
|
|
.Cm ServerAliveInterval
|
|
and
|
|
.Cm ServerAliveCountMax
|
|
options to have the SSH client exit if it finds itself no longer
|
|
connected to the server. In many ways this may be a better solution than
|
|
the monitoring port.
|
|
.It Fl f
|
|
causes autossh to drop to the background before running ssh. The
|
|
.Fl f
|
|
flag is stripped from arguments passed to ssh. Note that there is a crucial
|
|
difference between
|
|
.Fl f
|
|
with autossh, and
|
|
.Fl f
|
|
with ssh: when used with
|
|
.Nm
|
|
ssh will be unable to ask for passwords or passphrases. When
|
|
.Fl f
|
|
is used, the "starting gate" time (see AUTOSSH_GATETIME)
|
|
is set to 0.
|
|
.It Fl V
|
|
causes
|
|
.Nm
|
|
to display its version number and exit.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
Other than the flag to set the connection monitoring port,
|
|
.Nm
|
|
uses environment variables to control features. ssh seems to be
|
|
still collecting letters for options, and this seems the easiest
|
|
way to avoid collisions.
|
|
.Bl -tag -width Ds
|
|
.It Ev AUTOSSH_DEBUG
|
|
If this variable is set, the logging level is set to to LOG_DEBUG, and
|
|
if the operating system supports it, syslog is set to duplicate log
|
|
entries to stderr.
|
|
.It Ev AUTOSSH_FIRST_POLL
|
|
Specifies the time to wait before the first connection test. Thereafter
|
|
the general poll time is used (see AUTOSSH_POLL below).
|
|
.It Ev AUTOSSH_GATETIME
|
|
Specifies how long ssh must be up before we consider it a successful
|
|
connection. The default is 30 seconds. Note that if AUTOSSH_GATETIME
|
|
is set to 0, then not only is the gatetime behaviour turned off, but
|
|
autossh also ignores the first run failure of ssh. This may be useful
|
|
when running autossh at boot.
|
|
.It Ev AUTOSSH_LOGLEVEL
|
|
Specifies the log level, corresponding to the levels used by syslog;
|
|
so 0-7 with 7 being the chattiest.
|
|
.It Ev AUTOSSH_LOGFILE
|
|
Specifies that
|
|
.Nm
|
|
should use the named log file, rather than syslog.
|
|
.It Ev AUTOSSH_MAXLIFETIME
|
|
Sets the maximum number of seconds that the program should run. Once
|
|
the number of seconds has been passed, the ssh child will be killed
|
|
and the program will exit.
|
|
.It Ev AUTOSSH_MAXSTART
|
|
Specifies how many times ssh should be started. A negative number
|
|
means no limit on the number of times ssh is started. The default
|
|
value is -1.
|
|
.It Ev AUTOSSH_MESSAGE
|
|
Append message to echo message sent when testing connections.
|
|
.It Ev AUTOSSH_NTSERVICE
|
|
(Cygwin only.) When set to "yes" , autossh sets up to run as an NT
|
|
service under cygrunsrv. This adds the -N flag for ssh if not already
|
|
set, sets the log output to stdout, and changes the behaviour on ssh
|
|
exit so that it will restart even on a normal exit.
|
|
.It Ev AUTOSSH_PATH
|
|
Specifies the path to the ssh executable, in case it is
|
|
different than the path compiled in.
|
|
.It Ev AUTOSSH_PIDFILE
|
|
Write autossh pid to specified file.
|
|
.It Ev AUTOSSH_POLL
|
|
Specifies the connection poll time in seconds; default is 600 seconds.
|
|
Unless AUTOSSH_FIRST_POLL is used, the first poll time will
|
|
set to match the poll time. If the poll time is less than twice the
|
|
network timeouts (default 15 seconds) the network timeouts will be
|
|
adjusted downward to 1/2 the poll time.
|
|
.It Ev AUTOSSH_PORT
|
|
Sets the connection monitoring port. Mostly in case ssh appropriates
|
|
-M at some time. But because of this possible use, AUTOSSH_PORT
|
|
overrides the -M flag. A value of 0 turns the monitoring function off.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
There are two particular OpenSSH options that are useful when using
|
|
.Nm
|
|
:
|
|
.Fp
|
|
.Cm ExitOnForwardFailure=yes
|
|
on the client side to make sure forwardings
|
|
have succeeded when autossh assumes the connection is setup properly.
|
|
.Fp
|
|
.Cm ClientAliveInterval
|
|
on the server side to make sure the listening
|
|
socket is closed on the server side if the connection closes on the
|
|
client side.
|
|
.El
|
|
.Sh AUTHOR
|
|
.Nm
|
|
was written by Carson Harding.
|
|
.Sh SEE ALSO
|
|
.Xr ssh 1 ,
|
|
.Xr ssh_config 5,
|
|
.Xr sshd_config 5,
|
|
.Xr ssh-add 1 ,
|
|
.Xr ssh-agent 1 ,
|
|
.Xr ssh-keygen 1 ,
|
|
.Xr cygrunsrv 1 .
|