Dictionaries
The dictionary files define names, numbers, and
data types for use in the server. In general,
the dictionary files are defined by industry standard specifications,
or by a vendor for their own equipment.
Each dictionary file contains a list of protocol-specific attributes and values, which the server uses to map between descriptive names and on-the-wire data. The names have no meaning outside of the server, and (with rare exception) are never sent "on the wire" between server and clients.
That is, editing the dictionaries will have no effect on anything other than the server that is reading those files. Adding new attributes to the dictionaries will have no effect on clients, and will not make clients magically understand those attributes. The dictionaries are solely for local administrator convenience, and are specific to each version of FreeRADIUS.
The dictionary files in the share directory should not be edited.
Editing those files will likely break the server.
Instead, you can add local dictionary definitions in the raddb/dictionary file.
Concepts and Background
The dictionaries are necessary because many networking protocols do not send humanly-readable names over the network. Instead, the protocols send sequences of bytes to represent concepts, where each byte has a particular meaning.
At the same time, it is useful for administrators to write policies
based on names, and not on numbers. No one wants to write a policy of
the form if concept 15 has value "foo", then do ….
The dictionaries solve this problem by enabling the server to decode
the magic numbers into humanly-readable names. The administrator can
then write policies of the form if the User-Name has value "bob",
then do something ….
Policies using descriptive are much simpler to create and understand than policies using numbers.
The dictionaries also enable the server to decode protocols using
data types, and then present that decoded data
to the administrator. As with the other examples above, it would be
very difficult write policies based on "raw hex" data: if User-Name is 0x626f62 ….
The dictionaries solve the data type problem by associating
data types with a name and number. That way the
bytes 0x7f000001 can be presented to the administrator as an IPv4
address of 127.0.0.1.
This association is two-way, protocols can get decoded to understandable names and data types, and those names and data can get encoded in protocols.
Dictionaries are always local
In almost all cases, the names defined in a dictionary have no meaning outside of the server. The names are never sent "on the wire" between server and client. Editing the dictionary names on one system will not change the names used by another system.
The names are also local to each implementation. FreeRADIUS has chosen a set of names for itself, which are based on specifications and on vendor definitions. In nearly all cases, these names are either the same as the external definition, or are very similar to the external definition.
In general, the only reason for us to change the names is that the names conflict with another name. It is not possible to have the same name mean two entirely different things.
Names are Case-insensitive
When names are printed, they are printed as the name given in the dictionaries. When a name is looked up in the dictionaries, the lookup is done in a case-insensitive manner.
Names are Hierarchical
In earlier versions of FreeRADIUS, the names were global. The global
names for attributes caused issue with implementations, as noted in
RFC 6929
Section 2.7.1. This limitation caused the names to be long, and have
"vendor prefixes", such as with Cisco-AVPair.
The names in FreeRADIUS are now hierarchical. In most cases, the old
names are simply split into separate sub-names with a period (.).
For example, the previously mentioned Cisco-AVPair now becomes
Cisco.AVPair., or Vendor-Specific.Cisco.AVPair.
If there is still a need to use the old names, the
ALIAS keyword can help. See
raddb/dictionary for additional documentation.
Files and Location
The dictionaries are placed into a share directory, which is usually
in a location such as /usr/share/freeradius/. The definitions for
each individual specification or vendor dictionary are placed in files
with the appropriate name. For example, dictionary.rfc2865 or
dictionary.cisco.
We reiterate that these dictionaries should not be edited. These dictionaries ship with the server, and any new installation (or upgrade) will over-write local changes.
Local edits should be kept to the raddb/dictionary file, which will
not be overwritten on an upgrade.
File Syntax
The dictionary file format follows the standard RADIUS dictionary syntax. In many respects, the format has had only minor changes since the original Livingston RADIUS server in 1993.
The file format is simple, and line-oriented. Blank lines are
ignored. Hash (#) characters are comments, and cause everything
after the hash character to be ignored, up to the end of the line.
Every non-blank line starts with a keyword, as given in the table below. In most cases, the main keywords of interest are ATTRIBUTE and VALUE.
| Keyword | Description |
|---|---|
Define a name which references an |
|
Define a name, number, and data type mapping |
|
Define a name and data type mapping |
|
Define a named enumeration of values for use with multiple |
|
Set flags for subsequent definitions |
|
Include another dictionary file |
|
Define a member of a |
|
Define a protocol like |
|
Define a structure which can contain |
|
Define a name for a particular value of an |
|
Define a name and number for a vendor |
The following keywords define logical nesting of attributes.
| BEGIN-PROTOCOL | Begin defining a protocol dictionary |
|---|---|
End a protocol dictionary |
|
Begin defining children of a structural data type |
|
End defining children of a structural data type |
|
Begin defining vendor-specific attributes |
|
End defining vendor-specific attributes |