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

FreeBSD Manual Pages


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

     autossh --	monitor	and restart ssh	sessions

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

     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.

   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

     2.	     If	autossh	itself receives	a SIGTERM, SIGINT, or a	SIGKILL	sig-
	     nal, it assumes that it was deliberately signalled, and exits af-
	     ter 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,

     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 AU-
	     TOSSH_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 re-
     quires 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".

     -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 di-

	     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 ex-
	     plore using the ServerAliveInterval and ServerAliveCountMax op-
	     tions 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 difference between -f	with autossh, and -f with ssh:
	     when used with autossh ssh	will be	unable to ask for passwords or
	     passphrases. When -f is used, the "starting gate" time (see AU-
	     TOSSH_GATETIME) is	set to 0.

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

     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-

	     If	this variable is set, the logging level	is set to to LOG_DE-
	     BUG, and if the operating system supports it, syslog is set to
	     duplicate log entries to stderr.

	     Specifies the time	to wait	before the first connection test.
	     Thereafter	the general poll time is used (see AUTOSSH_POLL	be-

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

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

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

	     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.

	     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.

	     Append message to echo message sent when testing connections.

	     (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

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

	     Write autossh pid to specified file.

	     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.

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

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

     autossh was written by Carson Harding.

     ssh(1), ssh_config(5,) sshd_config(5,) ssh-add(1),	ssh-agent(1),
     ssh-keygen(1), cygrunsrv(1).

BSD				 Mar 18, 2018				   BSD


Want to link to this manual page? Use this URL:

home | help