ltm rule command MR message
iRule(1) BIG-IP TMSH Manual iRule(1)
MR::message
Returns or sets details in the message routing table.
SYNOPSIS
MR::message clone (CLONE_ID)+
DESCRIPTION
Clones the message a number of times (one for each CLONE_ID) and dispatches each cloned message as ingress.
After the original message has completed the event in which this command is executed, each cloned message
executes the MR_INGRESS iRule event for itself. (CLONE_ID)+ can be one or more strings separated by space.
Protection against infinite loops should be considered! Returns the clone_count, see below, (allowed only at
MR_INGRESS).
MR::message clone -count CLONE_COUNT
DESCRIPTION
Clones the message CLONE_COUNT number of times and dispatches each cloned message as ingress. After the
original message has completed the event in which this command is executed, each cloned message executes the
MR_INGRESS iRule event for itself. Clone IDs of cloned messages will be automatically assigned to:
(clone_count_before + 1), (clone_count_before + 2), ..., (clone_count_before + CLONE_COUNT). Protection
against infinite loops should be considered! Returns the clone_count, see below, (allowed only at
MR_INGRESS).
MR::message clone_count
DESCRIPTION
Returns the number of clones of this message (including the original). Returns 0 if there are no clones of
this message.
MR::message clone_id
DESCRIPTION
Returns the clone id of the current message. Returns empty string for original message.
MR::message clone_id_request
DESCRIPTION
For Requests and Messages: Acts the same as clone_id. For Responses: Returns the clone id of the request this
response belongs to.
MR::message existing_connections_only (BOOLEAN)?
DESCRIPTION
Gets or sets a flag that instructs the MRF to only forward the message using existing connections, and if a
connection to the selected host does not exist then the route will fail.
MR::message new_connection_only (BOOLEAN)?
DESCRIPTION
Gets or sets a flag that instructs the MRF to create a new connection for this message. This connection will
not be reused for other messages but will remain until it expires to receive any responses.
MR::message outgoing_connection_instance_seed (NONNEGATIVE_INTEGER)?
DESCRIPTION
Gets or if been set by this iRule then this seed will be used to generate the connection instance number
instead of this generated by some internal originating connection id. (See MR::connection_instance iRule
command).
MR::message route
DESCRIPTION
Returns the contents of the route stored in the message.
MR::message route none
DESCRIPTION
Clear any route already set in the message.
MR::message route ('peer-selection-mode' | 'selection-mode' | 'mode') ('sequential' | 'seq' | 'ratio') ('peer'
PEER)+
DESCRIPTION
Instructs the route table to route the message to the provided peer or list of peers and a peer-selection-
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 ('peer' PEER)+
DESCRIPTION
Instructs the route table to route the message to the provided peer or list of peers. 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 ((
('config' TRANSPORT_CONFIG
('connection-mode' ('per-peer' | 'per-blade' | 'per-tmm' | 'per-client' |
'per-client-per-blade' | 'per-client-per-tmm' | 'per-peer-alternate-tmm' | 'per-client-alternate-tmm'))?
('max-connections' NONNEGATIVE_INTEGER)?
)?
('virtual' VIRTUAL_SERVER_OBJ
('connection-mode' ('per-peer' | 'per-blade' | 'per-tmm' | 'per-client' |
'per-client-per-blade' | 'per-client-per-tmm' | 'per-peer-alternate-tmm' | 'per-client-alternate-tmm'))?
('max-connections' NONNEGATIVE_INTEGER)?
)?
(('pool' POOL_OBJ) | ('host' HOST))
))+
DESCRIPTION
Instructs the route table to route the message to the provided host or pool using the specified virtual server
or transport config for creating the outgoing connection. If both a transport config and virtual server are
listed, the transport-config will be used for creating a new outgoing connection, but a connection created
with either transport will be usable for connection reuse.
MR::message attempted
DESCRIPTION
Gets the hosts that this message has been routed towards.
MR::message attempted none
DESCRIPTION
Clear any attempted hosts already set in the message.
MR::message attempted ((('virtual' VIRTUAL_SERVER_OBJ)
|
('config' TRANSPORT_CONFIG)) ('host' HOST)
)+
DESCRIPTION
Sets the attempted hosts list. If set before routing the message (during MR_INGRESS or MR_EGRESS) a host will
be selected from the pool that has not already been attempted.
MR::message drop (REASON)?
DESCRIPTION
Drops the current message
MR::message retry_count
DESCRIPTION
Returns the number of attempts to route this message that have occurred.
MR::message status
DESCRIPTION
Returns the status of the routing operation (valid only at MR_EGRESS or MR_FAILED). Possible values are:
"unprocessed"
"route found"
"no route found"
"dropped"
"queue_full"
"no connection"
"connection closing"
"internal error"
"persist key in use"
"standby dropped"
MR::message originator
DESCRIPTION
Returns the transport type, transport name and IP and port of the originator of the message.
MR::message lasthop
DESCRIPTION
Returns the message's lasthop (details of the connection that originated the message).
MR::message nexthop none
DESCRIPTION
Clears the nexthop already set in the message.
MR::message nexthop (HOP)?
DESCRIPTION
Returns the nextop 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.
MR::message pick_host (('peer' PEER) | (('pool' POOL_OBJ) ('config' TRANSPORT_CONFIG)?)) ('carp' CARPKEY)?
DESCRIPTION
MR::message pick_host peer [carp ] MR::message pick_host pool
[config ] [carp ] Returns a host picked from pool specified in the peer. If carp
key is specified, it uses CARP algorithm to compute the host. If no carp key is specified, it uses LB
algorithm of the pool object specified on peer object to return the host. The returned value can be used to
set the host of MR::message route command.
MR::message snat (none | automap | ('address' HOST))
DESCRIPTION
MR::message snat none Source address translation is discarded.
MR::message snat automap Causes the system to assign the configured self IP to the serverside connection(s).
MR::message snat address :[] Causes the system to assign the specified source address to the
serverside connection(s).
DESCRIPTION
RETURN VALUE
VALID DURING
MR_INGRESS MR_EGRESS MR_FAILED
EXAMPLES
# Example 1
when MR_INGRESS {
if {[GENERICMESSAGE::message is_request] != 0} {
set host [MR::message pick_host peer /Common/mypeer]
MR::message route config tcp_tc host $host
}
}
# Example 2
when MR_INGRESS {
if {[GENERICMESSAGE::message is_request] != 0} {
set host [MR::message pick_host peer /Common/mypeer carp [IP::client_addr]]
MR::message route config tcp_tc host $host
}
}
HINTS
SEE ALSO
CHANGE LOG
@BIGIP-11.5.0 --First introduced the command. @BIGIP-11.6.0 --Add MR::message retry_count --Add MR::message
nexthop --Add MR::message lasthop @BIGIP-13.0.0 --Add peer-selection-mode keyword to MR::message route
command. --Add MR::message attempted @BIGIP-13.1.0 --Add connection-mode keyword to MR::message route
command. --Add max-connections keyword to MR::message route command. @BIGIP-14.0.0 --Add MR::message clone
--Add MR::message clone_count --Add MR::message clone_id --Add MR::message clone_id_request --Add MR::message
pick_host --Add MR::message existing_connections_only --Add MR::message outgoing_connection_instance_seed
@BIGIP-14.1.0 --Add MR::message new_connection_only @BIGIP-15.0.0 --Adjust MR::message cloning command
descriptions to be exolicit about when clones execute MR_INGRESS, and clarify the wording.
BIG-IP 2020-06-23 iRule(1)