Manual Chapter : iRule Support

Applies To:

Show Versions Show Versions

BIG-IP LTM

  • 13.1.5, 13.1.4, 13.1.3, 13.1.1, 13.1.0
Manual Chapter

iRule Support

Overview

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.

MRF SIP provides a set of iRule events which are raised during message processing and routing which allow operators to inspect and edit the SIP messages. They allow operators to forward, route, reject or drop messages.

Events order for SIP REQUEST message:

CLIENT_DATA (or SERVER_DATA) -> SIP_REQUEST -> MR_INGRESS -> MR_EGRESS -> SIP_REQUST_SEND

Events order for SIP RESPONSE message:

SERVER_DATA (or CLIENT_DATA) -> SIP_RESPONSE -> MR_INGRESS -> MR_EGRESS -> SIP_RESPONSE_SEND

MRF iRule Events and Commands

MRF Events

Table 1. MRF Events
Event Description
MR_INGRESS This event is raised when a message is received by the message proxy and before a route lookup occurs. Setting the route for a message will bypass route lookup.
MR_EGRESS This event is raised after the route has been selected and processed and the message is delivered to the mr_proxy for forwarding on the new connflow.
MR_FAILED This event is raised when a message has been returned to the originating flow due to a routing failure.

MRF Commands

Table 2. MRF Events
Command Description
MR::instance Returns the name of the current mr_router instance. The instance name will be the same name as the router profile.
MR::protocol Returns ‘generic, ‘sip’ or ‘diameter’
MR::store <name> … Stores a tcl variable with the mr_message object. This variable will be delivered with the message to the egress connflow. Adding variables does not effect the content of the message
MR::restore [<name> …] Returns adds the stored variables to the current context tcl variable store. If no name is provided, it will add all stored variables.
MR::peer <name>

Returns the content of the named peer. If a local peer has been created with the provided name (using MR::peer <name> ...), the local peer's contents will be returned. If a local peer has not been created with the provided name, the static peer from configuration will be returned. The returned value will be formatted as:

(versions 11.5 - 12.1)

<destination> using <transport>

where:

destination = <destination_type> "<destination_value>"

destination_type = pool | virtual

transport = <transport_type> "<transport_name>"

transport_type = virtual | config

for example:

pool "/Common/default_pool" using config "/Common/sip_udp_tc"

(version 13.0 + )

<transport> <destination>

where:

destination = <destination_type> <destination_value>

destination_type = pool | virtual

transport = <transport_type> <transport_name>

transport_type = virtual | config

for example:

virtual /Common/sip_tcp_vs host [10.2.3.4]%0:5060

MR::peer <name> [[virtual <virtual_name>] OR [config <transport_config_name>]] [[host <host tuple>] OR [pool <pool name>]] Defines a peer to use for routing a message to. The peer may either refer to a named pool or a tuple (IP address, port and route domain iD). When creating a connection to a peer, the parameters of either a virtual server or a transport config object will be used. The peer object will only exist in the current connections connflow. When adding a route (via MR::route add), it will first look for a locally created peer object then for a peer object from the configuration. Once the current connection closes, the local peer object will go away.
MR::peer <name> [[virtual <virtual_name>] OR [config <transport_config_name>]] [[host <host tuple>] OR [pool <pool name>]] ratio <ratio_value> Defines a peer to use for routing a message to. The peer may either refer to a named pool or a tuple (IP address, port and route domain iD). When creating a connection to a peer, the parameters of either a virtual server or a transport config object will be used. The peer object will only exist in the current connections connflow. When adding a route (via MR::route add), it will first look for a locally created peer object then for a peer object from the configuration. Once the current connection closes, the local peer object will go away. Adding the ratio keyword allows setting the ratio of the peer.
MR::message lasthop

Returns the message's lasthop (details of the connection that originated the message). The lasthop is presented as <TMM number>:<FlowID>

for example

0:800000000005

MR::message nexthop

Returns the message's nexthop (details of the connection the message is to be forwarded to). If the new_nexthop parameter is present, a nexthop may be set for the message. The nexthop is formated as <TMM number>:<FlowID>

for example

0:800000000029

MR::message nexthop <new_nexthop> Sets the message's nexthop (details of the connection the message is to be forwarded to). The new_nexthop parameter is present, a nexthop may be set for the message. The nexthop is formated as <TMM number>:<FlowID>
MR::message route

Returns a rendering of the mr_route_value selected for this message. The returned value will be formatted as:

(versions 11.5 - 12.1)

{ <destination> using <transport> [<destination> using <transport>] }

where:

destination = <destination_type> "<destination_value>"

destination_type = pool | virtual

transport = <transport_type> "<transport_name>"

transport_type = virtual | config

for example:

