Manual Chapter : Configuration Objects

Applies To:

Show Versions Show Versions

BIG-IP LTM

  • 13.0.1, 13.0.0
Manual Chapter

Configuration Objects

MRF

The Message Routing Framework (MRF) is an extension to the BIG-IP® system to support routing of messages between connections. MRF is a protocol independent framework that is used to build protocol specific routing systems. Currently three protocol implementation of MRF are supported by the BIG-IP system: DIAMETER, SIP and Generic Message.

Virtual Server

A virtual server is a traffic-management object on the BIG-IP® system that is represented by an IP address and a service. Clients on an external network can send application traffic to a virtual server, which then directs the traffic according to configuration instructions.

All virtuals sharing the same router profile will share the same router instance. This means that they will be able to use connections created by traffic on other virtuals. They will also be able to route message between each other.

The virtual server configuration contains a destination address and mask which specifies what IP addresses and port the virtual server will listen for incoming packets. The virtual server object also contains a source address allowing it to limit packets to those packets that originate from a range of devices.

The behavior of a virtual server is determined by the set of profiles attached to the virtual server. In addition, the behavior of a virtual can further be extended by assigning iRules to the virtual. Furthermore, the transport-config object is used to define the outgoing connection, for example source address translation, and translation modes of the virtual server. Note, the virtual server configuration (e.g. pool and persistence profile) used to select a destination is not used in MRF.

Transport Config

A transport config defines the parameters of a new outgoing connection. It is a subset of a virtual server used to define parameters of an outgoing connection. This includes the profiles, iRules and source-address-translation settings.

Since a transport-config may be used in a route that may be used in multiple router instances, the router profile is not defined in a transport-config object. Instead, an outgoing connection inherits the router profile of the router instance that creates an outgoing connection.

Transport Config Attributes

Table 1. Transport Config Attributes
Attribute Description Default
ip-protocol Specifies the ip protocol. This will be automatically set based on the transport profile added. This value is read-only. none
source-port Specifies the source port to be used for the connection being created. If the source-port is zero, an ephemeral port will be used. 0
profiles The transport protocol and the protocol-specific profile associated with this outgoing connection.  
source-address-translation Specifies the source-address-translation type and the pool.  
rules List of iRules associated with this outgoing connection. none
Source Address Translation
Table 2. Transport Config Attributes
Sub-Attribute Description Default
type Specifies the type of source address translation to perform automap
pool Specifies the name of the snap pool none
Source Address Translation Types
Table 3. Source Address Translation Types
Type Description
automap The self-ip of the outgoing vlan will be used as the source address of the outgoing connection.
snat A source address will be selected from the named snat pool
none No source address translation will be performed.

Route

The route object is used to determine the best route to use for forwarding a message. Each route contains a source and destination address fields that are matched against the source and destination address metadata fields of the message. If the route's source or destination address field is empty, it is considered a wildcard and all values of the message's corresponding address field will be considered matching. An actual match of the contents of an address field is scored higher than a wildcard match.

The route object also contains a list of peers and a peer-selection-mode to specify how peers in the peer list are selected.

Generic Message Route Object

ltm message-routing generic route <name> {
   destination-address <string>
   source-address <string>
   peer-selection-mode <ratio/sequential>
   peers {
      <peers>
   }
}
Attribute
Table 4. Generic Message Route Object Attributes
Attribute Description Default
destination-address The destination-address of the route. This is often the name of the receipent of a message none
source-address The source-address of the route. This is often the name of the originator of a message none
peer-selection-mode

This specifies the method to select a peer from the provided list of peers. Possible values are:

  • sequential: The first peer in the list of peers is selected. If the message is retried, the next peer in the list will be used.
  • ratio: The probability of a peer from the list being selected will be based on the relative ratio values of each peer.
sequential
peers Provides the list of peers used by this route none
Example
# default route - source and destination address are wildcard
ltm message-routing generic route default_route {
    peer-selection-mode sequential
    peers { default_peer, backup_peer }
}
  
ltm message-routing generic route forwarding_route {
    destination-address help
    peers { forwarding_peer }
}
  
