For each product listed in the vendor.ini file, Steel-Belted Radius Carrier provides .dct (text) and .dic (xml) dictionary files. Dictionary files enable Steel-Belted Radius Carrier to exchange attributes with RADIUS or Diameter clients. Like initialization files, dictionary files are loaded at startup time, and reside in the Steel-Belted Radius Carrier directory.
The .dct dictionary files identify the attributes Steel-Belted Radius Carrier expects when receiving RADIUS requests from a specific type of device. The .dct dictionary files also identify the attributes Steel-Belted Radius Carrier includes when sending a RADIUS response to a specific type of device. Figure 2 illustrates the format of a dictionary file.
.dct File Location
.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
.dct File Records
Records in a .dct dictionary file must begin with one of the keywords listed in Table 57.
Table 57: Dictionary File Keywords
Include the referenced file
Define a new attribute
Define a named integer value for an attribute
Define a macro used to simplify repetitive definitions
Define options beyond the scope of attribute definitions
Ignore this text (comment)
Editing .dct Dictionary Files
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.
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:
Add a new vendor-product entry to vendor.ini so that you can reference the new dictionary while configuring Steel-Belted Radius Carrier.
Place your dictionary file in the same directory as the Steel-Belted Radius Carrier daemon.
Edit the dictiona.dcm file so that it includes your new dictionary file.
Stop and restart the server.
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 (Table 58) conform to the following syntax:
ATTRIBUTE attrib_name attrib_id syntax_type flags
Table 58: ATTRIBUTE Record Syntax
Name of the attribute (up to 31 characters with no embedded blanks).
Integer in the range 0–255 identifying the attribute's encoded RADIUS identifier.
Syntax type of the attribute.
Defines whether an attribute appears in the check list, the return list (or both), whether it is multi-valued and whether it is orderable.
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.
Table 59: Syntax Type Identifiers
1-byte (8-bit) unsigned decimal number.
2-byte (16-bit) unsigned decimal number.
4-byte (32-bit) unsigned decimal number.
4-byte (32-bit) signed decimal number. A number with a 1 in the first bit position is interpreted as a negative number.
IP address or IP netmask attribute.
IPv4 address selected from an IP address pool.
String attribute (includes null terminator).
String attribute (without null terminator).
Time attribute (number of seconds since 00:00:00 GMT, 1/1/1970).
null-value attribute (2-octet) containing only type and length
IPv6 address attribute (per RFC-3162)
IPv6 prefix attribute (per RFC-3162)
IPv6 interface attribute (per RFC-3162)
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.
Table 60: Compound Syntax Types
The device manufacturer's SMI Network Management Private Enterprise code (assigned by ISO) in decimal form.
Type setting for vendor-specific attribute as defined in the RADIUS specification; N specifies the length of the field (in bytes), nnn specifies the decimal value of the field.
Length field for vendor-specific attribute as defined in the RADIUS specification; N specifies the length of the field (in bytes), nnn specifies the decimal value of the field (a plus sign before the value indicates that the length of the data portion is to be added to nnn to obtain the actual length).
Fill field setting for non-integer tunneled attributes; N specifies the size of the field to be filled with the value specified by nnn.
The actual data to be included in the attribute; the syntax can be any of the standard syntax types.
Tunnel attributes include a tag field, which may be used to group attributes in the same packet which refer to the same tunnel. Since some vendors' equipment does not support tags, this syntax type is optional and must be present for the attribute to include a tag field.
A value of 0 indicates that the field is present but ignored.
An example of a vendor-specific attribute definition follows:
ATTRIBUTE vsa-xxx 26 [vid=1234 type1=1 len1=+2 data=string] R
The flags setting consists of the concatenation of one or more flag characters from the list in Table 61.
Table 61: Flag Characters
b or B
Indicates that an attribute may be bundled in a single Vendor-Specific-Attribute for a particular vendor id. It may be included as one of a series of subattributes within a single VSA.
Note: The bundled option must be specified in all dictionaries that use the same Vendor ID.
Attribute can appear once within a user or profile checklist.
Attribute can appear multiple times within a user or profile checklist.
Attribute can appear once within a user or profile returnlist.
Indicates the attribute can be included in an Accept-Response to a WiMAX reauthentication.
Attribute can appear multiple times within a user or profile returnlist.
Attribute can appear once within a tunnel attribute list.
Attribute can appear multiple times within a tunnel attribute list.
o or O
Attribute is orderable; the administrator can control the order in which such attributes are stored in the Steel-Belted Radius Carrier database (this flag makes sense only for multi-valued attributes).
Causes Steel-Belted Radius Carrier to salt-encrypt the attribute.
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
Table 62: VALUE Records
Name of the attribute (up to 31 characters with no embedded blanks)
Name of the attribute value (up to 31 characters with no embedded blanks)
Integer value associated with the attribute 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 (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
Table 63: MACRO Records
Name of the macro
One or more comma-delimited macro variable names
String into which macro variables are to be substituted; any sequence of characters conforming to the format %x % for which a macro variable called x has been defined undergo the substitution process
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
By default, each vendor-specific attribute is encoded in a single VSA attribute. The format of a VSA attribute is described in Table 64.
Table 64: VSA Attribute Format
0 - 7
Type: contains the value 26
8 - 16
Length of data in bytes
17 - 47
48 - on
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
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:
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).
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
.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.
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.
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
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.
Table 65: XML Attributes Allowed in the <attribute> Element
XML Attribute Name
Specifies the identifying name of the attribute.
Specifies a unique integer type code of the attribute.
Specifies the data type of the attribute. This XML attribute can be set to:
Specifies whether to print the attribute value in the server log file.
Specifies whether to include a tag field to the attribute.
Specifies whether to format the tag field even if the tag attribute is set to 0.
Specifies the vendor ID of the attribute if it is a VSA,
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
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:
Place your dictionary file in the same directory as the SBR Carrier daemon.
Edit the Dictionaries.xml master file so that it includes your new dictionary file.
Stop and restart the server.