File Format

As stated previously, the dictionary file format has not been standardized; it is unique to each server implementation.

Each dictionary file is composed of a series of lines of text. Similarly to the other configuration files, comments may be added via the via hash or pound character (#). Each line starts with a keyword that instructs the server how to interpret the rest of the line, which consists of a series of strings separated by spaces. The format and interpretation of the strings are defined differently for each keyword.

The keywords and their descriptions are given below. When the server loads a dictionary file, it creates both forward and reverse mappings for each entry. That is, names can be used to find numbers and numbers can be used to find names, subject to the restrictions described below:

  • ATTRIBUTE attribute-name number type

    • Defines a dictionary mapping and type for an attribute.

  • VALUE attribute-name value-name number

    • Defines an enumerated value for an attribute.

  • VENDOR vendor-name number

    • Defines a dictionary mapping for a vendor.

  • BEGIN-VENDOR vendor-name

    • Starts a block of attributes that are all managed by the named vendor.

  • END-VENDOR vendor-name

    • Ends a block of attributes that are all managed by the named vendor.

  • $INCLUDE filename

    • Includes another dictionary file as if its contents were inserted in place of the $INCLUDE line.

The field names given above should be in the format of words separated by dashes, such as "Foo-Bar". The numbers assigned to a name are usually defined in standards documents and are decimal integers. The attribute types are predefined names, such as integer or string.

To maintain backward compatibility, the dictionaries distributed with FreeRADIUS often define multiple names for the same attribute number. The reason for this repetition is that some attributes have been re-named as later RFCs obsolete earlier ones, and the old names may still be used in some configuration files. This multiple definition leads us to explain some of the additional validation and usage rules surrounding dictionaries.

The following rules define how multiple and/or conflicting definitions are handled:

  • Multiple names can be defined to map to the same number for "ATTRIBUTE"s, "VALUE"s, and "VENDOR"s

  • The last name defined is used when doing number-to-name lookup.

  • If an entry has multiple names defined, any of those names can be used in the configuration files to refer to that number.

  • Multiple names can be defined for ATTRIBUTEs only when all of the properties are identical (e.g., they have to be of the same data type, etc.).

  • VALUEs can only be used for integer attributes. They cannot be used for strings, IP addresses, or other data types.

It is important to read this section in it’s entirety before writing custom dictionaries. Many considerations must be taken into account when creating a dictionary. If something is missed or overlooked, the dictionaries will not work or may even break the server. The remainder of this chapter describes the various types of diction entries in detail and finishes with a guide to creating your own dictionaries. As always, it is suggested that the system man pages for the dictionary files and the comments in the dictionary files themselves be read as well.