dictionary(5)

💖 dictionary(5) — the RADIUS dictionary file, bestie edition 💖

File Formats Manual · dictionary 🦋

---

✨ NAME ✨

dictionary — the RADIUS dictionary file, aka the little translator that keeps your whole server from spiraling 💅

---

🌸 DESCRIPTION 🌸

okay so. the master RADIUS dictionary file lives at /etc/raddb/dictionary. it's the main character, and it pulls in a bunch of other dictionary files that hang out in /usr/share/freeradius/. every dictionary file is basically a list of RADIUS attributes and values, and your server uses them to map between cute descriptive names and the raw on-the-wire data. and like, the names? they mean nothing outside the RADIUS server itself. they are literally never exchanged between server and clients. not once. no cap. 🙈

so bestie, hear me when i say this:

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 RADIUS clients, and will not make RADIUS clients magically understand those attributes.

the dictionaries exist solely for local administrator convenience, and they're specific to each version of FreeRADIUS. that's it. that's the whole vibe. 💀

the dictionaries in /usr/share SHOULD NOT be edited unless you know exactly what you are doing. changing them will most likely break your RADIUS deployment. like, break it break it. 😭

if you need to add new attributes, please edit the /etc/raddb/dictionary file instead. its sole purpose is to contain site-local definitions that are added by the local administrator. it was literally born for this. 🎀

---

🌈 FORMAT 🌈

every line that starts with a hash sign ('#') is treated as a comment and ignored. she's not part of the conversation, she's just vibing in the background. 💅

each line of the file can contain one of the following strings:

👑 ATTRIBUTE name oid type [flags]

define a RADIUS attribute name to number mapping. iconic behavior.

the name field is a printable field, taken from various specifications or vendor definitions. it's most commonly used as a series of words, separated by hyphens. e.g. "User-Name". Vendor-specific attributes (VSAs) are prefixed by the vendor name, e.g. "Cisco-AVPair". the names should be globally unique, since they're used as a key to look up the properties of the attribute. unique names only, bestie, no duplicates allowed at this function. 💅

the oid field is taken from the relevant specification for that name. in most cases it's a decimal number, such as "256". for certain attributes, a "dotted number" notation is used, e.g. "1.2". the "dotted number" notation is used only for certain attributes. it's exclusive like that. 🦋

the type field can be one of the standard types:

• string — UTF-8 printable text (the RFCs call this "text")
• octets — opaque binary data (the RFCs call this "string")
• ipaddr — IPv4 address
• date — Seconds since January 1, 1970 (32-bits)
• integer — 32-bit unsigned integer
• ipv6addr — IPv6 Address
• ipv6prefix — IPV6 prefix, with mask
• ifid — Interface Id (hex:hex:hex:hex)
• integer64 — 64-bit unsigned integer

the type field can also be one of the following non-standard types:

• ether — Ethernet MAC address
• abinary — Ascend binary filter format
• byte — 8-bit unsigned integer
• short — 16-bit unsigned integer
• signed — 31-bit signed integer (packed into 32-bit field)
• tlv — Type-Length-Value (allows nested attributes)
• ipv4prefix — IPv4 Prefix as given in RFC 6572.

the last (optional) field of an attribute definition is additional flags for that attribute, in a comma-separated list. previous versions of the server allowed these flags to include a vendor name. this behavior may still work, but it is deprecated, and is not recommended. like, we don't do that anymore, babe. 🙈

the options are:

• array — Multiple values are packed into one attribute.
• concat — Multiple attributes should be concatenated
• encrypt=# — set encryption type 1, 2, or 3.
• has_tag — The attribute can have an RFC 2868 style tag
• secret — A value which should not be printed in debug mode
• virtual — The attribute is special to the server.

the "array" flag is only used for DHCP. it indicates that a DHCP option can contain an array of multiple values. 🍓

the "concat" flags indicates that when multiple attributes are present in a packet, the contents should be concatenated together to get the final contents. similarly, when encoding packets, a long value should be split into multiple attributes. it's giving teamwork. 🫶

the "encrypt" flag marks the attribute as being encrypted with one of three possible methods:

