Figure 2: Sample Dictionary (.dct) File

.dct File Location

The .dct dictionary files must be placed in the same directory as the Steel-Belted Radius Carrier daemon. During initialization, Steel-Belted Radius Carrier reads the file dictiona.dcm in the server directory to get a list of files with an extension of .dct (standard dictionary files) and uses the list to create a master dictionary, which includes all known attributes.

.dct File Records

Records in a .dct dictionary file must begin with one of the keywords listed in Table 57.

Editing .dct Dictionary Files

The product-specific files shipped with Steel-Belted Radius Carrier reflect specific vendors’ implementations of RADIUS clients. Therefore, you do not usually need to modify the .dct dictionary files shipped with Steel-Belted Radius Carrier. However, if your network access server vendor provides information about a new product, a new attribute, or a new value for an attribute, you can add this information to your existing Steel-Belted Radius Carrier configuration by editing dictionary files.

Note: If dictionary entries are changed after tunnel, user, or profile attributes have been entered, existing attributes may become no longer editable or orderable. To edit such attributes, delete and re-enter them. This is working as designed.

Before you edit an existing .dct dictionary file or create a new one, you must do the following to integrate your changes into Steel-Belted Radius Carrier:

1. Add a new vendor-product entry to vendor.ini so that you can reference the new dictionary while configuring Steel-Belted Radius Carrier.
2. Place your dictionary file in the same directory as the Steel-Belted Radius Carrier daemon.
3. Edit the dictiona.dcm file so that it includes your new dictionary file.
4. Stop and restart the server.

Include Records

Records in a .dct dictionary file that begin with the @ character are treated as special include records. The string that follows the @ character identifies the name of a .dct dictionary file whose contents are to be included. For example, the entry @vendorA.dct includes all of the entries in the file vendorA.dct.

Include records are honored only one level deep. For example, if file vendorA.dct includes file radbase.dct and radbase.dct includes radacct.dct, vendorA.dct incorporates records in radbase.dct but not those in radacct.dct.

Master Dictionary for .dct Files

The master dictionary dictiona.dcm consists of include records that reference vendor-specific dictionaries. The order in which vendor-specific dictionaries are included in the master dictionary has significance only if two vendor-specific dictionaries contain conflicting definitions for the same attribute or attribute value. The first definition of an attribute or attribute value takes precedence over later definitions of the same attribute or attribute value. For example, if master dictionary dictiona.dcm consists of the following include records:

@vendorA.dct
@vendorB.dct
@vendorC.dct

then attributes and attribute values defined in vendorA.dct override attributes and attribute values defined in vendorB.dct or vendorC.dct, and attributes and attribute values in vendorB.dct override attributes and values defined in vendorC.dct

ATTRIBUTE Records

Attribute records (Table 58) conform to the following syntax:

ATTRIBUTE attrib_name attrib_id syntax_type flags

Note: One limitation of standard dictionary files (the attrib_id of all the attribute records must be unique) is waived for the master dictionary file. Multiple vendors can define different attribute names for the same attribute identifier (assuming the attribute identifier is not already used in the base RADIUS specification). Because attributes in the Steel-Belted Radius Carrier database are stored by name (rather than by attrib_id), this introduces no ambiguity into the database.

The following example illustrates a typical attribute record:

ATTRIBUTE Framed-IP-Netmask 9 ipaddr Cr

This attribute record specifies all of the following:

• An attribute named Framed-IP-Netmask is supported.
• The attribute’s encoded RADIUS identifier is 9.
• The attribute must use the syntax of an IP address.
• Flag characters specify that the attribute can appear multiple times in a check list (C) and at most one time in a return list for User or Profile entries (r) in the Steel-Belted Radius Carrier database.

Attribute Name and Identifier

No two attribute records in a single dictionary file can have the same attrib_name or attrib_id. If a duplicate attrib_name or attrib_id is encountered, the later definition of the attribute is ignored in favor of the earlier one.

Syntax Type Identifier

Standard syntax_type identifiers are listed in Table 59.

Note: Signed integer support is limited to attributes received in packets and processing relating to those attributes, such as accounting logs, authentication logs, authentication reports, and SQL plug-ins. Web GUI does not support signed integers, and treats signed and unsigned integers as unsigned integers.

Compound Syntax Types

In addition to the standard syntax_type identifiers listed in Table 59, the dictionary can accommodate compound syntax types for use in defining vendor-specific attributes. Instead of a single syntax_type identifier, one or more of the options listed in Table 60 can be combined inside square brackets to form a compound syntax type.

An example of a vendor-specific attribute definition follows:

ATTRIBUTE vsa-xxx 26 [vid=1234 type1=1 len1=+2 data=string] R

Flag Characters

The flags setting consists of the concatenation of one or more flag characters from the list in Table 61.

VALUE Records

Value records (Table 62) are used to define names for specific integer values of previously defined integer attributes. Value records are never required, but are appropriate where specific meaning can be attached to an integer value of an attribute. The value record must conform to the following syntax:

VALUE attrib_name value_name integer_value

No two value records in a .dct dictionary file can have the same attrib_name and value_name or the same attrib_name and integer_value. If a duplicate is encountered, the later definition of the attribute value is ignored in favor of the earlier one (the earlier one is considered to be an override).

The following example illustrates the use of the VALUE record to define more user-friendly attribute values for the Framed-Protocol attribute:

ATTRIBUTE  Framed-Protocol     7     integer     Cr
VALUE      Framed-Protocol     PPP           1
VALUE      Framed-Protocol     SLIP          2