{ pool "/Common/default_pool" using config "/Common/sip_udp_tc" host "[10.2.3.4]%0:5060" using virtual "/Common/sip_tcp_vs" }

(version 13.0 + )

<transport> <destination> [<transport> <destination>]

where:

destination = <destination_type> <destination_value>

destination_type = pool | host

transport = <transport_type> <transport_name>

transport_type = virtual | config

for example:

virtual /Common/sip_tcp_vs host [10.2.3.4]%0:5060 config /Common/sip_udp_tc pool /Common/default_pool

MR::message route peer <peer_name> [peer <peer_name>] Instructs the route table to route the message to the provided peer list. This form of the MR::message route command takes the names of configured peers or dynamic peers created via the MR::peer command.
MR::message route mode <sequential | ratio> peer <peer_name> [peer <peer_name>] Instructs the route table to route the message to the provided peer list. The peer list will have the peer-selection-mode set the the provided mode. This form of the MR::message route command takes the names of configured peers or dynamic peers created via the MR::peer command.
MR::message route [[virtual <virtual_name>] OR [config <config_name>]] [[host <host tuple>] OR [pool <pool_name>]] Instructs the route table to route the message to the provided host or pool.
MR::message attempted

Returns a list of hosts that the message has been routed towards. The returned value will be formatted as:

<transport> <destination> [<transport> <destination>]

where:

destination = <destination_type> host <host_value>

transport = <transport_type> <transport_name>

transport_type = virtual | config

for example:

virtual /Common/sip_tcp_vs host [10.2.3.4]%0:5060 config /Common/sip_udp_tc host [20.3.4.5]%0:5060

MR::message attempted none Clear list of attempted hosts from the message.
MR::message attempted [[virtual <virtual_name>] OR [config <config_name>]] [host <host tuple>] Sets the list of attempted hosts in the message. If set before routing (during MR_INGRESS or MR_FAILED), the hosts in the attempted hosts list will be avoided when performing a lb_pick.
MR::message originator

Returns the transport type, transport name and ip address/port/route domain ID of the originator of the message.

The returned value will be formatted as:

<transport> <destination>

where:

destination = host <host_value>

transport = <transport_type> <transport_name>

transport_type = virtual | config

for example:

virtual /Common/sip_tcp_vs host [10.2.3.4]%0:5060

MR::message drop <reason> Drops the current message
MR::message retry_count Returns the number of attempts to route this message that have occurred.
MR::message status Returns the status of the routing operation (valid only at MR_EGRESS). Possible values are: "unprocessed", "route found", "no route found", "dropped", "queue_full", "no connection", "connection closing", "internal error", "persist key in use", and "standby dropped"
MR::flow_id Returns the flow_id of the current connection (in hex).
MR::transport

Returns the transport type and name of the current connection.

for example

config /Common/sip_udp_tc

MR::prime [config <config_name>] OR [virtual <virtual_name>] [host <host tuple>] OR [pool <pool name>] Initialize a connection to the specified peer (or active poolmembers of the specified pool) using the specified transport.
MR::retry This command is only available during MR_FAILED event. It re-submits the current message for routing to an alternate pool member. If the previous routing attempt set the message's nexthop or route, these fields should be cleared before retrying routing (use "MR::message nexthop none" and "MR::message route none"). The message's route_status will automatically be reset by this command. If the the retry also fails and the retry_count has reached the max_retries setting in the router profile, the message will be given a "Max retries exceeded" route status.
MR::max_retries Returns the configured max_retries of the router instance.
MR::connection_instance

Returns the instance number and number of connections of the current connection within a peer. It will be formatted as "<instance_number> of <max_connections>". For incoming connections, this will return "0 of 1".

for example

0 of 5

MR::connection_mode Returns the connection_mode of the current connection as configured in the peer object. Valid connection_modes are "per-peer, per-blade, per-tmm and per-client". For incoming connections, this will be "per-peer".
Route Status
Table 3. Route Status
Status Description
unprocessed Message has not been submitted for routing yet
route found Route has been found
no route found A route has not been found
dropped The message has been dropped by a MR::message drop command
queue full The message was returned back to the originator because one of the MRF processing queues had reached its configured limit.
no connection The message was routed to a connection which was no longer present.
connection closing The message was queued to be send on a connection which was closed.
internal error The message was unable to be delivered due to an internal error. For example, out of memory.
persist key in use Two messages routed using the same persistence key simultanously tried to create the same persistence record.
standby dropped The message is a mirrored message running on a standby device and was dropped as part of routing to avoid creating an outgoing connection on the standby device.
Max retries exceeded The message was returned to the originator because the latest attempt to retry routing exceeded the configured max retry count.

SIP iRule Events and Commands

