In this section:
When creating a Modification Record, you are required to configure the Order and Command attributes in the Web-based User Interface [(Web UI), see the following figure].
For detailed information about configuring Modification Records, see Configuring Modification Tables and Records.
Modification Record Create Screen
Note
If the AVP is nested, create AVP aliases to reflect the nested AVPs relationship before creating the modification record.
The (modification) order for the message must be unique for each Modification Table and can be between 1 and 100. The (modification) Command attribute for the message is applied in numerical order.
The format for describing the Command attribute is provided in the following table.
Command Attribute Format
| Format | Description |
|---|---|
| bold text | Type exactly as shown. |
| <text> | Replace with the appropriate argument. |
| [abc] | Any or all arguments [ ] are optional. |
| a|b | Options delimited by | cannot be used together |
Syntax for the Command Attribute
Note
To apply modifications to a Diameter answer message, the request must have the command set-answer-rt <routingTableName> applied.
The syntax for the supported modification commands include the following:
Caution
Do not use curved quotation marks in the command syntax (“ ” ). Use only straight quotation marks (" "). The text editor may not parse curved quotation marks.
The following figures shows an example of a Modification Record Selection Screen and an example of a Modification Record.
Note
The header bit flags M | P | E | T are case insensitive and are displayed in the lower case once validated.
A text editor may be used to facilitate command creation. The value can then be cut and pasted into the Command attribute.
Modification Record Selection Screen
Modification Record Screen
append-avp <avpString>
Append the (top-level) AVP to the end of the message. The <avpString> describes the format of the appended AVP as described with the UA XML interface for an AVP. Grouped AVP (such as the Proxy-Info, see example below) can also be appended.
For example:
append-avp <avp avp-name=”Proxy-Host” value=”test_table.example.net” />
append-avp <avp avp-name=”Proxy-Info”><avp avp-name=”Proxy-Host” value=”test_table.example.net”/><avp avp-name=”Proxy-State” value=”00 0a 0b”/></avp>
count <statsName> <columnNumber>
The message is counted in the DSC Message statistics with the provided <statsName> and <columnNumber>.
The <statsName> may not contain any comma characters.
The <columnNumber> must be an integer from 1 to 10. The integer 1 maps to the column named COUNTER_1 in the statistics file, and so on.
ingress-filtering
Immediately apply ingress filtering to the message.
mod-avp-code <old avpAlias> <new avpAlias>
Modify AVP Code command.
<old avpAlias>: avpAlias of AVP in original Diameter message.
<new avpAlias>: avpAlias of AVP that will replace original AVP in Diameter message.
mod-avp-value bitwise and|or <avpAlias> <0x mask> [offset]
Consider the following for this command:
- <avpAlias> must be the name of an existing AVP Alias Definition
- offset is an optional byte count offset to apply the mask, default of 0 applies mask to MSB toward LSB
- mask is a hex value that must start with 0x and must be aligned to bytes (even count of hex characters)
- mask is applied as a big endian integer (MSB is applied to the lowest array offset)
- mask can be up to 8 bytes
- value without an offset is expected to apply to an integer type and the mask should cover all bytes of the value
- if an AVP value does not have enough bytes to apply the mask then the command is ignored (message trace will report)
A few conditions are possible where the provisioned rules are valid but cannot be applied to an incoming message. For these cases, a message tracing log is generated (should the message be traced at the time). The trace log includes the trace preamble and text similar to: mod <xyz> cannot be applied to AVP <abc>: data length.
Specific cases include:
- a mask value is larger than the AVP data
- an offset value pushes the mask past the end of the AVP data
The following table provides examples for mod-avp-value bitwise.
mod-avp-value bitwise Examples
| Command | AVP Value Before | AVP Value After |
|---|---|---|
| mod-avp-value bitwise or <avpAlias> 0x00ff0000 | aabbccdd | aaffccdd |
| mod-avp-value bitwise and <avpAlias> 0x00ff0000 | aabbccdd | 00bb0000 |
| mod-avp-value bitwise and <avpAlias> 0x00ff 2 | aabbccdd | aabb00dd |
| mod-avp-value bitwise and <avpAlias> 0x8080 | aabbccdd | Not applied - mask length incompatible |
mod-avp-value byte-replace <avpAlias> <0x value> [offset]
Consider the following for this command:
- <avpAlias> must be the name of an existing AVP Alias Definition
- offset is an optional byte count offset to apply the value, default of 0 (zero) applies to MSB toward LSB
- value is a hex value that must start with 0x and must contain an even number of hex digits
- if an AVP value does not have enough bytes to apply the value then the command is ignored (message trace will report)
A few conditions are possible where the provisioned rules are valid but cannot be applied to an incoming message. For these cases a message tracing log would be generated (should the message be traced at the time). The trace log includes the trace preamble and text similar to: mod <xyz> cannot be applied to AVP <abc>: data length.
The following table provides examples for mod-avp-value byte-replace.
mod-avp-value byte-replace Examples
| Command | AVP Value Before | AVP Value After |
|---|---|---|
| mod-avp-value byte-replace <avpAlias> 0x55 3 | aabbccdd | aabbcc55 |
| mod-avp-value byte-replace <avpAlias> 0x3456 5 | aabbccddeeff00aa | aabbccddee3456aa |
mod-avp-value replace <avpAlias> <string>
Consider the following for this command:
- <avpAlias> must be the name of an existing AVP Alias Definition
- <string> must consist of printable ASCII characters and must be enclosed in quotes. In addition to the restrictions on all text strings, the following characters may not be used within string: "<>&;
- if the AVP described by <avpAlias> is not present in the message, this command is skipped.
The <string> defined in the command is the new value to replace the existing string value. The <string> is the only AVP field modified.
The following table provides examples for mod-avp-value replace:
mod-avp-value replace Examples
| Command | AVP Value Before | AVP Value After |
|---|---|---|
| mod-avp-value replace <avpAlias> sonus_table.com | test_table.example.com | sonus_table.com |
| mod-avp-value replace <avpAlias> the_cloud_table.com | sonus_table.com | the_cloud_table.com |
mod-avp-value insert left|right <avpAlias> <string>
This command inserts the <string> to the AVP identified by <avpAlias>, either at the left or right.
Consider the following for this command:
- <avpAlias> must be the name of an existing AVP Alias Definition.
- <string> must consist of printable ASCII characters and must be enclosed in quotes. In addition to the restrictions on all text strings, the following characters may not be used within string: "<>&;
- if the AVP described by <avpAlias> is not present in the message, this command is skipped.
The following table provides examples for mod-avp-value insert.
mod-avp-value insert Examples
| Command | AVP Value Before | AVP Value After |
|---|---|---|
| mod-avp-value insert left <avpAlias> "XY-Z.” | test_table.example.com | X Y-Z.test_table.example.com |
| mod-avp-value insert right <avpAlias> "XYZ” | test_table.example.com | test_table.example.comXYZ |
mod-avp-value delete left|right <avpAlias> <octetCount>
This command removes <octetCount> characters from the contents of the AVP identified by <avpAlias> either at the left or right.
Consider the following for this command:
- <avpAlias> must be the name of an existing AVP Alias Definition.
- <octetCount> must be a strictly positive integer.
- if <octetCount> is larger than the size of the AVP then the AVP contents are removed entirely and the empty AVP is left in the message.
- if the AVP described by <avpAlias> is not present in the message, this command is skipped.
The following table provides examples for mod-avp-value delete.
mod-avp-value delete Examples
| Command | AVP Value Before | AVP Value After |
|---|---|---|
| mod-avp-value delete left <avpAlias> 11 | test_table.example.com | example.com |
| mod-avp-value delete right <avpAlias> 12 | test_table.example.com | test_table |
| mod-avp-value delete left <avpAlias> 1024 | test_table.example.com |
mod-avp-flag <avpAlias> assign|clear|set m|p|<0x bits>
Consider the following for this command:
- V bit is illegal to set directly (use Vendor-Id on AVP)
- bits is a hex byte that must start with 0x and must adhere to the same flag restrictions (nonset of V)
- assign ignores the V bit and keeps it intact, the rest of the bits are set to <0x bits>
- when assign is followed by a bit (M or P), all the other bits (except V which remains intact) are reset to 0
A few conditions are possible where the provisioned rules are valid but cannot be applied to an incoming message. For these cases a message tracing log would be generated (should the message be traced at the time). The trace log will include the trace preamble and text similar to: mod <xyz> cannot be applied to AVP <abc>: data length.
The following table provides examples for mod-avp-flag
mod-avp-flag Examples
| Command | Description |
|---|---|
| mod-avp-flag set m | sets M bit on AVP, other bits are retained |
| mod-avp-flag assign 0×60 | sets M and P bits only, clears reserved (keeps V intact) |
mod-message-flag assign|clear|set p|e|t|<0x bits>
Consider the following for this command:
- R bit is illegal to set directly
- E bit is illegal on Requests
- bits is a hex byte that must start with 0x and must adhere to the same flag restrictions (nonset of R and possibly E)
- assign ignores the R bit and keeps it intact, the rest of the bits are set to <0x bits>
- E bit cannot be set on a request type message, the command is skipped
- when assign is followed by a bit (P, E or T), all the other bits (except R which remains intact) are reset to 0
The following table provides examples for mod-message-flag
mod-avp-flag Examples
| Command | Description |
|---|---|
| mod-message-flag set p | Sets P bit on AVP; other bits are retained |
| mod-message-flag clear 0x0f | Zeros out reserved bits |
| mod-message-flag set 0x0f | Ones in all reserved bits |
realm-accounting
Indicate that this message and its answers should be tracked for billing verification. Issuing this command multiple times for the same message has no further effect.
Note
Diameter loop detection on incoming requests happens before a message reaches the routing tables, so enabling realm accounting using this command does not count received requests that trigger a DIAMETER_LOOP_DETECTED error code. If you want to count these messages, enable realm accounting for all messages received at the node using the DSC Node, Realm Accounting attribute.
remove-avp <avpAlias>
Consider the following for this command:
- <avpAlias> must be the name of an existing AVP Alias Definition.
- any AVP matching the AVP Alias are removed (there may be several, if the AVP Alias uses the ANY specifier).
- if the AVP described by <avpAlias> is not present in the message, this command is skipped.
replace-avp <avpAlias> <avpString>
Consider the following for this command:
- <avpAlias> must be the name of an existing AVP Alias Definition.
- any AVP matching the <avpAlias> have their contents replaced with the AVP described by <avpString>.
- if the AVP described by <avpAlias> is not present in the message, this command is skipped.
set-answer-rt <routingTableName>
When this command is applied to a Diameter Request, the corresponding Diameter Answer message, received from an ADN Connection, goes through any modifications indicated by the routing table before the answer is routed back to the ADN from which its Request was received.
Hence, this command allows Answer messages to undergo modification commands but does not allow re-routing of Answer messages
Note
The set-answer-rt command can be used with the use-rate-limiter command to apply Incoming Answer Rate Limiters to a message. If the set-answer-rt <routingTableName> is applied to a request by the Outgoing Request Routing Table and the <routingTableName> invokes the user-rate-limiter command, then the answer message is subjected to the Incoming Answer Rate Limiters as it returns from the ADN.
trace
Mark the message as of interest for tracing. The message progress is logged, subject to pacing. Issuing this command multiple times for the same message has no further effect.
use-rate-limiter <NAME>
Associates the message with the Rate Limiter identified by the <NAME>. The use-rate-limiter command can be applied to a request data path and also to an answer message if referenced by a routing table specified by the set-answer-rt command.
rta on|off
The routing table modification commands 'rta on' and 'rta off' are used to control round-trip statistics for specific messages from incoming ADNs. The routing table modification command functions as follows:
- rta on
When applied to a message, this command enables the round trip accounting feature for the message.
Use 'rta on' with the DSC Node attribute Round Trip Accounting disabled to enable round-trip accounting only for selected messages.
- rta off
When applied to a message, this command disables the round trip accounting feature for the message.
Used 'rta off' with the DSC Node attribute Round Trip Accounting enabled to exclude round-trip accounting for specific messages.
replace-dest-realm-from-imsi <AVPAlias> <optional prefix=epc> <optional suffix=3gppnetwork.org>
The command is validated for existing AVPAlias and valid prefix and suffix.
Note
Before using this command ensure the required IMSI Mobile Codes have been configured, refer to Configuring Mobile Codes Definitions.
Note
The string prefix.mnc000.mcc000.suffix must be validated to be a valid FQDN string.
Consider the following for this command:
- <AVPAlias> must be a string
The prefix is optional. If the prefix is not provided, it defaults to epc.
NoteThe prefix can be empty, in which case the user must set it using the string <empty>.
- The suffix is optional. If the suffix is not provided, it defaults to 3gppnetwork.org.
If the command is valid, then the modified Destination-Realm AVP value is applied to the message.
If the modification cannot be applied to a message because of an error, a paced log entry is added to the debug log. Errors include the following:
- A message with an AVPAlias that contains an IMSI value that does not start with six digits.
- A message that does not contain a Destination-Realm AVP.
replace-dest-realm-from-imsi-if <AVPAlias> <Destination-Realm> <optional prefix=epc> <optional suffix=3gppnetwork.org>
The command is validated for existing AVPAlias and valid prefix and suffix.
Note
Before using this command ensure the required IMSI Mobile Codes have been configured, refer to Configuring Mobile Codes Definitions.
Note
The string prefix.mnc000.mcc000.suffix must be validated to be a valid FQDN string.
Consider the following for this command:
- <AVPAlias> must be a string
<Destination-Realm> must be a valid FQDN string.
NoteThe modification is only applied when the received message Destination-Realm Value matches the user-provided one.
The prefix is optional. If the prefix is not provided, it must default to epc.
NoteThe prefix can be empty, in which case the user must set it using the string <empty>.
- The suffix is optional. If the suffix is not provided, it defaults to 3gppnetwork.org.
If the command is valid, then the modified Destination-Realm AVP value is applied to the message.
If the modification cannot be applied to a message because of an error, a paced log entry is added to the debug log. Errors include the following:
- A message with an AVPAlias that contains an IMSI value that does not start with six digits.
- A message that does not contain a Destination-Realm AVP.
Overview
Content Tools