User File Format

A User File is a text file that contains profiles–also known as records or entries–for individual users, DEFAULT users, and possibly templates. A profile consists of an index-key , zero or moreCheck-Items (access tests) and zero or more Reply Items (session configuration parameters). Instead of or in addition to the check and reply items, the profile may contain a reference to the name of a template profile from which additional Check-Items and/or Reply Items can also be read in another instance of the ReadUserFile plug-in. Check items and reply items consist of Attribute = Value pairs (AVP), where the Attribute is often a RADIUS dictionary attribute but may also define a NavisRadius variable or refer to some internal setting.

The NavisRadius ReadUserFile plug-in searches through the User File for information needed to authenticate and authorize the user and properly configure a user's session. There are certain formatting conventions that must be followed for the User File to be read correctly. (See the ReadUserFile plug-in documentation for more information about using this plug-in.)

File Format Notes

NavisRadius supports an enhanced text file format for storing user configuration information. This format is generally similar to the user files found in common Freeware RADIUS servers.

Special Characteristics

The following lists the special characteristics of the user file format:

Use of the backslash character (\) as a line continuation character to allow long lines to wrap for better readability.
Use of inline comments by placing the pound sign (#) comment character anywhere in a line. Any text following the pound sign to the end of the line is ignored.
Use of full-line comments that are not seen as a blank lines and do not terminate a record.
Use of spaces, commas, tabs, or new indented lines as separators of multiple attribute value pairs (AVP).
Use of multiple default entries.
Use of a blank line is required to separate individual entries (profiles) when ReadUserFile-ColumnOneMode is set to False.
User of a non-white space character in column one is required to separate individual entries (profiles) when ReadUserFile-ColumnOneMode is set to True.
Use of characters in the key index–typically the User-Name–may be any character except the following when the key is unquoted: pound sign (#), white space, commas (,), quotes ("), less then (<), or back slash (\). If any of the these characters are needed in a key, the key may be quoted and the characters used and normal escaping rules apply.

Note: The default search string for the ReadUserFile plug-in is the ${packet.Base-User-Name} variable, which contains the value of the RADIUS User-Name attribute without the realm.

File Format Rules

The following explain and demonstrate these formatting rules.

A Basic User Profile

The format for a basic user profile is described in the following:

The first line must start at the left-hand margin and begin with the index-key (usually the user name or the keyword DEFAULT) followed by white space (tab or space characters). The white space is followed by the search key's check items.
Note: Any search key starting with the string DEFAULT is assumed to be a default entry, see Default Entries below.)
The remainder of the first line may consist of optional check-Item AVPs
The second logical line (See Continuing Long Lines) begins the list of reply items sent to the RADIUS client to configure the user's session. The second and any additional lines are indented. By convention, all subsequent lines of reply items follow the same indent.
One or more blank lines follow the last reply item separating one profile from another and marking the end of the profile entry.

Examples of a typical single and multiple user profiles

The following is an example of a typical user profile created using these guidelines:

The first line shows steve is the entry's key, and password="testing" is the only check item. The remaining eight lines are the reply items:

steve Password="testing"
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 192.168.10.6,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = Broadcast-Listen,
Filter-Id = "std.ppp",
Framed-MTU = 1500,
Framed-Compression = Van-Jacobson-TCP-IP

Multiple user entries follow the same format with at least one blank line to clearly separate each entry.

steve Password="testing"
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 192.168.10.6,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = Broadcast-Listen,
Filter-Id = "std.ppp",
Framed-MTU = 1500,
Framed-Compression = Van-Jacobson-TCP-IP

gonzo Password="testing"
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 192.168.10.6,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = Broadcast-Listen,
Filter-Id = "std.ppp",
Framed-MTU = 1500,
Framed-Compression = Van-Jacobson-TCP-IP

Continuing Long First Lines

For readability, the backslash (\) line continuation character may be used at the end of a line to indicate that the text is actually continued on the next line. The backslash character must be the last character on the line, and must not be followed by a space or tab. In the example below, there are four check items that are quite long so we chose to continue the final check item on the next line and indicate the break using the backslash.

steve Password="testing", Called-Station-Id= "8005551234" NAS-IP-Address = 10.1.1.3, \
NAS-Port-Type = Async
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 192.168.10.6,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = Broadcast-Listen,
Filter-Id = "std.ppp",
Framed-MTU = 1500,
Framed-Compression = Van-Jacobson-TCP-IP

In this example, the second line with the NAS-Port-Type is read as part of the first line since the first line ended with a backslash (\). The program will thus include NAS-Port-Type as part of the profile's check items.

Inserting Comments

Sometimes it may be necessary to add a comment to a profile.

Comments are denoted by a pound sign (#). This tells the server to, "Ignore anything that appears after the #."
Comments can be inserted as single or multiple-line comments.
Spaces following the pound sign are not required.
Comments may be added before, in, and after an entry but must not be separated from the entry by a blank line.

For example:

# This is Steve's entry
steve Password="testing"
# Everything that follows is session info for steve
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 192.168.10.6, # Static IP Address
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = Broadcast-Listen, # Accept Routing updates
Filter-Id = "std.ppp",
Framed-MTU = 1500,
Framed-Compression = Van-Jacobson-TCP-IP
# This is the end of Steve's entry - and there must be a blank line after this comment

Separating Multiple Reply Attribute Pairs

NavisRadius allows using commas and white space to separate Attribute Value Pairs (AVPs). (Note that the comma (,) at the end of a line has no special meaning in NavisRadius.) The following example shows the use of these separators and the line continuation character in a typical user file:

steve Password="testing" Service-Type = Framed-User Framed-Protocol= PPP \
Framed-IP-Address = 192.168.10.6 \
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = Broadcast-Listen,
Filter-Id = "std.ppp"
Framed-MTU = 1500,
Framed-Compression = Van-Jacobson-TCP-IP

The DEFAULT Entry

NavisRadius also allows the use of default entries in the user file. If the ReadUserFile method property ReadUserFile-NoDefaults is set to FALSE and an index-key exactly matching the search key is not found, NavisRadius then automatically looks for entries with an index-key of DEFAULT. If the DEFAULT profile is found then it is used as the user profile. The default profile can be used when several users use a common session profile. For example:

#
# Use this configuration as a default if the user does
# not have one specified.
#
# NOTE: User's existence needs to be verified
# elsewhere.
#
DEFAULT Auth-Type = UNIX
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = Van-Jacobson-TCP-IP,
Framed-MTU = 1500

As shown in the example above, only one DEFAULT entry was used and it would match any request. The Auth-Type = UNIX is used as an indication that password authentication will be performed by retrieving the user's password from the UNIX password file or system password source later in the PolicyFlow™.

Note: If a ReadUserFile method is assigned a blank or missing search-key the method will fail and will not search for default users. To avoid this problem, which occurs most often when using a search-key other than the User-Name such as a realm, assign the specific value DEFAULT as a default value in the search-key property. For example:

ReadUserFile-SearchKey = ${packet.User-Realm:DEFAULT}

Multiple Default Entries

When several alternate default profiles are necessary, NavisRadius allows multiple DEFAULT profiles. If you have several services and each service requires a different profile, you can select among multiple default entries by using a User-Name prefix, a User-Name suffix or both.

When multiple DEFAULT entries exist in a User File each one is checked in the order it appears in the user file. Each entry should have a unique suffix, prefix, or combination of suffix and prefix. A DEFAULT entry with no suffix or prefix will match every request and should be the last DEFAULT entry in the file. All DEFAULT entries are checked after all non-default entries are checked.

Note: For entries using a prefix or suffix any of the following formats are acceptable for either:

Prefix=.slip
Prefix= .slip
Prefix =.slip
Prefix = .slip
Prefix=".slip"

Multiple Default Entries Using a Prefix

When NavisRadius sees a prefixed check item in a default entry, the value of the prefix check item is matched against the user name starting with the first character. The user name prefix can consist of any characters allowed in a user name and does not have to be separated from the user name by a delimiter. Also, prefixes are case-sensitive.

A DEFAULT entry with the Check-Item... would match this user name

Prefix = "slip." slip.richard

Prefix = "ppp." ppp.thomas

Prefix = "madrid" madridmaria

Prefix = "Paris" Parisclaude

A DEFAULT entry with the Check-Item...	would match this user name
Prefix = "slip."	slip.richard
Prefix = "ppp."	ppp.thomas
Prefix = "madrid"	madridmaria
Prefix = "Paris"	Parisclaude

For example, a user might prefix slip. or ppp. to their user name depending on which session profile they wanted. The default profiles would look something like the following:

#
# DEFAULT SLIP Configuration
#
DEFAULT Prefix = "slip."
Service-Type = Framed-User,
Framed-Protocol = SLIP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

#
# DEFAULT PPP Configuration
#
DEFAULT Prefix = "ppp."
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

Multiple Default Entries Using a Suffix

Instead of using a prefix test, it is also possible to do a suffix test. The syntax is very similar to the prefix syntax except the match test starts at the last character of the user name and reads to the left until a match is made or none is possible. For example:

The Check-Item... would match this user name

Suffix = .slip terry.slip

Suffix = .ppp kyle.ppp

Suffix = london nigellondon

Suffix = Berlin hansBerlin

The Check-Item...	would match this user name
Suffix = .slip	terry.slip
Suffix = .ppp	kyle.ppp
Suffix = london	nigellondon
Suffix = Berlin	hansBerlin

For example, a user might append .slip or .ppp to their user name depending on which session profile they wanted. The default profiles would look something like the following:

#
# DEFAULT SLIP Configuration
#
DEFAULT Suffix = ".slip"
Service-Type = Framed-User,
Framed-Protocol = SLIP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

#
# DEFAULT PPP Configuration
#
DEFAULT Suffix = ".ppp"
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

Multiple Default Entries Using Automatic Suffix Calculation

If neither a prefix nor a suffix check item is provided in a default profile entry, then NavisRadius will automatically create a suffix check item by masking off the string DEFAULT from the key index and assigning any remaining characters as the suffix. For example, if the index-key is DEFAULT.slip and no suffix check item is defined, NavisRadius will automatically create a suffix of slip as though the entry contained Suffix = .slip. This automatic check item is calculated on-the-fly and is not actually written to the User-File. This is illustrated below:

#
# DEFAULT.slip SLIP Configuration
# NavisRadius will treat this entry as though it contained Suffix = .slip

#
DEFAULT.slip
Service-Type = Framed-User,
Framed-Protocol = SLIP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

#
# DEFAULT.ppp PPP Configuration
# NavisRadius will treat this entry as though it contained Suffix = .ppp
#
DEFAULT.ppp
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

Example of Multiple Default Entries Using Prefix and Suffix

DEFAULT Prefix = "slip."
Service-Type = Framed-User,
Framed-Protocol = SLIP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

DEFAULT Prefix = "ppp."
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

DEFAULT.slip
Service-Type = Framed-User,
Framed-Protocol = SLIP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

DEFAULT.ppp
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = None,
Framed-MTU = 1006

DEFAULT Prefix = "slip.", Suffix = ".compressed"
Service-Type = Framed-User,
Framed-Protocol = SLIP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = Stac-LZS,
Framed-MTU = 1006

DEFAULT Prefix = "ppp.", Suffix = ".compressed"
Service-Type = Framed-User,
Framed-Protocol = PPP,
Framed-IP-Address = 255.255.255.254,
Framed-IP-Netmask = 255.255.255.255,
Framed-Routing = None,
Framed-Compression = Stac-LZS,
Framed-MTU = 1006

DEFAULT Auth-Type = Reject
Reply-Message = "You Must choose a session profile: slip. or ppp."

Determining the Actual User-Name that Matched the Default Entry

It is often necessary to know the user name without the prefix or suffix for use in later methods in a PolicyFlow. For example, if the user name rome.antonia matched a default entry with the check-item Prefix = rome. we might want to use the user name antonio in a later method. The ReadUserFile plug-in makes the User-Name without the prefix or suffix available in the ${key} return variable. This can be used to assign the user name to a NavisRadius variable for later use.

This example illustrates the use of the ${key} variable:

UserLookUp Method-Type = ReadUserFile Method-Next = continue
ReadUserFile-Filename = users
ReadUserFile-NoDefaults = FALSE
# The Search Key is the user name with a prefix or suffix, but without realm
ReadUserFile-SearchKey = "${packet.Base-User-Name}"
ReadUserFile-Map = "${reply.*}= ${reply.*};"
ReadUserFile-Map = "${check.*}= ${check.*};"
# The user name without a prefix or suffix is saved for use later in the PolicyFlow.
ReadUserFile-Map = "${user.Base-User-Name} = ${key};"