connect¶
Description¶
This command establishes a sideband connection. It is one of several
commands that make up the ability to use sideband
connections from iRules.
Syntax¶
connect [-protocol TCP|UDP] [-myaddr <ip address>] [-myport <port>] [-tos <tos>] [-status <varname>] [-idle <seconds>] [-timeout <milliseconds>] <destination>
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.
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"
}
The BIG-IP API Reference documentation contains community-contributed content. F5 does not monitor or control community code contributions. We make no guarantees or warranties regarding the available code, and it may contain errors, defects, bugs, inaccuracies, or security vulnerabilities. Your access to and use of any code available in the BIG-IP API reference guides is solely at your own risk.