Using these dictionary records, the administrator need not remember that the integer value 1 means PPP and the integer value 2 means SLIP when used in conjunction with the Framed-Protocol attribute. Instead, the Steel-Belted Radius Carrier Administrator program lets you choose from a list of attribute values including PPP and SLIP.

Macro Records

Macro records (Table 63) are used to streamline the creation of multiple vendor-specific attributes that include many common parameters. A macro record can be used to encapsulate the common parts of the record. The macro record must conform to the following syntax:

MACRO macro_name(macro_vars) subst_string

The following example illustrates the use of a macro that simplifies the specification of multiple vendor-specific attributes:

MACRO Cisco-VSA(t, s) 26 [vid=9 type1=%t% len1=+2 data=%s%]
ATTRIBUTE Cisco-xxx Cisco-VSA(1, string) R
ATTRIBUTE Cisco-yyy Cisco-VSA(4, int4) C
ATTRIBUTE Cisco-zzz Cisco-VSA(9, ipaddr) r

The macro preprocessor built into the Steel-Belted Radius Carrier dictionary processing translates the records in the preceding example to the following records before being processed.

ATTRIBUTE Cisco-xxx 26 [vid=9 type1=1 len1=+2 data=string] R
ATTRIBUTE Cisco-yyy 26 [vid=9 type1=4 len1=+2 data=int4] C
ATTRIBUTE Cisco-zzz 26 [vid=9 type1=9 len1=+2 data=ipaddr] r

OPTION Records

By default, each vendor-specific attribute is encoded in a single VSA attribute. The format of a VSA attribute is described in Table 64.

The OPTION setting can be used to enable the attributes of a particular vendor ID to be bundled within a single VSA.

The OPTION record must conform to the following format:

OPTION bundle-vendor-id = vid

Note: You must set the B flag for attribute bundling to occur. For a particular vendor-specific attribute to be bundled, you must set the OPTION record for the vendor’s vendor-ID and set the B (or b) flag for the specific attribute.

The Nortel Rapport dictionary supports this option, for example. If you want to combine Nortel’s vendor-specific attributes in a single VSA, provide the entry:

OPTION bundle-vendor-id=562

This is because 562 is Nortel’s Vendor ID, as set in the MACRO record. The Nortel Rapport vendor-specific attributes now are concatenated within the vendor-data portion of a RADIUS VSA attribute (up to 249 octets).

.dic Files

The .dic dictionary files are the XML format of the .dct dictionary files. The .dic dictionary files identify the attributes SBR Carrier expects when receiving Diameter requests from a specific type of device or while sending a Diameter or CoA/DM requests to a specific type of device.

In the .dic file, the top level element must be tagged as <Dictionary>. The allowable child elements of the <Dictionary> element are <?dict>, <vendor>, and <attributes>. The following example illustrates the format of a .dic dictionary file.

<Dictionary>

<?dict import = "radius.dic" ?>

<vendor id = "WiMAX"    vid ="24757"/>

<attribute id = "WiMAX-Device-Authentication-Ind"    type = "2"    format = "integer"  vendor="WiMAX"  sensitive = "false">
<constant name = "Successful"    value = "1"/>
<constant name = "Unsucessful"    value = "2"/>
</attribute>

<attribute id = "WiMAX-GMT-Time-Zone-Offset"    type = "3"    format = "integer"  vendor="WiMAX"  sensitive = "false">
</attribute>

<attribute id = "WiMAX-AAA-Session-ID"    type = "4"    format = "octets"  vendor="WiMAX"  sensitive = "false">
</attribute>

</Dictionary>

.dic File Location

The .dic dictionary files must be placed in the same directory as the SBR Carrier daemon. During initialization, SBR Carrier reads the master file Dictionaries.xml in the server directory to get a list of files with an extension of .dic.

<?dict> Element

The <?dict> element is used to include the records of the specified .dic file. The only allowable XML attribute of the <Dictionary> element is import. Include records are honored only one level deep. For example, if the vendorA.dic file includes the diabase.dic file and diabase.dic includes diaacct.dic, then vendorA.dic incorporates records in diabase.dic but not those in diaacct.dic.

<vendor> Element

You can use the <vendor> element to streamline the creation of multiple vendor-specific attributes that include many common parameters. You may include multiple <vendor> elements for the <Dictionary> element. The allowable XML attributes of the <vendor> element are:

• id—Specifies the name of the vendor
• vid—Specifies the device manufacturer's SMI network management private enterprise code (assigned by ISO) in decimal form

<attribute> Element

The <attribute> element is used to define attributes for the .dic dictionary file. You may include multiple <attribute> elements for the <Dictionary> element, each of which provides supplemental details of an attribute in the .dic file. Table 65 lists the XML attributes allowed in the <attribute> element.

The <attribute> element may have <constant> child elements. The <constant> element defines a named value, which a simple attribute may have, for example:

<attribute id = "WiMAX-Device-Authentication-Ind"    type = "2"    format = "integer"  vendor="WiMAX"  sensitive = "false">
<constant name = "Successful"    value = "1"/>
<constant name = "Unsucessful"    value = "2"/>
</attribute>

Editing .dic Dictionary Files

The product-specific files shipped with SBR Carrier reflect specific vendors’ implementations of Diameter clients. Therefore, you do not usually need to modify the .dic dictionary files shipped with SBR Carrier. However, if your network access server vendor provides information about a new product, a new attribute, or a new value for an attribute, you can add this information to your existing SBR Carrier configuration by editing dictionary files.

Before you edit an existing .dic dictionary file or create a new one, you must do the following to integrate your changes into SBR Carrier:

1. Place your dictionary file in the same directory as the SBR Carrier daemon.
2. Edit the Dictionaries.xml master file so that it includes your new dictionary file.
3. Stop and restart the server.