• "1" means that the attribute is encrypted with the method as defined in RFC2865 for the User-Password attribute.
• "2" means that the password is encrypted with the method as defined in RFC2868 for the Tunnel-Password attribute.
• "3" means that the attribute is encrypted as per Ascend's definitions for the Ascend-Send-Secret attribute.

the "has_tag" flag marks the attribute as being permitted to have a tag, as defined in RFC2868. the purpose of the tag is to allow grouping of attributes for tunneled users. see RFC2868 for more details. 🧚

the "secret" flag indicates that the value should not be printed in normal debug mode. the value will be printed when the debug level is 3 or higher. so like, it's secret but not secret-secret. iykyk. 🤫

the "virtual" flag is for the server, and indicates that the attribute does not really exist. instead, the value is taken from an internal callback. she's not real but she's still showing up. main character energy. 👑

when the server receives an encoded attribute in a RADIUS packet, it looks up that attribute by number in the dictionary, and uses the definition found there for printing diagnostic and log messages. when the server sees an attribute name in a configuration file, it looks up that attribute by name in the dictionary, and uses the definition found there. two lookups, both slay. ✨

💜 VALUE attribute-name value-name number

define an attribute value name to number mapping, for an attribute of type integer. the attribute-name field MUST be previously defined by an ATTRIBUTE entry — no skipping ahead, bestie. the value-name field can be any non-space text, but is usually taken from RFC2865, or other documents.. the number field is also taken from the relevant documents, for that name.

when the server receives an encoded value in a RADIUS packet, it looks up the value of that attribute by number in the dictionary, and uses the name found there for printing diagnostic and log messages. 💅

🌸 VENDOR vendor-name number [format=...]

define a Vendor Specific Attribute encapsulation for vendor-name to number. for a list of vendor names and numbers, see http://www.iana.org/enterprise-numbers.txt.

the "format=t,l" statement tells the server how many octets to use to encode/decode the vendor "type" and "length" fields in the attributes. the default is "format=1,1", which does not have to be specified. for USR VSA's, the format is "format=4,0", for Lucent VSA's it's "format=2,1", and for Starent VSA's it's "format=2,2". every vendor has her own little format moment. 🎀

the supported values for the number of type octets (i.e. the first digit) are 1, 2, and 4. the support values for the number of length octets (i.e. the second digit) are 0, 1, and 2. any combination of those values will work. mix and match, go off. 🔥

🦋 BEGIN-VENDOR vendor-name

define the start of a block of Vendor-Specific attributes. all of the following ATTRIBUTE definitions are interpreted as being for the named vendor, until the block is closed by an "END-VENDOR" statement.

this practice is preferred to placing the vendor name at the end of an ATTRIBUTE definition. do it the cute way. 💅

for VSAs in the RFC 6929 "Extended vendor-specific" space, a format can be specified following the "vendor-name". the format should be "format=Extended-Vendor-Specific-1", through "format=Extended-Vendor-Specific-6". the matching "END-VENDOR" should just have the "vendor-name", without the format string. no format at the goodbye, bestie. 🫶

🌟 END-VENDOR vendor-name

end a previously defined BEGIN-VENDOR block. the "vendor-name" must match. no mismatched goodbyes, that's not the vibe. 😭

🍓 $INCLUDE filename

include dictionary entries from the file filename. the filename is taken as relative to the location of the file which is asking for the inclusion. it's like tagging your bestie into the group chat. 💖

💀 BEGIN-TLV name

this feature is supported for backwards compatibility with older dictionaries. it should not be used. the new "oid" form for defining the attribute number should be used instead. respectfully, retire her. 🙈

💀 END-TLV name

this feature is supported for backwards compatibility with older dictionaries. it should not be used. the new "oid" form for defining the attribute number should be used instead. same energy, same warning. 🧚

---

🎀 FILES 🎀

• /etc/raddb/dictionary
• /usr/share/freeradius/dictionary.*

---

⭐ SEE ALSO ⭐

radiusd(8), RFC2865, RFC2866, RFC2868 RFC6929

---

and that's the whole page, bestie!! this one is from the <strong>05 Jan 2025</strong> era, brought to you by the FreeRADIUS corner of the File Formats Manual. go forth and edit /etc/raddb/dictionary like the responsible local administrator icon you are 💅✨