Section 9. File formats

9.1. Dictionary file

The dictionary file defines easy-to-read names for the attributes and values used in RADIUS messages. It defines how RADIUS attribute numbers map to readable attribute names, and how RADIUS value numbers map to readable value names. The dictionary also defines the type of data that each attribute can hold.

The dictionary file is an ASCII text file. Each definition occupies one line. A hash mark # marks the beginning of a comment. Comment and blank lines are ignored.

9.1.1. ATTRIBUTE `attrname attrnum type [flags]`

This defines the name, RADIUS attribute number, and type for an attribute. Here is an example of attribute definition:

ATTRIBUTE Service-Type 6 integer

ATTRIBUTE is the keyword that says this is an attribute definition. Service-Type is the name of the attribute: the string that is used as the attribute name when printing the attribute and when setting attributes in the user database. 6 is the standard RADIUS attribute number for this attribute (see RFC 2865), and integer is the data type for this attribute. The supported data types are:

string
ASCII string of up to 253 bytes. Trailing NULs are stripped.
text
Similar to string
integer
32-bit unsigned value
signed-integer
32-bit signed value
integer8
8-bit unsigned value
integer16
16-bit unsigned value using network byte order
integer64
64-bit unsigned value using network byte order
date
Date as an integer number of seconds since 00:00:00 UTC Jan 1 1970
ipaddr
IP address in the form aaa.bbb.ccc.ddd, or a 4-byte binary string
ipaddrv6
IPv6 address in the form 2001:db8:148:100::31
ipaddrv4v6
4 or 16 octets long IPv4 or IPv6 (respectively) address in network byte order
binary
Binary data
abinary
Ascend filter, using the special Ascend filter definition syntax. Radiator is very strict about the syntax. You must follow the filter definition syntax exactly.
hexadecimal
Binary data formatted as hexadecimal
boolean
Required only by some Nortel/Aptis CVX vendor-specific attributes. A single byte attribute. Values of 0 or 1 are permitted.
tagged-integer
See Section 7.1.24. Tagged Tunnel attributes and other tagged attributes.
tagged-string
See Section 7.1.24. Tagged Tunnel attributes and other tagged attributes.
ipv4prefix
IPv4 prefix in the form 192.168.1.0/24
ipv6prefix
IPv6 prefix in the form 2001:db8:148:100::/64
ifid
IPv6 interface identifier in the form aaaa:bbbb:cccc:dddd
tlv
Encapsulation attribute that contains one or several attributes
custom
See Section 9.1.10. Using VSA framework for customised attributes for more about custom attribute VSA framework.

If you redefine an ATTRIBUTE by defining a new name for an previously defined attribute number, the new definition replaces the old one. The first is a synonym for the second when used in a reply.

attrnum may be in decimal, hex (prefixed by ‘0x’) or octal (prefixed by 0).

ATTRIBUTE also supports optional flags to control whether the attribute is tagged or requires encryption like this:

ATTRIBUTE Tunnel-Password 69 string has_tag,encrypt=2

The permitted flags are:

has_tag
Specifies that the encoded attribute is prefixed a tag octet. The value of the tag can be specified in an attribute value with a leading tag number and a colon.
encrypt=n (n = 1, 2 or 3)
Specified that the attribute is to encrypted with the specified algorithm. The following algorithms are supported:
1. RADIUS User-Password encryption
2. The SALT algorithm as described by RFC 2548
3. Symmetric encoding and decoding as required for Ascend-Send-Secret

9.1.2. VALUE `attrname valuename value`

This defines a symbolic name for an integer type attribute. When setting the value of an integer attribute in a check or reply item, you can use the symbolic name instead of the raw integer.

VALUE Service-Type Login-User 1

VALUE is a keyword that says this is a value definition. Service-Type means that this is a definition of a value for the Service-Type attribute (which should be of type integer). Login-User is the symbolic name for the value, and 1 is the value that Login-User translates to. value may be in decimal or hex (prefixed by ‘0x’).

If you redefine a VALUE by defining a new name for a previously defined value number, the new definition will silently replace the old one. The first will be a synonym for the second when used in a reply.

9.1.3. VENDORATTR `vendornum attrname attrnum type [flags]`

This defines a vendor-specific attribute. RADIUS defines a special attribute number 26 that can be used to hold any vendor defined data type. This allows NAS vendors to add their own NAS-specific codes.

VENDORATTR 9 cisco-avpair 1 string

VENDORATTR is a keyword that says this is a vendor-specific attribute definition. 9 is the SMI Network Management Private Enterprise Code of the vendor (Cisco in this example). cisco-avpair is the symbolic name for the attribute, and string is the data type. The same data types as for ATTRIBUTE are supported. Radiator supports both hex and decimal attribute numbers in VENDORATTR.

After an integer VENDORATTR is defined, you can have VALUE definitions in the same format as for other ATTRIBUTES.

If you redefine a VENDORATTR by defining a new name for an previously defined vendor attribute number, the new definition will silently replace the old one.

