F5 Logo MyF5
Search
  1. MyF5 Home
  2. BIG-IP Service Provider: SIP Administration
  3. iRule Support
Manual Chapter : iRule Support

Applies To:

Show Versions Show Versions

BIG-IP LTM

  • 17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0, 15.1.9, 15.1.8, 15.1.7, 15.1.6, 15.1.5, 15.1.4, 15.1.3, 15.1.2, 15.1.1, 15.1.0, 15.0.1, 15.0.0, 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0, 14.0.1, 14.0.0
Manual Chapter

iRule Support

iRule Support

Overview: iRule support for SIP administration

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

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

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".
MR::message clone [ <clone_id>* ] OR [ -count <clones_count> ]
Clone the current message(s) and adds to the mr_proxy ingress queue. The command is used in one of two modes:
1. Example: MR::message clone "idexampleA" "idexampleB" "idexampleC": Creates a number of cloned messages as the number of IDs given. In this example, three cloned messages are created with IDs idexampleA, idexampleB, and idexampleC.
2. Example: MR::message -count 3: Creates a given number of clones. The clone IDs will be automatically assigned to the values:
"clone_count_before + 1",
"clone_count_before + 2",...."
<clone_count_before + clones_count>".
In this example three cloned messages are created with IDs "1", "2", and "3".
There can also be a combination of a number of calls, one and later another:
MR::message clone "idexampleA" "idexampleB"
MR::message -count 3
In this example, five cloned messages are created with IDs: "idexampleA", "idexampleB", "3", "4", and "5".
<clone_id> must be a non-empty string. The command returns the clone_count so far.
Contraint 1: Cloning should be allowed to operate only in originating connflow and only in MR_INGRESS. This is because the egress TMM may be on a different TMM and incrementing the clone count may not be detectable by copies of the messages on the ingress TMM. In MR_FAILED it is also not allowed (will issue an error ltm log) because it complicates the implementation, the API, and there is always an alternative to use MR::retry (for example: to send the failed messages to a log server).
Contraint 2: Cloning of cloned messages is not allowed because it complicates the implementation and is unnecessary; all the clones can be made on the original message one after another:
when MR_INGRESS {
if { [MR::message clone_count] == 0}{
MR:message clone "C1" "C2"
MR:message clone "C3" "C4"
} else {
.......
}
}
For this example, protect the clone command with an "if" statement so the cloned messages will not be cloned again. (Only when an original message arrives will it have a clone_count equal to 0).
MR::message clone_count
Returns the number of clones or clones of clones as this message. Returns 0 if there is no cloned message as this message.
Contraint 1: Allowed to operate in MR_INGRESS, MR_EGRESS, and MR_FAILED.
MR::message clone_id
Returns the clone id string, given during creation at the "clone" command. Returns an empty string for original message.
Constraint 1: Allowed to operate in MR_INGRESS, MR_EGRESS, and MR_FAILED.
MR::message clone_id_request
For requests or messages (protocols which are not request/response): acts the same as "clone_id". For responses: returns the ID of the request this response belongs to.
Constraint 1: Allowed to operate in MR_INGRESS, MR_EGRESS, and MR_FAILED.
Constraint 2: The "clone_id_request" iRule will not work correctly for SIP answers (returns an empty string although it is an answer of a cloned request) for two scenarios: 1. The "Insert Via Header" option at the SIP session profile is not enabled. 2. SIP ALG is enabled.
MR::message existing_connections_only <boolean>
Gets or sets a flag that instructs the MRF to only forward the message using existing connections. If a connection to the selected host does not exist then the route will fail.
Allowed to operate in MR_INGRESS, MR_EGRESS, and MR_FAILED.
MR::message outgoing_connection_instance_seed <integer>
Gets or if set by this iRule then this seed is used to generate the connection instance number instead of this generated by some internal originating connection ID. (Refer to the MR::connection_instance command).
If the number received is larger than 32-bit then the 64-bit number will be hashed to a 32-bit number.
Allowed to operate in MR_INGRESS, MR_EGRESS, and MR_FAILED.
route_status attribute
After routing has completed, the route status attribute will contain the status (success or failure) of the routing operation.

SIP iRule Events and Commands

All the SIP/SDP iRule commands specified in the following links are supported.
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.
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.
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information