ltm message-routing generic route bad_route {
    source-address annoying_user
    peer-selection-mode ratio
    peers { default_peer, blackhole_peer }
}

Route Table

Generic message maintains a route table per router instance. The route table contains three types of routes, static routes from configuration, dynamic routes auto generated from peer names per connection and dynamic routes added by an iRule.

The route table will use the source and destination address of a message to determine the best matching route to use for forwarding the message. The source and destination attributes of the route will be matched against the source and destination addresses of the route to generate a score. The highest scoring route is used for forwarding the message.

Table 5. Generic Message Route Table
Matching Fields Score
Both src_addr + dst_addr matches 3
dst_addr matches 2
src_addr matches 1
no attributes match 0

Static Route

Generic message allows for static routes to be loaded from configuration. A static route contains a list of peers, where each peer contains a list transport-config and a pool.

Pool

A standard LTM pool is used to list a set of devices that messages may be routed towards.

ltm pool my_default_pool members { 10.1.2.1:1234, 10.1.2.2:1234, 10.1.2.3:1234 }
ltm pool my_backup_pool members { 10.1.2.4:1234, 10.1.2.5:1234, 10.1.2.6:1234 }
ltm pool my_empty_pool members { }

Peer Object

A peer object is used to define a set of hosts and the the method to connect with them. Peers are used to create static routes. The peer structure is protocol independent while each protocol implementation of MRF will define its own static route structure. Furthermore, a peer object can be used to configure MRF to create outgoing connections to members of a pool, at startup, and to retry creating connection at a configurable interval (in milliseconds). In summary, peers contain a pool, a transport-config and connection distribution settings.

ltm message-routing generic peer default_peer {
   transport-config my_snat_tc
   pool my_default_pool
   connection-mode per-tmm
   number-connections 2
   auto-initialization enabled
   auto-initialization-interval 1000
}
Transport-config Not Defined

If a transport-config is not defined, the outgoing connection will use the settings of the incoming connection for creating the outgoing connection.

ltm message-routing generic peer backup_peer {
   pool my_backup_pool
}
Message Forwarding

If a pool is not defined, the outgoing connection will use the destination (local address) of the incoming connection as the destination (remote address) of the outgoing connection. This is how to configure message forwarding.

ltm message-routing generic peer forwarding_peer {
   transport-config my_nosnat_tc
}
Black Hole Route

If a pool with no pool members is used, the message routed to that peer will fail routing. This can be used as a method to create a black hole route.

ltm message-routing generic peer blackhole_peer {
   ratio 3
   pool my_empty_pool
}
Peer name

Each connection is assigned a peer name. This peer name must be set via the GENERICMESSAGE::peer name iRule command. Once the peer name has been sent, the connection is able to receive and forward messages.

The peer name is used to add a dynamic route to the route table. It is also used to set the source address of each message.

Peer Attributes
Table 6. Generic Message Route Table
Attribute Description Default
pool Pool associated with the peer. If only one peer, then configure a single-member pool. If none, the message will be forwarded to the destination address and port of the originating connection. none
transport-config Specifies the transport-config that defines the parameters of the outgoing connection. If none, the parameters of the originating connection will be used to create the outgoing connection. none
connection-mode

Specifies how the number of connections per peer are to be limited as follows: per-peer, per-blade, per-tmm, per-client.

If a transport config is not specified, the attributes of the originating connection of the message being routed will be used to create the outgoing connection. In this case, the connection-mode in the peer object will be ignored.

per-peer
number-connections

Specifies the number of connections between the BIG-IP® system and a peer.

If a transport config is not specified, the attributes of the originating connection of the message being routed will be used to create the outgoing connection. In this case, the number-connections in the peer object will be ignored.

