ltm rule command connect

iRule(1)		      BIG-IP TMSH Manual		      iRule(1)



connect
       Establishes a sideband connection.

SYNOPSIS
       connect info (
			   '-protocol'
			   '-myport'
			   '-myaddr'
			   '-local'
			   '-remote'
			   '-tos'
			   '-status'
			   '-idle'
		       )#
		       SIDEBAND_CONNECTION

       connect ((
		       ('-protocol' PROTO)
		       ('-myaddr' IP_ADDR)
		       ('-myport' PORT)
		       ('-timeout' MSEC)
		       ('-idle' SEC)
		       ('-tos' TOS)
		       ('-status' VARIABLE)
		   )#)?
		   (IP_TUPLE | SIDEBAND_VIP)

DESCRIPTION
       This command establishes a sideband connection. It is one of several
       commands that make up the ability to use sideband connections from
       iRules.

RETURN VALUE
       This command opens a sideband connection to the specified destination.

       The connect command returns a connection identifier, assuming the
       connection attempt succeeds. This connection ID is then used to send
       and receive data on the connection as well as close it. If the
       connection attempt fails, a null string is returned. The connect
       command will suspend iRule execution until the connection attempt
       succeeds or fails.

       If you wanted the sideband connection to be encrypted with SSL, you
       should target a virtual server that has a Server SSL profile associated
       to it. Connections from the sideband connection to the sideband VS will
       be unencrypted, but all external traffic will be encrypted with SSL.

       Arguments
	   destination specifies where the traffic should be sent. This can
       either be the name of a virtual server, or an IP address and port, in
       the format "IPv4:port" or "IPv6.port".

       -protocol specifies the IP protocol to be used. The default is TCP, but
       can be explicitly specified. Note than in some versions, the protocol
       may be case-sensitive, and is not validated during rule load time. An
       unknown protocol will trigger a TCL error, and result in the client
       connection being torn down.

       -myaddr specifies the source address for the connection. See the
       caveats below. The default is to let the BIG-IP pick, in which case the
       system will use the closest Self-IP to the destination as the source
       address; if targeting a virtual server that has "address translation"
       disabled, the source address will be the local TMM's internal address
       (in 127.1.0.0/16).

       -myport specifies the source port for the connection. See the caveats
       below. The default is to let the BIG-IP pick. Even if specified, the
       BIG-IP may choose a different source port to ensure return traffic
       disaggregates to the same TMM.

       -timeout $ms is the time in milliseconds to wait to establish the
       connection.

       -idle $sec is the idle timeout to use for the connection; how long to
       leave the connection open if it is unused. The default is 300 seconds.

       -tos $tos specifies the IP TOS to use (see IP::tos)

       -status varname will save the status of the connection attempt into
       varname. The possible status values are:
	   connected - the connection is established (success)
	   timeout - the connection attempt timed out (if a timeout was
       specified)
	   failed - the connection attempt failed

       Note that the connect command may raise a TCL error in some failure
       conditions, e.g. if the BIG-IP is unable to route to the destination.
       If a TCL error is raised, the status variable may be unset.

       myaddr and myport
	   If specifying an IP and port as the destination, the IP address
       specified as -myaddr must be one to which TMM will respond to ARP
       requests (e.g. a self IP address), to ensure that return traffic is
       properly routed back to the BIG-IP.

       If using a VS or VIP as the destination, -myaddr must not be specified,
       as it breaks the functionality (as of version 11.5.0). Instead, omit
       the -myaddr and TMM will use the local TMM's IP address (127.1.x.x) as
       the source address instead.

VALID DURING
EXAMPLES
	# Open a sideband connection with a connection timeout of 100 ms and an idle timeout of 30 seconds
	#   to a local virtual server name sideband_virtual_server
	set conn_id [connect -timeout 100 -idle 30 -status conn_status sideband_virtual_server]

	# Same as above, but use an external host IP:port instead of a virtual server name
	set conn_id [connect -timeout 100 -idle 30 -status conn_status 10.0.0.10:80]


	Example with more complete error handling:
	# Connect to an external host with a connection timeout of 100 ms and an idle timeout of 30 seconds
	# Use catch to handle any errors in the destination virtual server name or external host:port
	# Check if the return value saved to $conn_id is not null
	if {[catch {connect -timeout 1000 -idle 30 -status conn_status sideband_virtual_server} conn_id] == 0 && $conn_id ne ""}{
	    log local0. "Connect returns: $conn_id and conn status: $conn_status"
	} else {
	    log local0. "Connection could not be established to sideband_virtual_server"
	}

HINTS
SEE ALSO
CHANGE LOG
       @BIGIP-11.0.0 --First introduced the command.



BIG-IP				  2017-01-31			      iRule(1)