Attributes and values are the basis of any RADIUS client or server.
Attributes, like User-Name, name a piece of information that can be
carried in a RADIUS packet. Values, like admin, are the information
itself. An A-V (attribute-value) pair is just an attribute and its
corresponding value, and is often written as User-Name = admin. In
OpenRADIUS, every action that you take in the behaviour file is defined
in terms of attributes and values.
A RADIUS server uses a dictionary file to convert between the numeric
attributes and values used in RADIUS packets and human-readable ones.
OpenRADIUS uses a modular dictionary, consisting of the file named
dictionary and the files in the directory subdicts. The
dictionary file is the main dictionary, and the files in subdicts
are sub-dictionaries. Usually, each sub-dictionary represents one vendor
(like Cisco or USR), one standard (like RFC 2866 or 2869), or one specific
situation (like authenticating with LDAP.)
In order to make OpenRADIUS work with your equipment, you will need to add
your vendor's attributes and values to a sub-dictionary. A few vendor
sub-dictionaries are included with the OpenRADIUS package, but in most
cases you will be starting from scratch. You should have some
documentation from your hardware vendor specifying which attributes and
values correspond to which numeric codes, or a prepared dictionary file.
OpenRADIUS's dictionary format is quite different from other servers', so
you won't be able to use a vendor-supplied dictionary as-is, but you will
use it as a base to create your own.
To get started, you will need to have your vendor's IANA-assigned numeric
ID, and the list of attributes with possible values. The first file to
edit is subdicts/dict.vendors, which is a list of vendor IDs. Add a
line for your vendor to the file, just above the line $addvendorxAny. You should use a brief, meaningful vendor name. For instance:
$add vendor 429 USR # Or 3Com
$add vendor 529 Ascend
$add vendor 9999 Example
$add vendor x Any
Here, we have added a line for the vendor named "Example", with a vendor ID
of 9999. You can now save and close the dict.vendors file.
The next file to edit is the main dictionary file. At around line 130,
you will see a list of lines starting with $addattribute26. Each of
these lines describes the way a given vendor encodes the data inside a
packet. Most vendors fall into the "Normal" classification, so we would
add a line like this: [This is not neccessary if the vendor indeed uses VSAs
that look like ordinary RADIUS attributes. The 'vendor=x' entry matches any
vendor, so if your vendor isn't listed above it, OpenRADIUS will encode and
decode the A/V pair according to the rules that apply in RAD-VSA-STD, which is
appropriate for most (sane) vendors. -- EvB, 2003/04/27]
Here, again, we have added a line for the "Example" vendor. The other
change you will need to make to dictionary is to include your
soon-to-be-created vendor sub-dictionary. Scroll down to around line 145,
where you will see lines starting with $includesubdicts/. To these
lines, add your vendor:
As usual, we have added the line for "example". The filename
dict.example was chosen for consistency, but you can name your
sub-dictionary anything you like.
The only remaining task is to create the sub-dictionary file itself.
Create a new file in the subdicts directory with the name you chose in
the previous step. The first line in your new sub-dictionary should set
the vendor for the rest of your file:
$set default vendor=Example
The vendor name that you use here must match the one that you added to the
dict.vendors file in the first step.
Next, you will define all of your attributes. It is common to use the
vendor's name in each attribute, to avoid duplicating attribute names from
the RADIUS standards or from other vendors. Defining attributes can be
complex, since each one has a type (either integer or string) and a length.
By default, OpenRADIUS will assume that your attributes have string values,
so you will need to note each one that has an integer value, and give the
length of that integer. This information should all be available from your
These lines define four attributes. The numeric codes used are defined by
the vendor documentation. Attributes 1 and 4 are, by default, string
attributes. String attributes have their length determined automatically.
Attributes 2 and 3 are integer attributes, whose length must be specified;
attribute 2 is a "short" integer, two bytes in length, and 3 is a "long",
or four-byte, integer. As you can see, the val_type option specifies
the type of attribute, and the val_size option specifies its length.
Once all of your attribute lines are written, you can add value lines.
Value lines are optional, but convenient, and serve to translate numeric
value codes into text values. For instance, they allow you to refer to
"Access-Accept" and "Access-Reject" instead of "code 2" and "code 3". To
specify values, use the following syntax:
$set default item=Example-Service-Level
$add value 1 Gold
$add value 2 Silver
$add value 3 Bronze
The first line specifies which item your values will apply to. Each
subsequent line defines one value code and its name. You can define values
for any integer attributes.
Once you have defined all of your values, save and close the sub-dictionary
file. You can now start using your new vendor configuration.