1
ratio Used to designate the ratio of this peer when used within a route with a peer-selection-mode of ratio. 1
auto-initialization If enabled, the BIG-IP® system will automatically create outbound connections to the active pool members in the specified pool using the configuration of the specified transport-config. For auto-initialization to attempt to create a connection, the peer must be included in a route that is attached to a router instance. For each router instance that the peer is contained in, a connection will be initiated. The auto-initialization logic will verify at a configurable interval if the a connection exists between the BIG-IP system and the pool members of the pool. If a connection does not exist, it will attempt to reestablish one. disabled
auto-initialization-interval Specifies the interval (in milliseconds) that attempts to initiate a connection occur. Valid ranges are from 500ms to 65535ms 5000ms

Connection Modes

Per Peer

A BIG-IP® system will make just one connection to a peer. This means that only one TMM is connected to each Peer. While this connection mode uses fewer connections it will introduce latency. This will happen when messages are disaggregated to the wrong TMM and must be forwarder. The following diagram provides additional detail.

Optimum scenario

Optimum scenario

  1. Message arrives on a Virtual Server (VS)
  2. Message is disaggregated to TMM-0
  3. TMM-0 is connected to the correct server so the message is sent
Performance impacted scenario

Performance impacted scenario

  1. Message arrives on a Virtual Server (VS)
  2. Message is disaggregated to TMM-1
  3. TMM-1 is not connected to Server 1 so message must be forwarded to the correct TMM. This will introduce latency.
  4. TMM-0 is send message to Server 1
Per TMM

A BIG-IP® system will make a connection from every TMM to the same peer. This means a machine with 8 cores will have 8 connections per peer. While this increases the number of active connections, it also improves performance because there is no need to forward messages between TMMs.

Every TMM is connected to every peer which     decreases latency but increases the number of connections

Every TMM is connected to every peer which decreases latency but increases the number of connections

  1. Message arrives on a Virtual Server (VS)
  2. Message is disaggregated to TMM-0
  3. TMM-0 is connected to the correct server so the message is sent
  4. Second message arrives
  5. Message is disaggregated to TMM-1
  6. TMM-1 is connected to the requested server so the message can be sent directly
Per Blade

A BIG-IP® system creates one connection per blade to each peer. This provides a balanced performance approach between the per peer connection mode (only one connection) and a per tmm connection mode (a connection from each TMM). This mode only makes sense for a hardware chassis with multiple blades.

Each blade will make a single connection to     each peer.

Each blade will make a single connection to each peer.

  1. Message arrives on Blade 0
  2. Blade 0 opens a connection to Server 1 and forwards the message
  3. Second message arrives
  4. Blade 1 opens a connection to server 1 and forwards the message
Note: A connection will not be opened to Server 2 until a message targeted at that server arrives.
Per Client

A BIG-IP® system will create a new outgoing connection for each client. Note, clients do not share connections.

Connections will be created for each client.

Connections will be created for each client.

  1. Client 1 message arrives on a Virtual Server (VS)
  2. Message is disaggregated to TMM-0
  3. TMM-0 connects to Server 1 and sends the message
  4. Second message arrives
  5. Client 2 message is disaggregated to TMM-1
  6. TMM-1 connects to Server 1 and send the message
  7. Third message arrives
  8. Client 3 message is disaggregated to TMM-0
  9. TMM-0 creates a new connection for Server 1 for Client 3
Note: A connection will not be opened to Server 2 until a message targeted at that server arrives.

Message

The Generic Message implementation of MRF provides a series of iRule commands for generating and populating a message. A message container wraps data that will be routed between connections. Associated with the message are meta-data fields used to assist routing of the message.

Message Types

Generic Message understands three types of message types: request, response and notifications.

Request Message

Request messages are messages that expect a response to be returned from the destination. A request message contains payload data and a source and destination address. The source address will be auto populated by Generic Message with the peer name of the originating connection. The destination address will need to be populated by the script. The source and destination address will be used by the route table to find the best matching route to use for delivering the message.

Setting the destination address of a message will identify the message as a request message. The destination address is often generated by data contained in the message.

Response Message

Response messages are messages returned by the destination to be delivered to the originator of the request. A message without a destination address is assumed to be a response message.

Generic message will assign a request-sequence-number to all request messages before raising GENERICMESSAGE_EGRESS event. The details of the originating flow (TMM and flow_id) of the request will be stored in a pending request table on the outgoing connection.

