Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Dictionary Files

 

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.

.dct Files

.dct Files

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.

Figure 2: Sample Dictionary (.dct) File
Sample Dictionary (.dct) 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

Keyword

Function

@

Include the referenced file

ATTRIBUTE

Define a new attribute

VALUE

Define a named integer value for an attribute

MACRO

Define a macro used to simplify repetitive definitions

OPTIONS

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.

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

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:

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

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

ATTRIBUTE attrib_name attrib_id syntax_type flags

Table 58: ATTRIBUTE Record Syntax

Parameter

Function

attrib_name

Name of the attribute (up to 31 characters with no embedded blanks).

attrib_id

Integer in the range 0–255 identifying the attribute's encoded RADIUS identifier.

syntax_type

Syntax type of the attribute.

flags

Defines whether an attribute appears in the check list, the return list (or both), whether it is multi-valued and whether it is orderable.

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:

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

Syntax Type

Function

hexadecimal

Hexadecimal string.

int1

1-byte (8-bit) unsigned decimal number.

int2

2-byte (16-bit) unsigned decimal number.

int4, integer

4-byte (32-bit) unsigned decimal number.

signed-integer

4-byte (32-bit) signed decimal number. A number with a 1 in the first bit position is interpreted as a negative number.

ipaddr

IP address or IP netmask attribute.

ipaddr-pool

IPv4 address selected from an IP address pool.

string

String attribute (includes null terminator).

stringnz

String attribute (without null terminator).

time

Time attribute (number of seconds since 00:00:00 GMT, 1/1/1970).

constant

null-value attribute (2-octet) containing only type and length

ipv6addr

IPv6 address attribute (per RFC-3162)

ipv6prefix

IPv6 prefix attribute (per RFC-3162)

ipv6interface

IPv6 interface attribute (per RFC-3162)

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.

Table 60: Compound Syntax Types

Option

Function

vid=nnn

The device manufacturer's SMI Network Management Private Enterprise code (assigned by ISO) in decimal form.

typeN=nnn

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.

lenN=nnn

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).

fillN=nnn

Fill field setting for non-integer tunneled attributes; N specifies the size of the field to be filled with the value specified by nnn.

data=syntax_type

The actual data to be included in the attribute; the syntax can be any of the standard syntax types.

tag=nnn

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:

Flag Characters

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

Table 61: Flag Characters

Flag Character

Meaning

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.

c

Attribute can appear once within a user or profile checklist.

C

Attribute can appear multiple times within a user or profile checklist.

r

Attribute can appear once within a user or profile returnlist.

Include-auth-only

Indicates the attribute can be included in an Accept-Response to a WiMAX reauthentication.

R

Attribute can appear multiple times within a user or profile returnlist.

t

Attribute can appear once within a tunnel attribute list.

T

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).

salt-encrypt

Causes Steel-Belted Radius Carrier to salt-encrypt the attribute.

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

Table 62: VALUE Records

Parameter

Function

attrib_name

Name of the attribute (up to 31 characters with no embedded blanks)

value_name

Name of the attribute value (up to 31 characters with no embedded blanks)

integer_value

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:

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

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

Parameter

Function

macro_name

Name of the macro

macro_vars

One or more comma-delimited macro variable names

subst_string

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:

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.

OPTION Records

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.

Table 64: VSA Attribute Format

Bits

Content

0 - 7

Type: contains the value 26

8 - 16

Length of data in bytes

17 - 47

Vendor ID

48 - on

Vendor data

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:

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:

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

.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.

.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.

<?dict> Element

<?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

<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

<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.

Table 65: XML Attributes Allowed in the <attribute> Element

XML Attribute Name

Description

id

Specifies the identifying name of the attribute.

type

Specifies a unique integer type code of the attribute.

format

Specifies the data type of the attribute. This XML attribute can be set to:

  • string—String including null terminator (0–254 octets)

  • ipaddr6—IPv6 address (16 octets)

  • ipaddr—IP address (4 octets)

  • integer—4-byte (32-bit) unsigned decimal number

  • int8—8-byte (64-bit) unsigned decimal number

  • time—Number of seconds since 00:00:00 GMT, 1/1/1970

  • octets—Raw octets

sensitive

Specifies whether to print the attribute value in the server log file.

  • If set to true, the attribute value is not printed in the server log file.

  • If set to false, the attribute value is printed in the server log file.

tag

Specifies whether to include a tag field to the attribute.

  • If set to 1, a tag field is included to the attribute.

  • If set to 0, a tag field is not included to the attribute.

preserve

Specifies whether to format the tag field even if the tag attribute is set to 0.

  • If set to true, the packet builder always formats the tag field even if the tag attribute is set to 0.

  • If set to false, the packet builder omits the tag field if the tag attribute is set to 0.

vendor

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:

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:

  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.