Diameter Protocol Configuration Parameters

You can use the configuration parameters in create_config.py to configure the Diameter protocol implementation.

See the discussion about extending the Diameter dictionary for information necessary to configure Diameter protocol messages, and extend the base Diameter implementation.

For more information about the MATRIXX environment variables, see the discussion about container directories and environment variables in MATRIXX Installation and Upgrade.

Attention: Some parameters in Diameter Protocol Configuration Parameters configure Diameter host and realm properties. You can configure additional Diameter host and realm behavior using a sed file. See Diameter Host and Realm Routing for more information.

Table 1. Diameter Protocol Configuration Parameters
Parameter	Description	Default Value
Diameter Source Host Name for Non-Routable Packets	Specifies the value to use for the Origin-Host AVP in non-routable packets (CERs, CEAs, DWRs, DWAs, DPRs, and DPAs) sent by MATRIXX Engine. Identifies this Diameter node to the Diameter peers with which it shares connections. This question is asked for each engine in the environment. The Diameter source host name is typically the DNS host name and must be a fully qualified domain name in the Diameter realm, for example, `source.mycompany.com`. create_config.info question:`Engine n: Diameter: What is the hostname of your Diameter source (the Origin-Host AVP) for non-routable packets?`	myhost
Diameter Realm for Non-Routable Packets	The Diameter realm is typically your company website address. This question is asked for each engine in the MATRIXX Engine environment. Diameter applications use the realm string to identify their domain of responsibility. This allows virtual domains to exists within a single host where multiple open Diameter entities are running with different realm configurations. This value is for non-routable packets. The value must be a fully qualified domain name. create_config.info question: `Engine n: Diameter: What is the name of your Diameter realm (the Origin-Realm AVP) for non-routable packets?`	matrixx.com
Diameter Source Host Name for Routable Packets	Specifies the value to use for the Origin-Host AVP in routable packets sent by the MATRIXX Engine servers. Identifies this Diameter node to the Diameter peers with which it shares connections. create_config.info question: `Engine n: Diameter: How do you want to assign the Diameter source (the Origin-Host AVP) for routable packets?` The options are same and tra_dr.	same
Diameter Realm for Routable Packets	A Diameter client sends an Origin-Realm AVP to identify the source of the packet. Normally this is the same value for routable and non-routable packets. In some special cases, the value used needs to be different. This question allows you to specify how the value for routable packets is determined. The options are same and tra_dr. create_config.info question: `Engine n: Diameter: How do you want to assign the Diameter source (the Origin-Realm AVP) for routable packets?`	same
Maximum Message Rate	The maximum number of Diameter packets that can be received, per second, before message throttling is activated. The default is `0`, which deactivates message throttling. If the message rate exceeds the configured value or if throttling is disabled and the message rate is too high, they are added to the inbound Diameter queue. If the queue runs out of space, additional messages are rejected until the queue has available space and a 4002 (OUT_OF_SPACE) return code is sent back to the network. create_config.info question: `What is the maximum message rate in messages per second you want to support?`	0
Message Rate Window Size	If you turn on message throttling, you must set the size of the message window. The maximum message rate is checked by calculating the maximum number of messages that can be received during a specified time window. Once this calculated value has been met, all remaining messages received during this time window are rejected. For example, if the maximum message rate is 5,000 messages per second, and the window size (in micros) is 1,000,000 (1 second), the throttle is not activated until after 5,000 messages have been processed. If the interval of time is less than 1 second, and more than 5,000 messages have been received, the socket is not read again until the next interval starts. The interval starts when the first packet within an interval is received. Note: Setting a window size that is too small may cause a small spike of messages to be rejected, even though the total number in a second has not been exceeded. Setting a window size that is too large might cause a lot of empty time where all messages are rejected until the next time window. This happens when spikes early in the time window cause the calculated maximum to be reached. The minimum value is 100 and the maximum value is 2000000. create_config.info question: `What is the window size (in micros) to measure this message rate?`	1000000
Diameter Total Used Octets	The Diameter Gateway can calculate the total number of octets from the CC-Input-Octets and CC-Output-Octets in the network message. create_config.info question: `Diameter: Do you want the Diameter Gateway to calculate CC-Total-Octets from CC-Input-Octets and CC-Output-Octets (y/n)?`Diameter Gateway For more information about `CC-Total-Octets`, see the discussion about Diameter total octet calculation in MATRIXX Diameter Integration.	n
Diameter Routing by Realm Name	This parameter determines how a message destined to a Diameter Peer must be routed when the socket is closed. It uses the Origin-Host attribute-value pair (AVP). If the value is `yes`, the engine checks if there is another Diameter Peer with an open socket that has the same realm name. If one is found, it is used. If one is not found or if the value is `no`, the MDC is not sent and is logged. create_config.info question: `Diameter: Do you want to allow routing by the realm name if a preferred connection is not available (y/n)?`	n
3GPP MS-TimeZone AVP Values	You can configure how to handle non-conforming 3GPP-MS-TimeZone values that cannot be decoded by the Diameter Gateway. `reject` – The Diameter packet is rejected with a 5004 error code, INVALID_AVP_VALUE. `ignore` – The non-conforming AVP is ignored instead of being rejected, and the appropriate MDC field is not set. In such cases, the event generated has a utcOffset value of `0` and an EventTime time zone value of `Z` (UTC time). This is consistent with the behavior when the AVP is not provided. `process` – The non-conforming AVP is assumed to be a negative value in two's complement format. create_config.info question: `Diameter: How do you want to handle non-conforming 3GPP-MS-TimeZone AVP values?`	reject
Default Diameter Dictionary	The MATRIXX Diameter Dictionary is defined in the diameter_dictionary.xml file and has definitions for the Diameter AVPs, functions, and Diameter-to-MDC mappings implemented in the MATRIXX Engine. To add a Vendor ID or AVPs, or make other changes to the Diameter Dictionary, answer `n` to the question: `Diameter: Do you want to use the default Diameter Gateway dictionary (y/n)?` Then answer the following questions: `Diameter: How many new Vendor Ids do you want to add?` Note: By default the Diameter Dictionary supports Vender ID names '3GPP', '3GPP2', 'ETSI', 'MatrixxSoftware' and Vender ID numbers '0', '10415', '5535', '13019', and '35838'. For each ID to add, the script asks the following two questions: `Diameter: VendorId:1:What is the new Vendor Id's name?` `Diameter: VendorId:1:What is the new Vendor Id's number?` After configuring the Vendor IDs, answer the following questions: `Do you want to add any Diameter AVPs (y/n)?` `Do you want to add any Diameter AVPs to the defined packets (y/n)?` `Do you want to use a constant value for ExternalServiceType (y/n)?`	y
Add Diameter Simple AVPs	If you do not use the default Diameter Dictionary (answer `n` to the default Diameter Dictionary question), you can add simple AVPs to the following Diameter packets. You must answer `y` to the question: `Do you want to add any Diameter AVPs (y/n)?`. You must specify 1 or more simple AVPs to the following question: `How many simple (non-grouped) Diameter AVPs do you want to add?` For each AVP answer the following questions: `What is the AVP's name?` `What is the AVP's code?` `What is the AVP's type?` `What is the AVP's vendorId name?` AVP types are listed by the create_config.py script when it runs, and include types such as `Integer32`, `Address`, and `Enumerated`. Most of these are described in the Diameter RFC. The one exception is TimeZone. It is a special type that is used to identify the type of data used in the 3GPP-MS-TimeZone AVP. Important: Enums are generated from system MDC information in the mdc_config_system.xml file on the MATRIXX Engine pod. All PriceLoaderEventTriggerType values must be present in the /mtx/data/data_container_subtype/PriceLoaderEventTriggerType.xml file. Add any missing values to this file. Note: Most AVPs are mapped to an MDC field, but this is not required. An AVP must be mapped to an MDC if it is used during processing or if it is returned on the Answer packet. Otherwise it does not have to be mapped. If an AVP is not mapped, it still needs to be specified in the packet definition to prevent error messages being logged about unknown AVPs.	n
Add Diameter Grouped AVPs	If you do not use the default Diameter Dictionary (answer `n` to the default Diameter Dictionary question), you can add grouped AVPs to the Diameter packets. You must answer `y` to the question: `Do you want to add any Diameter AVPs (y/n)?`. You must specify `1` or more grouped AVPs to the question: `Diameter: How many grouped Diameter AVPs do you want to add?` For each new grouped AVP, you must specify the following information: If an MDC exists that is based upon an MDC used in the diameter_dictionary_base.xml file, the following question is asked: `Diameter: Do you want to use a private MDC instead of the MDC_NAME MDC (y/n)?` `Diameter: New grouped AVP:1:What MDC struct name should be used for mapping this AVP?` `Diameter: New grouped AVP:1:optional:1:What is the maximum number of times this AVP can occur?` The following questions are asked for each AVP in a grouped AVP: `Diameter: New grouped AVP:1:optional:1:What is the MDC field name to map to this AVP?` `Diameter: New grouped AVP:1:optional:1:Do you want to specify additional attributes for this mapping (y/n)?` `Diameter: Do you want to add any AVPs to existing grouped AVPs (y/n)?` If you answer `y` to this question, then the following questions might be asked: `Diameter: What are the names of any existing grouped AVPs to which you want to add AVPs?` `Diameter: Modified grouped AVP:GROUPED_AVP_NAME:Do you want to use a different MDC struct name instead of MDC_NAME for this grouped AVP (y/n)?` `Diameter: Modified grouped AVP:MDC_NAME:How many fixed AVPs do you want to add?` `Diameter: Modified grouped AVP:MDC_NAME:How many required AVPs do you want to add?` `Diameter: Modified grouped AVP:MDC_NAME:How many optional AVPs do you want to add?` `Diameter: Modified grouped AVP:MDC_NAME:optional:1:What is the name of this AVP?` `Diameter: Modified grouped AVP:MDC_NAME:optional:1:What is the maximum number of times this AVP can occur?` `Diameter: Modified grouped AVP:MDC_NAME:optional:1:What is the MDC field name to map to this AVP?` `Diameter: Modified grouped AVP:MDC_NAME:optional:1:Do you want to specify additional attributes for this mapping (y/n)?` If you answer `y` to this question, you must answer the following questions about the attributes. `Diameter: Modified grouped AVP:MDC_NAME:optional:2:What type of decoding should be used for this AVP?` Based on your answer to this question, additional questions might be asked. For example, if you entered `decode_hex_string`, you are asked the following question: `Diameter: Modified grouped AVP:MDC_NAME:optional:2:What is the name of the destination field for this function?` `What is the grouped AVP's name?` `What is the grouped AVP's code?` `What is the grouped AVP's vendorId name?` If the AVP has no Vendor ID, press enter to accept the default value. `How many fixed AVPs does it have?` `How many required AVPs does it have?` `How many optional AVPs does it have?` For each category with an AVP, answer the following questions: `What is the name of this AVP?` `What is the maximum number of times this AVP may occur?` The default value is `1`.	0
Add Diameter AVPs to Packets	If you do not use the default Diameter Dictionary (answer `n` to the default Diameter Dictionary question), and you answer `y` to the question `Do you want to add any Diameter AVPs to the defined packets (y/n)?`, you must answer the following questions: `Diameter: Do you want to add Diameter AVPs to any packets defined in the Common application (y/n)?` `Diameter: Do you want to add Diameter AVPs to any packets defined in the NASREQ application (y/n)?` `Diameter: Do you want to add Diameter AVPs to any packets defined in the Accounting application (y/n)?` `Diameter: Do you want to add Diameter AVPs to any packets defined in the Credit-Control application (y/n)?` `Diameter: Do you want to add Diameter AVPs to any packets defined in the Gx application (y/n)?` `Diameter: Do you want to add Diameter AVPs to any packets defined in the Sy application (y/n)?` One or more additional questions are asked as determined by the answers to the earlier questions. For each application to which you answered `y`, you must answer the following questions where `PacketName` is the application name, the command name, and Request or Answer: `How many required Diameter AVPs do you want to add to the PacketName Request packet?` `How many optional Diameter AVPs do you want to add to the PacketName Answer packet?` For example: `How many required Diameter AVPs do you want to add to the Common application Capabilities-Exchange Request packet?` The defined packets for each application are: Common Capabilities-Exchange Re-Auth Abort-Session Session-Terminate Device-Watchdog Disconnect-Peer NASREQ AA Accounting Accounting Credit-Control Re-Auth Credit-Control Gx RA CC Sy Session-Terminate Spending-Limit Spending-Status-Notification Based on your answers in the preceding question, for each AVP in each packet, answer the following questions: `What is the AVP's name?` `What is the MDC's field name?` Specify the full path of the field in the MDC, separated by dots (.). For example: `Diameter:New Credit-Control application Credit-Control Request required AVP:1 What is the AVP's name?Calling-Party-Number Diameter:New Credit-Control application Credit-Control Request required AVP:1 What is the MDC's field name? ServiceInfo.InInfo.CallingPartyNumber` Note: In this example, the `Calling-Party-Number` AVP must have been added already to the Diameter Dictionary as described in the discussion about adding a simple AVP to the Diameter Dictionary and the MtxDiamRoMsg MDC must have been extended to include the `InInfo.CallingPartyNumber` field. For example, `ServiceInfo.InInfo.CallingPartyNumber`. You can specify a field name up to a total of eight levels. Note: To add an AVP to a packet but do not want the AVP to be processed by MATRIXX Engine by mapping it to an MDC field, leave the MDC field name empty and press Enter.	n
Use a Custom MDC in a Struct	For each custom MDC, the create_config.py script dynamically creates a list of custom MDCs for each struct used in the diameter_dictionary_base.xml file. This following question is only asked for a struct if this list for the struct is not empty. `Do you want to use a private MDC instead of the diameter_struct_name MDC (y/n)?` If the answer to this question is `y`, and there is only one possible custom MDC, the create_config.py script uses the MDC. However, if there is more than one element in the list, you must answer the following additional question: `What custom MDC do you want to use instead of the diameter_struct_name MDC?`	y
Diameter Packet Concise Trace Log	The default Diameter log has detailed debug information and packet information. To create a separate log that has only the Diameter packets processed, answer `y` when prompted to create a concise trace of Diameter packets. You can use this log to make sure the correct AVPs were sent. create_config.info question: `Diameter: Do you want a concise trace of Diameter Packets processed by the Diameter Gateway (y/n)?`	n
Diameter Dictionary sed file	If you customize the Diameter Dictionary file and a sed file exists, enter the name of the Diameter Dictionary sed file when prompted. create_config.info question: `Diameter: What is the name of the pre-existing diameter dictionary xml sed file (optional)?`	None
Compression Level for sending MDCs	When an MDC is sent in a Diameter packet, it is converted to a compact MDC and added as an AVP. Sometimes, the size of this AVP might be too large to be sent successfully. To resolve this, the compact MDC can be compressed. A value of 1 is the least compression, but the fastest, and 9 is the most compression, but most time-consuming. create_config.info question: `Diameter: What is the compression level (0-9) to use when sending MDCs in a Diameter packet?`	6
Capabilities-Exchange Message Timeout	The timeout value in milliseconds that the Diameter Gateway waits before sending a Capabilities-Exchange response to the Diameter client. create_config.info question: `Diameter: What is the timeout value in milliseconds to wait for the client-level Capabilities Exchange?`	50
Device-Watchdog Message Timeout	When the client socket is idle, the number of seconds that the Diameter Gateway waits before sending a Device-Watchdog message. create_config.info question: `Diameter: What is the time value in seconds a client socket is idle before sending a Device Watchdog packet?`	4
Error MDC Logging	Sets whether to log Diameter message MDCs that report a non-successful result (a Diameter result value other than `2001`). Logging Diameter MDCs is useful in troubleshooting when a high-level service operation is successful but a child service context is not. Diameter error MDC logs are in compact MDC format and are written to the ${MTX_ERROR_MDC_LOG_DIR}. create_config.info question: `Diameter: Do you want to log the MDCs that report a non-successful result (y/n)?`	y
Error MDC Log Closing	The closing of an error MDC log is triggered by either the log batch size, an amount of logging time, or an amount of idle time that has elapsed, which ever occurs first. Each parameter value is configurable and can be disabled by setting its value to 0, which removes it from the log-closing equation. create_config.info questions: `Diameter: What is the size in MBytes that you want to use to trigger a file close for error-MDC logs?` `Diameter: What is the time in seconds that you want to use to trigger a file close for error-MDC logs?` `Diameter: What is the idle time in milliseconds that you want to use to trigger a file close for error-MDC logs?`	Batch Size: 10 Mb Exceeded Time: 60 seconds Idle Time: 60000 milliseconds
Decode User-Location-Info AVPs	The 3GPP User-Location-Info AVP has a `type` field that can be either an enumeration field as specified in 3GPP 29.061 or a bit-mask field as specified in 3GPP 29.274. By default, the `type` field is treated as an enumeration. If you answer `y`, then the `type` field is treated as a bit-mask field. create_config.info question: `Diameter: Do you want to decode 3GPP User-Location-Info AVPs using the bit-mask version of the type field (y/n)?` Important: If you are using External Diameter Gateway (EDGW), use a sed file to configure the User-Location-Info decoding. For more information, see the discussion about deploying External Diameter Gateway.	n
Default Time-to-Live for Diameter	Specifies the default time to live in milliseconds for timed-out Diameter records before they are discarded. create_config.info question: `Diameter:What is the default time to live in milliseconds for DIAMETER messages?`	1500
Diameter Result Code for Rejected Messages	Specifies the result code for Diameter messages that have been in the system too long. A value of 0 indicates no response. create_config.info question: `What is the DIAMETER result code for DIAMETER messages which have been rejected because they have been in the MATRIXX system to long?`	0
Time-to-Live for Accounting Interim Record	Specifies the default time to live in milliseconds for timed-out accounting interim records before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Accounting:INTERIM_RECORD messages?`	1500
Time-to-Live for Accounting Event Record	Specifies the default time to live in milliseconds for timed-out accounting event records before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Accounting:EVENT_RECORD messages?`	1500
Time-to-Live for Accounting Start Record	Specifies the default time to live in milliseconds for timed-out accounting start records before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Accounting:START_RECORD messages?`	1500
Time-to-Live for Accounting Stop Record	Specifies the default time to live in milliseconds for timed-out accounting stop records before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Accounting:STOP_RECORD messages?`	1500
Time-to-Live for Abort Session Requests	Specifies the default time to live in milliseconds for timed-out abort-session requests before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Abort-Session-Request messages?`	1500
Time-to-Live for CCR Update Requests	Specifies the default time to live in milliseconds for timed-out CCR update requests before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Credit-Control-Request:UPDATE_REQUEST messages?`	1500
Time-to-Live for CCR Event Requests	Specifies the default time to live in milliseconds for timed-out Diameter operations before they are discarded. Specifies the default time to live in milliseconds for timed-out CCR event requests before they are discarded.create_config.info question: `Diameter:What is the time to live in milliseconds for Credit-Control-Request:EVENT_REQUEST messages?`	1500
Time-to-Live for CCR Initial Requests	Specifies the default time to live in milliseconds for timed-out CCR initial requests before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Credit-Control-Request:INITIAL_REQUEST messages?`	1500
Time-to-Live for CCR Termination Requests	Specifies the default time to live in milliseconds for timed-out CCR termination requests before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Credit-Control-Request:TERMINATION_REQUEST messages?`	1500
Time-to-Live for Gx CC Requests	Specifies the default time to live in milliseconds for timed-out Gx CC requests before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Gx CC-Request messages?`	1500
Time-to-Live for Reauthorization Requests	Specifies the default time to live in milliseconds for timed-out reauthorization requests before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Re-Auth messages?`	1500
Time-to-Live for Re-tariff Requests	Specifies the default time to live in milliseconds for timed-out re-tariff requests before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Re Tariff-Request messages?`	1500
Time-to-Live for Credit Control AA Requests	Specifies the default time to live in milliseconds for timed-out Credit Control AA requests before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Credit-Control AA-Request messages?`	1500
Time-to-Live for Sh Interface Messages	Specifies the default time to live in milliseconds for timed-out Sh Interface messages before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Sh interface messages?`	1500
Time-to-Live for Session Termination Requests	Specifies the default time to live in milliseconds for timed-out session termination requests before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Session-Termination-Request messages?`	1500
Time-to-Live for Sy Spending Limit Messages	Specifies the default time to live in milliseconds for timed-out Sy spending limit messages before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Sy spending limit messages?`	1500
Time-to-Live for Sy Status Notification Messages	Specifies the default time to live in milliseconds for timed-out Sy status notification messages before they are discarded. create_config.info question: `Diameter:What is the time to live in milliseconds for Sy status notification messages?`	1500
Rating Group ID for Offline Voice	Specifies the default rating group ID for Diameter offline voice (Rf) service. create_config.info question: `Global:What is the default Rating Group Id for the Diameter Offline voice service?` Attention: For Diameter offline charging to work, the offline usage status policy must first be allowed. See the discussion about status policies in MATRIXX Subscriber Management for more information.	0

Diameter Host and Realm Routing

The following SED commands control how outbound traffic peers are identified when using host/realm routing:

<route_by_host_and_realm>value</route_by_host_and_realm> — When value is 1, the peer must match the destination host and realm.
<route_by_host_only>value</route_by_host_only> — When value is 1, the peer must match the destination host only.

By default, both values are 1 and Diameter Gateway first tries to find a peer that matches both the host and the realm. If it cannot find a match, it looks for a peer that matches only the host.

In addition, when realm based routing is enabled, and Diameter Gateway does not find a peer to route to by host and realm match, or host only match (based on your configuration of the SED commands described earlier), you can set the following command value to 1 to specify that when realm based routing returns a peer, the destination host is preserved on the outbound message.

<keep_destination_host_on_realm_route>value</keep_destination_host_on_realm_route>

By default, the value is 0 and the destination host is not required.

Discarding Timed-Out Operations

You can configure Diameter Gateway to discard operations that have been in the system so long that the originator (end point) has given up, so replying has no result. This reduces the number of messages that must be recovered after a sudden system overload. Messages can be rejected at the start of processing by the Charging Server or at the start of processing by the Transaction Server. In either case, the result is set to 48 == TIMED_OUT, the result detail is set to 60 == DET_TIME_TO_LIVE_ENDPOINT_EXPIRED, and the MATRIXX Data Container (MDC) is passed back to Diameter Gateway.

A result of DIAMETER TOO_BUSY (3004) is returned to the Diameter client. The following fields in the MtxChrgMsg MDC control this behavior:

TimeToLiveEndpoint (datetime format) — Specifies the date/time after which replying to the end point has no result.
TimeToLiveResponseFlag (unsigned int32 format) — Indicates to MDC Gateway what to do if a message is discarded after timing out. A value of 0 means that MDC Gateway discards the stale request. A value of 1 means that MDC Gateway sends a TimeToLive-expired response.
TimetoLiveDeltaInSeconds (unsigned int32 format) — Specifies the number of seconds in addition to the TimeToLiveEndpoint. If this field is set, the value represents the time the message was received, plus the delta value. TimetoLiveDeltaInSeconds allows the rules for setting TimeToLiveEndpoint to be flexible. You can set TimetoLiveDeltaInSeconds using selective updates on Diameter Gateway. For more information, see the discussion about configuring selective updates in MATRIXX Installation and Upgrade.

You can configure this feature by answering the create_config.info questions described in the discussion about CAMEL Gateway configuration. If you answer 0 to any of the time-to-live questions, the TimetoLiveEndpoint is not set. The default values to these questions is 0, meaning that the discarding of timed-out operations is turned off by default.