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 priority (MESSAGE_PRIORITY)?
DESCRIPTION
Gets/sets the priority of/for this message. This integer will be one of the factors to rate limit the traffic in MRF.
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.
@BIGIP-16.1.0 --Add MR::message priority
BIG-IP 2022-04-12 iRule(1)