by Mark Johnston

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 $add vendor x Any. 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 $add attribute 26. 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]

$add attribute 26 Normal-VSA vendor=Microsoft subspace=RAD-VSA-STD
$add attribute 26 Normal-VSA vendor=Example subspace=RAD-VSA-STD
$add attribute 26 Normal-VSA vendor=x subspace=RAD-VSA-STD

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 $include subdicts/. To these lines, add your vendor:

$include subdicts/dict.cisco
$include subdicts/dict.example
#$include subdicts/dict.microsoft

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 vendor documentation.

Attribute lines should look like the following:

$add attribute 1  Example-Firmware-Version
$add attribute 2  Example-Service-Level  val_type=Integer val_size=2
$add attribute 3  Example-Priority       val_type=Integer val_size=4
$add attribute 4  Example-User-Token

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.

Generated on Sat Jul 2 01:18:04 2011 by decorate.pl / menuize.pl