Applies To:
Show Versions
BIG-IP LTM
- 13.1.5, 13.1.4, 13.1.3, 13.1.1, 13.1.0
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
| 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
| 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
| 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
| 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.
| 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. |