attrnum may be in decimal, hex (prefixed by ‘0x’) or octal (prefixed by 0).

VENDORATTR also supports the same optional flags. For more information, see Section 9.1.1. ATTRIBUTE attrname attrnum type [flags].

9.1.4. VENDOR `vendorname vendornumber`

Specifies that the decimal number vendornumber can be used to refer to the Vendor given by vendorname.

9.1.5. BEGIN-VENDOR`vendorname [parent=attributename]`

Specifies that all subsequent ATTRIBUTE keywords, until the next END-VENDOR are to be interpreted as VENDORATTR definitions for the named vendor.

The optional parent=attributename syntax is needed when Vendor-Specific attributes from extended space, as defined by RFC 6929, are used. The following example shows how to define a Vendor-Specific Attribute named OSC-Uid and an Extended-Vendor-Specific Attribute named OSC-Extended-Example. These both use Vendor-Id 9048 and Vendor-Type 1. The full "dotted number" notation that uniquely identifies OSC-Extended-Example is 241.26.9048.1. The unique identifier of OSC-Uid Vendor-Specific Attribute is 26.9048.1.

VENDOR OSC 9048

VENDORATTR 9048 OSC-Uid 1 string

BEGIN-VENDOR OSC parent=Extended-Vendor-Specific-1

ATTRIBUTE OSC-Extended-Example 1 string

END-VENDOR

Tip

For backwards compatibility, format=attributename is also allowed. The exact syntax used by different implementations is still evolving.

9.1.6. END-VENDOR

Terminates the previous BEGIN-VENDOR.

9.1.7. include `filename`

Includes the dictionary file specified by filename. Special characters are supported.

9.1.8. $INCLUDE `filename`

FreeRRADIUS style include command, includes the dictionary file specified by filename. Relative filenames are relative to the directory of the current dictionary. Special characters are not supported.

9.1.9. Available dictionaries

Radiator comes with a single main dictionary, plus an optional add-on dictionaries.

dictionary
The is the normal and default one. It merges attribute definitions from several sources, and should be satisfactory for most configurations.
dictionary.ascend
This is an add-on dictionary that includes definitions for some old-fashioned Ascend non-vendor-specific attributes that would normally conflict with newer attributes. If you need these old attributes, you can specify it as a second dictionary.
dictionary.* and goodies/dictionary.*
These dictionary files have more attributes for special cases. See the individual files for more details.

Under very unusual circumstances, you may wish to modify your dictionary. In any case, your dictionary must have entries for at least the following attributes, which are referred to by name in the radiusd code.

User-Name
User-Password
Acct-Delay-Time
Any other attributes that are required by your check and reply item configuration.

Wherever possible, use the default dictionary: it will work with the vast majority of cases. If you are operating with NASs from only one vendor, choose the default dictionary, or dictionary for that vendor. If you are operating in a mixed environment, use the default dictionary. If that does not work for you, try concatenating the dictionaries for the vendors you are using into one big dictionary or use DictionaryFile parameter to load the dictionaries as separate files.

If you need to add or modify attributes or other dictionary entries, we recommend adding them to your own site-specific dictionary, and then add that dictionary to the list of dictionaries given by the DictionaryFile parameter in your configuration file. See Section 3.7.16. DictionaryFile.

Whichever dictionary you choose to use, you should place it in the directory where radiusd expects to find it before starting radiusd. You should also be careful to specify the same dictionary to radpwtst with the -dictionary argument if you use it for testing.

9.1.10. Using VSA framework for customised attributes

Radiator supports using customised attributes. Currently there are some ready, customised modules available in Radiator Service Provider Module. For more information, see Radiator Service Provider Module

.

9.2. Flat file user database

Flat file user databases are used to list all the legitimate users for the <AuthBy FILE> module. You can also use flat file user databases as input to the builddbm and buildsql utility to create a DBM user database. See the users file in the Radiator distribution for an example.

Flat file user databases are ASCII text files containing zero or more user definitions. Lines beginning with ‘#’ are ignored. Each user definition is one or more lines. The first line must start with the user name in the first column. Subsequent lines for the user must begin with white space.