Each response message is initially assigned the oldest request-sequence-number in the pending request queue before raising GENERICMESSAGE_INGRESS event. Upon completion of the event the message will be forward to stored connection from the pending request table using the request-sequence-number.

If the pending request table is empty, the response message will be routed via the route table.

The default response routing implementation assumes that responses will arrive in the order that the requests were forwarded. If response message can arrive out of order, the script author will need to set the appropriate request-sequence-number during GENERICMESSAGE_INGRESS event.

Out of Order Message Solutions
  • Store the request-sequence-number as an attribute in the request message that will be returned by the server as part of the response message.
  • Maintain a table mapping an attribute in the request/response to the request-sequence-number.
  • Implement an independent response routing system.

If the pending request table is not usable for the use case, the script author will need to disable automatic response routing by setting the 'no-response' attribute of the message via the "GENERICMESSAGE::message no-response true" command. To disable the table for all messages the no-response attribute in the protocol profile should be set to 'yes'.

Response messages may be routed by setting the nexthop or route attribute of the message.

Notification Messages

Notification messages are messages that do not expect a response. Setting the no-response attribute of the message will instruct generic message that no response is expected for the message. If all messages will be notification message, the no-response attribute in the protocol profile should be set to 'yes'.

Message Meta-Data Fields

Source Address

The source address is a string used to identify the originating connection of the message. This is auto-populated with the peer name of the connection.

Destination Address

The destination address is a string used to identify the destination for the message. This will be used by the route table along with the source address to determine the best route to forward the message towards.

lasthop

The last hop contains an internal address for the originating connection for the message. For response routing, setting the next hop of the response message to the last hop of the request will instruct the router to bypass routing and forward the message directly to the specified connection.

nexthop

The next hop specifies an internal address for a connection that should be used for forwarding the message.

route

Setting the route attribute of a message on ingress will bypass route table lookup and direct the router to forward the message directly to the route specified in the message.

After routing has completed, the route attribute of the message will be populated with the details of the route used.

attempted_hosts

Setting the attempted hosts attribute of a message on ingress will instruct the router to skip the provided hosts when performing a load balance pick.

After routing has completed, the attempted hosts attribute of the message will contain the list of transports (virtual or transport-config) and hosts (tuple) that the message has been routed towards.

originator

The originator attribute will contain the transport (virtual or transport-config) and host (tuple) of the originating connection of the message.

route_status

After routing has completed, the route status attribute will contain the status (success or failure) of the routing operation.

Profiles

Profiles are used to configure a message routing instance and its incoming connection (via virtual servers) and outgoing connections (via transprot-configs).

Router Profile

A router profile configures the message router instance. All virtuals sharing the same router profile will share the same message router instance. They will be able to route message between the connections of all virtual in the same router instance. They will also share the same route table. The name of the router profile will be the name of the router instance.

The router contains a list of routes. The routes will be loaded as static routes into the route table.

ltm message-routing generic router my_gm_router {
    routes { default_route, forwarding_route, bad_route }
}

Mirroring is also enabled via the router profile. All virtuals that use a router profile with mirroring enabled will be mirrored.

Generic Message Protocol Profile

The protocol profile configures the generic message parser.

ltm message-routing generic protocol <name> {
   no-response <yes/no>
   disable-parser <yes/no>
   message-terminator <url encoded string>
   max-message-size <integer>
   max-egress-buffer <integer>
}
Attributes
Table 7. Generic Message Protocol Profile Attributes
Attribute Description Default
no-response When set, all messages do not expect a response. A pending-request entry will not be created to route response/answer messages back to the originator. This field is a boolean. Possible values are 'yes' and 'no'. no
disable-parser When set, the generic message protocol's parser ignores all input from the transport stream. It also will not forward messages to the transport stream. It is assumed that all message parsing and forwarding will be implemented in a tcl script. no
message-terminator The string of characters used to terminate a message. none
max-message-size The maximum size of a message in bytes. If a message is exceeds this size, the connection will be reset. 32768
max-egress-buffer The maximum number of bytes waiting to be sent via the selected transport before the protocol filter notifies the router to stop delivering messages. Once the number of bytes waiting drops below this size, the protocol filter will notify the router that it may resume delivering messages. 32768

