Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AUTOSSH(1)		FreeBSD	General	Commands Manual		    AUTOSSH(1)

NAME
     autossh --	monitor	and restart ssh	sessions

SYNOPSIS
     autossh [-V] [-M port[:echo_port]]	[-f] [SSH_OPTIONS]

DESCRIPTION
     autossh is	a program to start a copy of ssh and monitor it, restarting it
     as	necessary should it die	or stop	passing	traffic.

     The original idea and the mechanism were from rstunnel (Reliable SSH Tun-
     nel). With	version	1.2 of autossh the method changed: autossh 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.)

     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-for-
     wardings method remains available for situations where using an echo ser-
     vice may not be possible.

CONTROLLING SSH
   SSH exits
     autossh tries to distinguish the manner of	death of the ssh process it is
     monitoring	and act	appropriately. The rules are:

     1.	     If	the ssh	process	exited normally	(for example, someone typed
	     "exit" in an interactive session),	autossh	exits rather than
	     restarting;

     2.	     If	autossh	itself receives	a SIGTERM, SIGINT, or a	SIGKILL	sig-
	     nal, it assumes that it was deliberately signalled, and exits
	     after killing the child ssh process;

     3.	     If	autossh	itself receives	a SIGUSR1 signal, it kills the child
	     ssh process and starts a new one;

     4.	     Periodically (by default every 10 minutes), autossh attempts to
	     pass traffic on the monitor forwarded port. If this fails,
	     autossh will kill the child ssh process (if it is still running)
	     and start a new one;

     5.	     If	the child ssh process dies for any other reason, autossh will
	     attempt to	start a	new one.

   Startup behaviour
     If	the ssh	session	fails with an exit status of 1 on the very first try,
     autossh

     1.	     will assume that there is some problem with syntax	or the connec-
	     tion setup, and will exit rather than retrying;

     2.	     There is a	"starting gate"	time. If the first ssh process fails
	     within the	first few seconds of being started, autossh 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 -f flag to autossh is used.

   Continued failures
     If	the ssh	connection fails and attempts to restart it fail in quick suc-
     cession, autossh will start delaying its attempts to restart, gradually
     backing farther and farther off up	to a maximum interval of the autossh
     poll time (usually	10 minutes).  autossh can be "prodded" to retry	by
     signalling	it, perhaps with SIGHUP	("kill -HUP").

   Connection setup
     As	connections must be established	unattended, the	use of autossh
     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.

     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 autossh

     If	you are	tunnelling and using an	older version of ssh that does not
     support the -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".

OPTIONS
     -M	port[:echo_port]
	     specifies the base	monitoring port	to use.	Without	the echo port,
	     this port and the port immediately	above it ( port	+ 1) should be
	     something nothing else is using.  autossh will send test data on
	     the base monitoring port, and receive it back on the port above.
	     For example, if you specify "-M 20000", autossh will set up for-
	     wards so that it can send data on port 20000 and receive it back
	     on	20001.

	     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 mon-
	     itor port is used,	and it carries the monitor message in both
	     directions.

	     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 lis-
	     ten on the	localhost (loopback interface),	which would suffice
	     for this use.

	     The echo service may also be something more complicated: perhaps
	     a daemon that monitors a group of ssh tunnels.

	     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 ServerAliveInterval and 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	solu-
	     tion than the monitoring port.

     -f	     causes autossh to drop to the background before running ssh. The
	     -f	flag is	stripped from arguments	passed to ssh. Note that there
	     is	a crucial a difference between -f with autossh,	and -f with
	     ssh: when used with autossh ssh will be unable to ask for pass-
	     words or passphrases. When	-f is used, the	"starting gate"	time
	     (see AUTOSSH_GATETIME) is set to 0.

     -V	     causes autossh to display its version number and exit.

ENVIRONMENT
     Other than	the flag to set	the connection monitoring port,	autossh	uses
     environment variables to control features.	ssh seems to be	still collect-
     ing letters for options, and this seems the easiest way to	avoid colli-
     sions.

     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.

     AUTOSSH_FIRST_POLL
	     Specifies the time	to wait	before the first connection test.
	     Thereafter	the general poll time is used (see AUTOSSH_POLL
	     below).

     AUTOSSH_GATETIME
	     Specifies how long	ssh must be up before we consider it a suc-
	     cessful connection. The default is	30 seconds. Note that if
	     AUTOSSH_GATETIME is set to	0, then	not only is the	gatetime be-
	     haviour turned off, but autossh also ignores the first run	fail-
	     ure of ssh. This may be useful when running autossh at boot.

     AUTOSSH_LOGLEVEL
	     Specifies the log level, corresponding to the levels used by sys-
	     log; so 0-7 with 7	being the chattiest.

     AUTOSSH_LOGFILE
	     Specifies that autossh should use the named log file, rather than
	     syslog.

     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.

     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.

     AUTOSSH_MESSAGE
	     Append message to echo message sent when testing connections.

     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 be-
	     haviour on	ssh exit so that it will restart even on a normal
	     exit.

     AUTOSSH_PATH
	     Specifies the path	to the ssh executable, in case it is different
	     than the path compiled in.

     AUTOSSH_PIDFILE
	     Write autossh pid to specified file.

     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 time-
	     outs will be adjusted downward to 1/2 the poll time.

     AUTOSSH_PORT
	     Sets the connection monitoring port. Mostly in case ssh appropri-
	     ates -M at	some time. But because of this possible	use,
	     AUTOSSH_PORT overrides the	-M flag. A value of 0 turns the	moni-
	     toring function off.

AUTHOR
     autossh was written by Carson Harding.

SEE ALSO
     ssh(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), cygrunsrv(1).

FreeBSD	11.0			 Jul 20, 2004			  FreeBSD 11.0

NAME | SYNOPSIS | DESCRIPTION | CONTROLLING SSH | OPTIONS | ENVIRONMENT | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=autossh&sektion=1&manpath=FreeBSD+11.0-RELEASE+and+Ports>

home | help