User names are quoted with double quotes (") if they contain white space. The user name must be followed by white space, followed by zero or more check items. Each check item is in the form Attribute = Value, and it defines a RADIUS attribute that is checked in Access-Requests before the user is authenticated. Multiple check items are separated by commas. There must be no comma after the last check item in the line. Values may optionally be surrounded by double quotes, which are ignored. For more information about check items, see Section 7. Check and reply items.

The second and subsequent lines are ‘reply’ items. Each line must commence with white space. Each reply item is in the form “Attribute = Value”, and it defines a RADIUS attribute that are returned to the NAS if the authentication succeeds. Such reply items are generally used to configure the NAS for the user. Each reply item must have a trailing comma (‘,’) except the last item on the last line. Values may optionally be surrounded by double quotes, which are ignored. Reply item values support special formatting characters, see Section 3.3. Special formatters.

The following figure shows an example, if the user mikem is granted access, the modem is configured for Framed-Protocol of PPP, and IP netmask of 255.255.255.0, Framed-Routing of None and a Framed-MTU of 1500.

Figure 5. Typical user entry in a flat file user database

9.3. DBM user database

DBM user database file is in similar format to the DBM files supported by Merit and other RADIUS servers. Entries are hashed by user name, which is unique. Each user entry consists of two strings separated by newline characters. The first line is a list of comma separated Check items in the form “Attribute = Value”. The second line is a list of comma separated Reply items in the form “Attribute = Value”. During authentication, the check and reply items are used in exactly the same way as for a Flat file user database. For more information, see Section 7. Check and reply items.

Radiator will choose the best format of DBM file available to you, depending on which DBM modules are installed on your machine. (Hint: You can force it to choose a particular format by using the DBType parameter, and by using the -t flag with builddbm).

You can convert a flat file user database directly into a DBM user database with builddbm utility, and you can also use builddbm to print the attributes for a particular user. You can convert a DBM user database into an SQL database with the buildsql utility.

A DBM database can have multiple DEFAULT users. During authentication, if no user name is found in the DBM database, the DEFAULT users will be tried in the order that they appeared in the input file, until a match is found. Technical Note: when the DBM file is built from a flat file, the first DEFAULT user encountered is added to the DBM file with the name DEFAULT. The seconds and subsequent DEFAULT entries are added as DEFAULT1, DEFAULT2 etc. Therefore the uniqueness and order of DEFAULT users in the database is guaranteed.

9.4. Unix password file

A Unix password file as understood by the AuthBy UNIX module is an ASCII file consisting of one line per user. There are at least 2 colon (:) separated fields per line. The first field is the user name, and the second is the crypt(3) encrypted password. The third and subsequent fields (if they are present) are ignored.

It will be recognised that this description fits the standard Unix password file format, and Radiator will work with /etc/password on Unix implementations that do not use a password shadow file. It will work with /etc/shadow on Unix implementations that do use a password shadow file (Radiator will need to run as root to get read access to /etc/shadow).

9.5. Accounting log file

The accounting log file is used to store the details of every Accounting-Request received for a Realm if the AcctLogFileName parameter is defined for the Realm. It is an ASCII text file with each entry occupying one or more lines and followed by a blank line. The log file format is identical to the format used by Livingston and other RADIUS servers. The first line gives the date and time the request was received by the server. The subsequent lines give the values for every attribute in the request. Every Accounting-Request, regardless of Acct-Status-Type is stored in the log file.

Figure 6. Typical accounting log file entry

9.6. Password log file

The Password log file is useful for your help desk to diagnose user's login problems. It is only written if you define PasswordLogFileName for a Realm. It is an ASCII text file containing the results of password checks, one check per line. Each line contains 5 colon (:) separated fields:

time:seconds:user:submitted_password:correct_password:result

The time is the full date time string, seconds is the number of seconds since January 1 1970 (Unix epoch). Result is the word "PASS" or "FAIL". For example:

Mon Jun 29 12:24:21 1999:899087061:mikem:fredd:fred:FAIL
Mon Jun 29 12:24:38 1999:899087078:mikem:fred:fred:PASS
Mon Jun 29 12:38:53 1999:899087933:mikem:fred:fred:PASS

The file is opened, written and closed for each entry, so it can be safely rotated at any time.

9.7. Portlist file

A port list file contains a list of permitted NAS address/port combinations that are permitted for a user or group of users. It is used by the NAS-Address-Port-List check item. It is an ASCII file, with two white space separated fields. The first field is the NAS address (either as a DNS name or IP address). The second field contains the lower and upper permitted port numbers in the format “lowport-highport”. Blank lines and lines starting with hash (‘#’) are ignored. You can have any number of entries for each NAS, and any number of NASs.

Note

iPASS roaming users do not get their real NAS Address sent to Radiator. Radiator considers these to be address 0.0.0.0 for the purposes of NAS-Address- Port-List.

# Users can log into ports 1-10 and 21-30 inclusive
# on 10.1.1.1 or into ports 100 to 115 inclusive on
# 10.1.1.2, or into ports 16 to 20 inclusive on
# mynas.domain.com 
10.1.1.1 1-10
10.1.1.1 21-30
10.1.1.2 100-115
mynas.domain.com 16-20
# For iPASS roaming:
0.0.0.0 0-1000

9.8. Group membership file

This file contains a list of groups and their members. <AuthBy FILE> uses these groups and the group file is defined with GroupFilename parameter. For more information, see Section 3.35.2. GroupFilename.

The format of group membership file has first the name of the group and then a comma-separated list of users that belong to that group. One user can belong to one or several groups.

Here is an example of a group membership file:

Admin-group username1

WiFiClient-group username1, username2, username3

Readonly-group username4, username5

9. File formats