Generic Message Events

Table 8. Generic Message Protocol Profile Attributes
Event Description
GENERICMESSAGE_INGRESS This event is raised when a message is received by the generic message filter.
GENERICMESSAGE_EGRESS The event is raised when a message is received from the proxy.

Generic Message Commands

Table 9. Generic Message Commands
Command Description
GENERICMESSAGE::peer name Gets the peer’s route name.
GENERICMESSAGE::peer name <name> Sets the peer's route name.
GENERICMESSAGE::message src Gets the message’s source address
GENERICMESSAGE::message src <src_addr> Sets the message's source address
GENERICMESSAGE::message dst Gets the message’s destination address
GENERICMESSAGE::message dst <dst_addr> Sets the message’s destination address
GENERICMESSAGE::message is_request Returns ‘true’ if the message is a request message
GENERICMESSAGE::message is_request true OR false Identifies the message as a request
GENERICMESSAGE::message length Gets the message size in bytes.
GENERICMESSAGE::message text Gets the message text.
GENERICMESSAGE::message text <new_text> Sets the message text.
GENERICMESSAGE::message data Gets the message data (as an array of bytes).
GENERICMESSAGE::message data Sets the message data (as an array of bytes).
GENERICMESSAGE::message no-response Returns 'true' if the message is an asynchronous message.
GENERICMESSAGE::message no_response true OR false Identifies the message as an asynchronous message.
GENERICMESSAGE::message create [<text> [<destination address>]] Creates a new empty message that can be sent. Once created a TEXTMSG_INGRESS event shall be raised where the script writer will be able to populate the message. Upon completion of the script, the message will be forwarded for routing.
GENERICMESSAGE::message drop <reason> Terminates processing of the current message.
GENERICMESSAGE::message status Returns the route status. Please see MR::message status
GENERICMESSAGE::message request_sequence_number Gets the request_sequence_number used to save the last hop of a request message. This will be valid during GENERICMESSAGE_EGRESS of request messages. During GENERICMESSAGE_INGRESS of response messages, it will contain the sequence number of the oldest un-responded request.
GENERICMESSAGE::message request_sequence_number <number> Sets the request_sequence_number used to save the last hop of a request message. During GENERICMESSAGE_INGRESS, setting this field will allow associting a response message with an un-responded request message and the request message's lasthop will be used as the next hop for the message.
GENERICMESSAGE::route add [src <src_addr>] [dst <dst_addr>] peer <peer> [peer <peer>]* Adds a route to the current instance that the iRule context is running in. (Note both ‘src’ and ‘source’ are acceptable. Likewise ‘dst’, ‘dest’ and ‘destination’ are acceptable).
GENERICMESSAGE::route delete [src <src_addr>] [dst <dst_addr>] Deletes a route from the current instance that the iRule context is running in. (Note both ‘src’ and ‘source’ are acceptable. Likewise ‘dst’, ‘dest’ and ‘destination’ are acceptable).
GENERICMESSAGE::route lookup [src <src_addr>] [dst <dst_addr>] Returns a route matching the specified source address and destination address in the instance that the iRule context is running in. (Note both ‘src’ and ‘source’ are acceptable. Likewise ‘dst’, ‘dest’ and ‘destination’ are acceptable).

Virtual Server Statistics

Table 10. Generic Message Commands
Field Description
request messages in The number of request messages received
response message in The number of response messages received
request messages out The number of request messages sent
response messages out The number of response messages sent
request bytes in The number of bytes of request messages received
response bytes in The number of bytes of response message received
request bytes out The number of bytes of request messages sent
response bytes out The number of bytes of response messages sent
failed request messages The number of request messages that failed routing
failed response messages The number of response messages that failed routing
failed request bytes The number of bytes of request messages that failed routing
failed response bytes The number of bytes of response messages that failed routing
current connections The current number of connections.
pending requests The current number of pending requests