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						      2020-06-23					     iRule(1)