ltm rule command TCP notify
iRule(1) BIG-IP TMSH Manual iRule(1)
TCP::notify
Sends a message to upper layers of iRule processing.
SYNOPSIS
TCP::notify (request | response | eom)
DESCRIPTION
This command has two uses, which are unrelated to one another:
1. to indicate the end of a message when TCP message-based load-balancing is in effect;
2. to raise the USER_REQUEST or USER_RESPONSE event.
The BIG-IP LTM module supports TCP message-based load-balancing. This is enabled by applying an mblb profile to an LTM
Virtual Server that also has a tcp profile applied. Note that currently (up to and including 11.4.1), the mblb profile can
only be added using tmsh. There is no mechanism for adding it via the Web UI. When an mblb profile is applied, the Virtual
Server provides TCP message-based load-balancing. Normally, TCP is a stream-oriented protocol rather than a message-
oriented protocol (like UDP). When a single TCP connection is used to deliver multiple discreet messages, TMOS must be able
to distinguish individual messages in order to load-balance them. This requires TMOS to reliably find each message
boundary. Unless TMOS has built-in handling code for the underlying application protocol (as it does for Diameter and SIP,
for example), an iRule must be used to indicate to the connection handling code where message boundaries occur.
TCP::notify is used for this purpose. In particular, when TCP::collect is invoked, the system begins collecting incoming
TCP data into a buffer. The data in this buffer may may be accessed using TCP::payload, and it may be removed from the
buffer by invoking TCP::release. When TCP::notify is invoked in the same event as TCP::release, it notifies TMOS that the
data released constitutes a single message. NOTE: it is safest X and strongly recommended X that TCP::notify be called
immediately after TCP::release. For this purpose, TCP::release should also always be invoked with its parameter,
since it is possible for the payload buffer to contain data beyond a single message boundary.
It is necessary to use TCP::notify request if the command is invoked in the client-side context (usually in CLIENT_DATA),
and TCP::notify response if the command is invoked in the server-side context (usually in SERVER_DATA). A compile\/load
error will be raised otherwise. Aside from this, for TCP message-based load-balancing, there is no functional difference
between the request and response sub-commands.
If TCP::notify is used in an iRule not associated with a TCP mblb Virtual Server, the command causes either the
USER_REQUEST or the USER_RESPONSE event to be raised. The event may or may not be raised immediately upon calling
TCP::notify. In particular, the USER_REQUEST event will not be raised until the server-side TCP connection is complete,
and, if there is data waiting to be sent to the server, it will not be raised until those data are sent. Similarly, if
there is data waiting to be sent to the client, the USER_RESPONSE event will not be raised until the data are sent. The
concept of "data waiting to be sent" is very difficult to precisely define; it refers to application data that has finished
client-side processing.
Syntax
TCP::notify [request | response | eom]
TCP::notify request
* Causes the USER_REQUEST event to be raised; or
* Indicates that data released from the payload buffer is a single
message in the clientside context.
TCP::notify response
* Causes the USER_RESPONSE event to be raised; or
* Indicates that data released from the payload buffer is a single
message in the serverside context.
TCP::notify eom
* Introduced in v11.5
* Indicates end of message to the proxy.
RETURN VALUE
None.
VALID DURING
CLIENT_ACCEPTED, CLIENT_CLOSED, CLIENT_DATA, SERVER_CLOSED, SERVER_CONNECTED, SERVER_DATA, SIP_REQUEST, SIP_REQUEST_SEND,
SIP_RESPONSE, STREAM_MATCHED
EXAMPLES
Provide TCP message-based load-balancing for SUPL ILP messages.
In these messages, the first two bytes are an unsigned
integer that provides the message length in octets. The next three
bytes are the ILP message version. The four-bytes following are assumed
to be a session identifier (in ILP, it can be more complicated than
this for the session ID, but this simplifying assumption is made for
the purposes of this example). This code persists messages (rather than
connections) based on the message session ID:
when CLIENT_ACCEPTED {
set message_length 0
set collected_length 0
set at_msg_start 1
TCP::collect
}
when CLIENT_DATA {
set data [TCP::payload]
set collected_length [TCP::payload length]
if { $at_msg_start } {
# it is possible that not enough data have yet been collected to
# extract the message length and session ID. If so, keep collecting
# until there is enough data in the payload buffer
if { $collected_length < 11 } {
TCP::collect
return
}
binary scan $data "S1x3W" message_length slc_session
#log local0. "Start of message, length = $message_length, collected = ($collected_length), slc_session = $slc_session"
# notice that persistence is per-message (because of the mblb profile) rather
# than per-connection, as one would typically find with a tcp VS
persist uie $slc_session
# binary scan does not support unsigned types in the version of
# Tcl used by iRules, so the bitwise-and (&) below casts the extracted
# value to an unsigned two-byte integer
set message_length [expr { $message_length & 0xffff }]
set at_msg_start 0
}
#else {
# log local0. " ... collected = ($collected_length)"
#}
if { $collected_length >= $message_length } {
#log local0. " ... end of message, collected = ($collected_length)"
set at_msg_start 1
TCP::release $message_length
TCP::notify request
#log local0. " ... after purge, length = ([TCP::payload length])"
}
TCP::collect
}
Detach the serverside connection after all the data has
been delivered to the client:
when SERVER_DATA {
log local0.debug "Received SERVER response ... [TCP::payload]"
if { [TCP::payload] ends_with $EOT } {
TCP::notify response
}
TCP::release
TCP::collect
}
when USER_RESPONSE {
LB::detach
log local0.debug "Detaches server connection ... "
if {[TCP::payload length] > 0} {
# %TODO%
# Process additional client requests here ...
}
}
HINTS
SEE ALSO
CHANGE LOG
@BIGIP-9.0.0 --First introduced the command. @BIGIP-11.5.0 --Added "eom" option.
BIG-IP 2022-04-12 iRule(1)