All the SIP/SDP iRule commands specified in the following links are supported.

https://clouddocs.f5.com/api/irules/SIP.html

https://clouddocs.f5.com/api/irules/SDP.html

Table 4. SIP iRule events and commands
Command Description Valid SIP Events Valid MR Events
SIP::persist reset Deletes any persistence entry with the current persist key of this message.

SIP_REQUEST

SIP_RESPONSE

SIP_REQUEST_SEND

SIP_RESPONSE_SEND

MR_INGRESS

MR_EGRESS

MR_FAILED

SIP::message Returns the full content of the request or response message.

SIP_REQUEST

SIP_RESPONSE

SIP_REQUEST_SEND

SIP_RESPONSE_SEND

MR_INGRESS

MR_EGRESS

MR_FAILED

SIP::persist [new-persist-key] Returns the persistence key being used for the current message. If new-persist-key is provided, the existing persistence key is replaced. The value of the new-persist-key MUST be one of valid header value in the message. A header name should not be given as the new-persist-key value. SIP_REQUEST MR_INGRESS [For response messages returns EMPTY string]
SIP::route_status Returns the routing status of the current message. Valid status are { "unprocessed", "route found", no route found", "dropped", "queue full", "no connection", "connection closing", "internal error" }. "route found" is based on the SIP RouteTable finding a route. It is not effected by the proxy’s ability to create a connection, so even if the server is not listening on the specified address or marked down, it might still return status as "route found" if the RouteTable is able to find the route.

SIP_REQUEST_SEND

SIP_RESPONSE_SEND

MR_INGRESS

MR_EGRESS

MR_FAILED

SIP::persist replace Route the message using the route table (or iRule command). On completion of routing, add a new persistence record if one does not exist. I an existing persistence record exists, replace the persistence record with the route selected.

SIP_REQUEST

also operates in

SIP_RESPONSE

SIP_REQUEST_SEND

SIP_RESPONSE_SEND

MR_INGRESS

MR_FAILED

also operates in

MR_EGRESS

SIP::persist bypass Route the message using the route table (or iRule command). On completion of routing, add a new persistence record if one does not exist. If an existing persistence record exists, the existing record will not be replaced and the selected route will not be modified.

SIP_REQUEST

also operates in

SIP_RESPONSE

SIP_REQUEST_SEND

SIP_RESPONSE_SEND

MR_INGRESS

MR_FAILED

also operates in

MR_EGRESS

SIP::persist ignore Route the message using the route table (or iRule command). The results of the routing will not be stored in the persistence table.

SIP_REQUEST

also operates in

SIP_RESPONSE

SIP_REQUEST_SEND

SIP_RESPONSE_SEND

MR_INGRESS

MR_FAILED

also operates in

MR_EGRESS

SIP::persist [persist-key] [new-timeout-value] Update the persistence kay and timeout to the new persist-key and new-timeout-value. The persistence key will be used for persistence lookup, add and update. If a persistence value is added or updated, the provided timeout will be used.

SIP_REQUEST

also operates in

SIP_RESPONSE

SIP_REQUEST_SEND

SIP_RESPONSE_SEND

MR_INGRESS

MR_FAILED

also operates in

MR_EGRESS

SIP::persist use Use the current persistence record for routing the message if present. If not present, route the message using the route table. On completion of routing, add a new persistence record if one does not exist. If an existing persistence record exists, repleace the message's selected route with the destination stored in the persistence entry.

SIP_REQUEST

also operates in

SIP_RESPONSE

SIP_REQUEST_SEND

SIP_RESPONSE_SEND

MR_INGRESS

MR_FAILED

also operates in

MR_EGRESS

Persist iRule Example

Get Persist Key
when SIP_REQUEST { log local0. "Persist-key = [SIP::persist]" }
Set Persist Key
when SIP_REQUEST {
  SIP::persist [SIP::header value From]
  log local0. "New Persist-key = [SIP::persist]"
}

SIP::header subcommands

Following subcommands are added to SIP::header commands. The values in [square braces] are optional-fields.

Table 5. SIP::header subcommands
Command Name Description
SIP::header count [header-name] Returns the count of the SIP headers. If "header-name" is specified count the specific headers.
SIP::header exists "header-name" Returns whether SIP header specified by name exists at least once.
SIP::header values [header-name] Returns list of the values of all the instances of SIP header values. If optional argument [header-name] is specified retrieve all values of the specified header-name.
SIP::header at "index" Returns SIP header at "index", index is the Nth line from the SIP header. Returns only the name of the header.
SIP::header replace "header-name" "header-value" [index] Replaces first instance of the header specified by "header-name". New entry is added if not present already. If [index] optional argument is present, replace the header name at [index]th position.
SIP::header names Returns list of all the SIP header names.