An iRule is a powerful and flexible feature within the BIG-IP^® local traffic management system that you can use to manage your network traffic. It allows operators to implement custom behavior beyond the native capabilities of the BIG IP system.

The Generic Message Protocol filter can be configured to divide the input stream (from the transport filter) into messages when it finds an instance of its message terminating string ("\n"). Each message will initially be treated as a response message. If a destination-address is added to the message, it will be changed to a request message.

The first message received after a new connection will be used as the peer name for the connection. A dynamic route for the peer will be added to the peer table using the peer name. The peer name may be set using the GENERICMESSAGE::peer name <name> command. If the peer name has already been set, the first message will be routed as any other message.

The Generic Message Protocol filter maintains a list of pending request messages. When a request message egresses through the filter, the last hop of the originator of the request is added to the pending request list (unless the message has been flagged as a no-response message).

Any message containing a destination address is treated as a request message. If a message does not contain a destination address and a pending request exists, that message is processed as the answer to the pending request. The message's nexthop attribute will be set to the lasthop of the oldest pending message and the pending message will be removed from the pending message list, and forwarded. An iRule command, GENERICMESSAGE::message request_sequence_number, can be used to associate a response to any pending request.

If a message does not contain a destination address and a pending request does not exist, that message will be processed as a request and forwarded for routing.

When a new connection is created, the iRule will need to set the peer name for the connection.

rule gm_rules {
    when CLIENT_ACCEPTED {
        GENERICMESSAGE::peer name "."
        TCP::collect
    }
  
    when SERVER_CONNECTED {
        GENERICMESSAGE::peer name "."
        TCP::collect
    }

rule gm_rules {
    when CLIENT_ACCEPTED {
        GENERICMESSAGE::peer name [IP::remote_addr]
        TCP::collect
    }
  
    when SERVER_CONNECTED {
        GENERICMESSAGE::peer name [IP::remote_addr]
        TCP::collect
    }

tm rule gm_rule {
    when CLIENT_ACCEPTED {
        TCP::respond "What is your name\n"
        TCP::collect
        set capture_name 1
    }
   
    when SERVER_CONNECTED {
        TCP::respond "What do you wish to be called\n"
        TCP::collect
        set capture_name 1
    }
   
    when CLIENT_DATA {
        set lines [split [TCP::payload] "\n"]
        TCP::payload 0 0
        foreach line $lines {
            set line [string trim $line]
            if { [string length $line] > 0 } {
                if { $capture_name == 1 } {
                    GENERICMESSAGE::peer name $line
                    set capture_name 0
                    TCP::respond "Welcome [GENERICMESSAGE::peer name]\n"
                } else {
...
                }
            }
        }
        TCP::release
        TCP::collect
    }
   
    when SERVER_DATA {
        set lines [split [TCP::payload] "\n"]
        TCP::payload 0 0
        foreach line $lines {
            set line [string trim $line]
            if { [string length $line] > 0 } {
                if { $capture_name == 1 } {
                    GENERICMESSAGE::peer name $line
                    set capture_name 0
                    TCP::respond "Welcome [GENERICMESSAGE::peer name]\n"
                } else {
...
                }
            }
        }
        TCP::release
        TCP::collect
    }

The data stream will need to be parsed during CLIENT_DATA and SERVER_DATA iRule events for messages. Once the bytes of a message has been collected, a message object will need to be created and populated.

The GENERICMESSAGE::message create command is used to create and populate a message.

Once a message is created, the GENERICMESSAGE_INGRESS event will be raised and the script author may modify and the message.

Upon completion of the GENERMESSAGE_INGRESS event, the message will be forwarded to the router for routing.

An example script that parses the input stream to create message follows. This example identifies a request message as having the destination address specified at the start of the message separated from the data of the message by a ':'.

when CLIENT_DATA {
        set lines [split [TCP::payload] "\n"]
        TCP::payload 0 0
        foreach line $lines {
            set line [string trim $line]
            if { [string length $line] > 0 } {
                if { $capture_name == 1 } {
...
                } else {
                    set tokens [split $line ":"]
                    if {[llength $tokens] > 1} {
                        GENERICMESSAGE::message create [join [lrange $tokens 1 end] ":"] [lindex $tokens 0]
                    } else {
                        GENERICMESSAGE::message create $line
                    }
                }
            }
        }
        TCP::release
        TCP::collect
    }
   
    when SERVER_DATA {
        set lines [split [TCP::payload] "\n"]
        TCP::payload 0 0
        foreach line $lines {
            set line [string trim $line]
            if { [string length $line] > 0 } {
                if { $capture_name == 1 } {
...
                } else {
                    set tokens [split $line ":"]
                    if {[llength $tokens] > 1} {
                        GENERICMESSAGE::message create [join [lrange $tokens 1 end] ":"] [lindex $tokens 0]
                    } else {
                        GENERICMESSAGE::message create $line
                    }
                }
            }
        }
        TCP::release
        TCP::collect
    }

When a message is received for routing, MRF will raise the MR_INGRESS event. The script author may set the nexthop or route attribute of the message to bypass the normal route table lookup. Response messages may already have the nexthop attribute set but the protocol if a pending request existed in the table.

Upon completion of the MR_INGRESS event, fi the message's nexthop attribute is set, the message will be forwarded to the connection specified in the nexthop attribute.

If the message's route attribute is set, route lookup will be skipped and the route value specified in the message's route attribute will be use to determine the distination host of for the message.

If the message's route attribute is not set, the route lookup will be performed using the message's source and destination address. The message's route attribute will be populated with the selected route's value.

After route selection, a peer from the route value will be selected and a pool member will be selected from the selected peer.

If available connection exists to the selected pool member, the message will be forwarded using that connection.

If an available connection does not exist, a new connection will be created.

The MR_EGRESS event will be raised as the message is leaving the router to be forwarded to the destination.

If a route could not be found or a connection could not be created, a MR_FAILED event will be raised. The script author may attempt to retry routing using the MR::retry command.

When the outgoing message is received by the protocol a GENERICMESSAGE_EGRESS event will be raised. If the protocol's parser is disabled, the script author will need to output the data of the message in the script.

when GENERICMESSAGE_EGRESS {
    TCP::respond "[GENERICMESSAGE::message data]\n"
}