13.3 Radius Internal Attributes

These are attributes used by GNU Radius during the processing of a request. They are never returned to the NAS. Mostly, they are used in matching rules.

13.3.1 Acct-Ext-Program

ATTRIBUTE Acct-Ext-Program 2008 string

The Acct-Ext-Program attribute can be used in RHS of an ‘raddb/hints’ to require the execution of an external accounting program or filter. If the attribute value starts with a vertical bar (‘|’), then the attribute specifies the filter program to be used. If it starts with a slash (‘/’), then it is understood as the full pathname and arguments for the external program to be executed. Using any other character as the start of this string results in error.

The command line can reference any attributes from both check and reply pairlists using attribute macros (see section Macro Substitution).

Before the execution of the program, radiusd switches to the uid and gid of the user daemon and the group daemon. You can override these defaults by setting variables exec-program-user and exec-program-group in configuration file to proper values (see section The option statement).

The accounting program must exit with status 0 to indicate a successful accounting.

13.3.2 Acct-Type

ATTRIBUTE Acct-Type 2003 integer

VALUE           Acct-Type               None    0
VALUE           Acct-Type               System  1
VALUE           Acct-Type               Detail  2
VALUE           Acct-Type               SQL     3

The Acct-Type allows one to control which accounting methods must be used for a given user or group of users. In the absence of this attribute, all currently enabled accounting types are used. See section Accounting, for more information about accounting types.

13.3.3 Auth-Failure-Trigger

This attribute specifies an external program or a Scheme expression to be run upon an authentication failure. The handling of this attribute depends upon its value:

If the value of Auth-Failure-Trigger begins with ‘/’, it is taken to contain a command line for invoking an external program. In this case radiusd invokes the program much the same way it does when handling Exec-Program attribute, i.e. the program is invoked with standard input closed, its standard output and standard error are captured and redirected to ‘radlog/radius.stderr’ file, the return value of the program is ignored.

If the value of Auth-Failure-Trigger begins with ‘(’, it is executed it as a Scheme expression. The return value of the expression is ignored.

This attribute is designed as a means to provide special handling for authentication failures. It can be used, for example, to increase failure counters and to block accounts after a specified number of authentication failures occurs. See section Controlling Authentication Probes, for the detailed discussion of its usage.

13.3.4 Auth-Data

ATTRIBUTE Auth-Data 2006 string

The Auth-Data can be used to pass additional data to the authentication methods that need them. In version 1.6 of GNU Radius, this attribute may be used in conjunction with the SQL and Pam authentication types. When used with the Pam authentication type, this attribute holds the name of the PAM service to use. This attribute is temporarily appended to the authentication request, so its value can be referenced to as %C{Auth-Data}. See section Authentication Server Parameters, for an example of of using the Auth-Data attribute in ‘raddb/sqlserver’:

13.3.5 Auth-Type

ATTRIBUTE Auth-Type 1000 integer

VALUE      Auth-Type         Local                0       
VALUE      Auth-Type         System               1       
VALUE      Auth-Type         Crypt-Local          3       
VALUE      Auth-Type         Reject               4       
VALUE      Auth-Type         SQL                  252     
VALUE      Auth-Type         Pam                  253     
VALUE      Auth-Type         Accept               254     

This attribute tells the server which type of authentication to apply to a particular user. It can be used in the LHS of the user's profile (see section Authentication.)

Radius interprets values of Auth-Type attribute as follows:

Local

The value of the User-Password attribute from the record is taken as a cleantext password and is compared against the User-Password value from the input packet.

System

This means that a user's password is stored in a system password type. Radius queries the operating system to determine if the user name and password supplied in the incoming packet are O.K.

Crypt-Local

The value of the User-Password attribute from the record is taken as an MD5 hash on the user's password. Radius generates MD5 hash on the supplied User-Password value and compares the two strings.

Reject

Authentication fails.

Accept

Authentication succeeds.

SQL

Mysql

The MD5-encrypted user's password is queried from the SQL database (SQL Authentication Type). Mysql is an alias maintained for compatibility with other versions of Radius.

Pam

The user-name–password combination is checked using PAM.

13.3.6 Crypt-Password

ATTRIBUTE Crypt-Password 1006 string

This attribute is intended to be used in user's profile LHS. It specifies the MD5 hash of the user's password. When this attribute is present, Auth-Type = Crypt-Local is assumed. If both Auth-Type and Crypt-Password are present, the value of Auth-Type is ignored.

See section Auth-Type.

13.3.7 Exec-Program-Wait

ATTRIBUTE Exec-Program-Wait 1039 string

When present in the RHS, the Exec-Program-Wait attribute specifies the program to be executed when the entry matches. If the attribute value string starts with vertical bar (‘|’), then the attribute specifies the filter program to be used. If it starts with slash (‘/’), then it is understood as the full pathname and arguments for the external program to be executed. Using any other character as the start of this string results in error.

13.3.7.1 Running an External Program

The command line can reference any attributes from both check and reply pairlists using attribute macros see section Macro Substitution.

Before the execution of the program, radiusd switches to uid and gid of the user daemon and the group daemon. You can override these defaults by setting the variable exec-program-user in the configuration file to a proper value. See section The option statement.

The daemon will wait until the program terminates. The return value of its execution determines whether the entry matches. If the program exits with a nonzero code, then the match fails. If it exits with a zero code, the match succeeds. In this case the standard output of the program is read and parsed as if it were a pairlist. The attributes thus obtained are added to the entry's reply attributes.

Example.

Suppose the ‘users’ file contains the following entry:

DEFAULT Auth-Type = System,
                Simultaneous-Use = 1
        Exec-Program-Wait = "/usr/local/sbin/telauth \
                             %C{User-Name} \
                             %C{Calling-Station-Id}"

Then, upon successful matching, the program ‘/usr/local/sbin/telauth’ will be executed. It will get as its arguments the values of the User-Name and Calling-Station-Id attributes from the request pairs.

The ‘/usr/local/sbin/telauth’ can, for example, contain the following:

#! /bin/sh

DB=/var/db/userlist

if grep "$1:$2" $DB; then
    echo "Service-Type = Login,"
    echo "Session-Timeout = 1200"
    exit 0
else
    echo "Reply-Message = \
          \"You are not authorized to log in\""
    exit 1
fi

It is assumed that ‘/var/db/userlist’ contains a list of username:caller-id pairs for those users that are authorized to use login service.

13.3.7.2 Using an External Filter

If the value of Exec-Program-Wait attribute begins with ‘|’, radiusd strips this character from the value and uses the resulting string as a name of the predefined external filter. Such filter must be declared in ‘raddb/config’ (see section filters statement).

Example.

Let the ‘users’ file contain the following entry:

DEFAULT Auth-Type = System,
                Simultaneous-Use = 1
        Exec-Program-Wait = "|myfilter"

and let the ‘raddb/config’ contain the following (6):

filters {
    filter myfilter {
        exec-path "/usr/libexec/myfilter";
        error-log "myfilter.log";
        auth {
            input-format "%C{User-Name}
                          %C{Calling-Station-Id}";
            wait-reply yes;
        };
    };        
};                        

Then, upon successful authentication, the program /usr/libexec/myfilter will be invoked, if it hasn't already been started for this thread. Any output it sends to its standard error will be redirected to the file ‘myfilter.log’ in the current logging directory. A string consisting of the user's login name and his calling station ID followed by a newline will be sent to the program.

The following is a sample /usr/libexec/myfilter written in the shell:

#! /bin/sh

DB=/var/db/userlist

while read NAME CLID
do
    if grep "$1:$2" $DB; then
        echo "0 Service-Type = Login, Session-Timeout = 1200"
    else
        echo "1 Reply-Message = \
              \"You are not authorized to log in\""
    fi
done

13.3.8 Exec-Program

ATTRIBUTE Exec-Program 1038 string

When present in the RHS, the Exec-Program attribute specifies the full pathname and arguments for the program to be executed when the entry matches.

The command line can reference any attributes from both check and reply pairlists, using attribute macros (see section Macro Substitution).

Before the execution of the program, radiusd switches to the uid and gid of the user daemon and the group daemon. You can override these defaults by setting variables exec-program-user and exec-program-group in configuration file to proper values The option statement.

The daemon does not wait for the process to terminate.

Example

Suppose the ‘users’ file contains the following entry:

DEFAULT Auth-Type = System,
                Simultaneous-Use = 1
        Exec-Program = "/usr/local/sbin/logauth \
                        %C{User-Name} \
                        %C{Calling-Station-Id}"

Then, upon successful matching, the program ‘/usr/local/sbin/logauth’ will be executed. It will get as its arguments the values of the User-Name and Calling-Station-Id attributes from the request pairs.

13.3.9 Fall-Through

ATTRIBUTE Fall-Through 1036 integer

VALUE      Fall-Through      No                   0       
VALUE      Fall-Through      Yes                  1       

The Fall-Through attribute should be used in the reply list. If its value is set to Yes in a particular record, that tells Radius to continue looking up other records even when the record at hand matches the request. It can be used to provide default values for several profiles.

Consider the following example. Let's suppose the ‘users’ file contains the following:

johns   Auth-Type = SQL
                Framed-IP-Address = 11.10.10.251,
                Fall-Through = Yes

smith   Auth-Type = SQL
                Framed-IP-Address = 11.10.10.252,
                Fall-Through = Yes

DEFAULT NAS-IP-Address = 11.10.10.1
        Service-Type = Framed-User,
                Framed-Protocol = PPP

Then after successful matching of a particular user's record, the matching will continue until it finds the DEFAULT entry, which will add its RHS to the reply pairs for this request. The effect is that, if user ‘johns’ authenticates successfully she gets the following reply pairs:

        Service-Type = Framed-User,
        Framed-Protocol = PPP,  
        Framed-IP-Address = 11.10.10.251

whereas user smith gets

        Service-Type = Framed-User,
        Framed-Protocol = PPP,  
        Framed-IP-Address = 11.10.10.252

Note that the attribute Fall-Through itself is never returned to the NAS.

13.3.10 Group

ATTRIBUTE Group 1005 string

13.3.11 Hint

ATTRIBUTE Hint 1040 string

Use the Hint attribute to specify additional matching criteria depending on the hint (see section Request Processing Hints — ‘raddb/hints’).

Let the ‘hints’ file contain

DEFAULT         Prefix = "S", Strip-User-Name = No
                Hint = "SLIP"

and the ‘users’ file contain

DEFAULT Hint = "SLIP",
                NAS-IP-Address = 11.10.10.12,
                Auth-Type = System
        Service-Type = Framed-User,
                Framed-Protocol = SLIP

Then any user having a valid system account and coming from NAS ‘11.10.10.12’ will be provided SLIP service if his user name starts with ‘S’.

13.3.12 Huntgroup-Name

ATTRIBUTE Huntgroup-Name 221 string

The Huntgroup-Name can be used either in the LHS of the ‘users’ file record or in the RHS of the ‘huntgroups’ file record.

When encountered in a LHS of a particular ‘users’ profile, this attribute indicates the huntgroup name to be matched. Radius looks up the corresponding record in the ‘huntgroups’ file. If such a record is found, each A/V pair from its reply list is compared against the corresponding pair from the request being processed. The request matches only if it contains all the attributes from the specified huntgroup, and their values satisfy the conditions listed in the huntgroup pairs.

For example, suppose that the authentication request contains the following attributes:

User-Name = "john",
User-Password = "guess",
NAS-IP-Address = 10.11.11.1,
NAS-Port-Id = 24

Let us further suppose that the ‘users’ file contains the following entry:

john    Huntgroup-Name = "users_group",
                Auth-Type = System
        Service-Type = Login

and, finally, ‘huntgroups’ contains the following entry:

users_group     NAS-IP-Address = 10.11.11.1
                NAS-Port-Id < 32

Then the authentication request will succeed, since it contains NAS-Port-Id attribute and its value is less than 32.

See section Huntgroups — ‘raddb/huntgroups’.

13.3.13 Log-Mode-Mask

ATTRIBUTE Log-Mode-Mask 2007 integer

VALUE           Log-Mode-Mask           Log-Auth                1
VALUE           Log-Mode-Mask           Log-Auth-Pass           2
VALUE           Log-Mode-Mask           Log-Failed-Pass         4
VALUE           Log-Mode-Mask           Log-Pass                6
VALUE           Log-Mode-Mask           Log-All                 7

Log-Mode-Mask is used to control the verbosity of authentication log messages for given user or class of users. The meaning of its values is:

Log-Auth

Do not log successful authentications.

Log-Auth-Pass

Do not show the password with the log message from a successful authentication.

Log-Failed-Pass

Do not show a failed password.

Log-Pass

Do not show a plaintext password, either failed or succeeded.

Log-All

Do not log authentications at all.

Technical details: After authentication, the server collects all Log-Mode-Mask attributes from the incoming request and LHS of the user's entry. The values of these attributes ORed together form a mask, which is applied via an XOR operation to the current log mode. The value thus obtained is used as effective log mode.

13.3.14 Login-Time

ATTRIBUTE Login-Time 1042 string

The Login-Time attribute specifies the time range over which the user is allowed to log in. The attribute should be specified in the LHS.

The format of the Login-Time string is the same as that of UUCP time ranges. The following description of the time range format is adopted from the documentation for the Taylor UUCP package:

A time string may be a list of simple time strings separated with vertical bars ‘|’ or commas ‘,’.

Each simple time string must begin either with a day-of-week abbreviation (one of ‘Su’, ‘Mo’, ‘Tu’, ‘We’, ‘Th’, ‘Fr’, ‘Sa’), or ‘Wk’ for any day from Monday to Friday inclusive, or ‘Any’ or ‘Al’ for any day.

Following the day may be a range of hours separated with a hyphen, using 24-hour time. The range of hours may cross 0; for example ‘2300-0700’ means any time except 7 AM to 11 PM. If no time is given, calls may be made at any time on the specified day(s).

The time string may also be the single word ‘Never’, which does not match any time.

Here are a few sample time strings with an explanation of what they mean.

‘Wk2305-0855,Sa,Su2305-1655’

This means weekdays before 8:55 AM or after 11:05 PM, any time Saturday, or Sunday before 4:55 PM or after 11:05 PM. These are approximately the times during which night rates apply to phone calls in the U.S.A. Note that this time string uses, for example, ‘2305’ rather than ‘2300’; this will ensure a cheap rate even if the computer clock is running up to five minutes ahead of the real time.

‘Wk0905-2255,Su1705-2255’

This means weekdays from 9:05 AM to 10:55 PM, or Sunday from 5:05 PM to 10:55 PM. This is approximately the opposite of the previous example.

‘Any’

This means any day. Since no time is specified, it means any time on any day.

13.3.15 Match-Profile

ATTRIBUTE Match-Profile 2004 string

The Match-Profile attribute can be used in LHS and RHS lists of a user profile. Its value is the name of another user's profile (target profile). When Match-Profile is used in the LHS, the incoming packet will match this profile only if it matches the target profile. In this case the reply pairs will be formed by concatenating the RHS lists from both profiles. When used in the RHS, this attribute causes the reply pairs from the target profile to be appended to the reply from the current profile if the target profile matches the incoming request.

For example:

IPPOOL  NAS-IP-Address = 10.10.10.1
                Framed-Protocol = PPP,
                Framed-IP-Address = "10.10.10.2"

IPPOOL  NAS-IP-Address = 10.10.11.1
                Framed-Protocol = PPP,
                Framed-IP-Address = "10.10.11.2"

guest   Auth-Type = SQL
                Service-Type = Framed-User,
        Match-Profile = IPPOOL

In this example, when user guest comes from NAS 10.10.10.1, he is assigned IP 10.10.10.2, otherwise if he is coming from NAS 10.10.11.1 he is assigned IP 10.10.11.2.

13.3.16 Menu

ATTRIBUTE Menu 1001 string

This attribute should be used in the RHS. If it is used, it should be the only reply item.

The Menu attribute specifies the name of the menu to be presented to the user. The corresponding menu code is looked up in the ‘RADIUS_DIR/menus/’ directory (see section Login Menus — ‘raddb/menus’).

13.3.17 Pam-Auth

ATTRIBUTE Pam-Auth 1041 string

The Pam-Auth attribute can be used in conjunction with

Auth-Type = Pam

to supply the PAM service name instead of the default ‘radius’. It is ignored if Auth-Type attribute is not set to Pam.

13.3.18 Prefix

ATTRIBUTE Prefix 1003 string

The Prefix attribute indicates the prefix that the user name should contain in order for a particular record in the profile to be matched. This attribute should be specified in the LHS of the ‘users’ or ‘hints’ file.

For example, if the ‘users’ file contained

DEFAULT Prefix = "U", Auth-Type = System
                Service-Type = Login-User

then the user names ‘Ugray’ and ‘Uyoda’ would match this record, whereas ‘gray’ and ‘yoda’ would not.

Both Prefix and Suffix attributes may be specified in a profile. In this case the record is matched only if the user name contains both the prefix and the suffix specified.

See section Suffix, and Strip-User-Name.

13.3.19 Proxy-Replied

ATTRIBUTE Proxy-Replied 2012 integer

VALUE      Proxy-Replied     No                   0       
VALUE      Proxy-Replied     Yes                  1       

radiusd adds this attribute to the incoming request if it was already processed by a remote radius server.

13.3.20 Realm-Name

(This message will disappear, once this node revised.)

ATTRIBUTE Realm-Name 2013 string

13.3.21 Replace-User-Name

ATTRIBUTE Replace-User-Name 2001 string

VALUE      Replace-User-Name  No                   0       
VALUE      Replace-User-Name  Yes                  1       

Use this attribute to modify the user name from the incoming packet. The Replace-User-Name can reference any attributes from both LHS and RHS pairlists using attribute macros (Macro Substitution).

For example, the ‘users’ entry

guest   NAS-IP-Address = 11.10.10.11,
                Calling-Station-Id != ""
                Auth-Type = Accept
        Replace-User-Name = "guest#%C{Calling-Station-Id}",
                Service-Type = Framed-User,
                Framed-Protocol = PPP

allows the use of PPP service for user name guest, coming from NAS ‘11.10.10.11’ with a nonempty Calling-Station-Id attribute. A string consisting of a ‘#’ character followed by the Calling-Station-Id value is appended to the user name.

13.3.22 Rewrite-Function

ATTRIBUTE Rewrite-Function 2004 string

The Rewrite-Function attribute specifies the name of the rewriting function to be applied to the request. The attribute may be specified in either pairlist in the entries of the ‘hints’ or ‘huntgroups’ configuration file.

The corresponding function should be defined in ‘rewrite’ as

integer name()

i.e., it should return an integer value and should not take any arguments.

See section Packet rewriting rules, Request Processing Hints — ‘raddb/hints’; Huntgroups — ‘raddb/huntgroups’.

13.3.23 Scheme-Acct-Procedure

ATTRIBUTE Scheme-Acct-Procedure 2010 string

The Scheme-Acct-Procedure attribute is used to set the name of the Scheme accounting procedure. See section Accounting with Scheme, for information about how to write Scheme accounting procedures.

13.3.24 Scheme-Procedure

ATTRIBUTE Scheme-Procedure 2009 string

The Scheme-Procedure attribute is used to set the name of the Scheme authentication procedure. See section Authentication with Scheme, for information about how to write Scheme authentication procedures.

13.3.25 Simultaneous-Use

ATTRIBUTE Simultaneous-Use 1034 integer

This attribute specifies the maximum number of simultaneous logins a given user is permitted to have. When the user is logged in this number of times, any further attempts to log in are rejected.

See section Multiple Login Checking.

13.3.26 Strip-User-Name

ATTRIBUTE Strip-User-Name 1035 integer

VALUE      Strip-User-Name   No                   0       
VALUE      Strip-User-Name   Yes                  1       

The value of Strip-User-Name indicates whether Radius should strip any prefixes/suffixes specified in the user's profile from the user name. When it is set to Yes, the user names will be logged and accounted without any prefixes or suffixes.

A user may have several user names for different kind of services. In this case differentiating the user names by their prefixes and stripping them off before accounting would help keep accounting records consistent.

For example, let's suppose the ‘users’ file contains

DEFAULT Suffix = ".ppp",
                Strip-User-Name = Yes,
                Auth-Type = SQL
        Service-Type = Framed-User,
                Framed-Protocol = PPP

DEFAULT Suffix = ".slip",
                Strip-User-Name = Yes,
                Auth-Type = SQL
        Service-Type = Framed-User,
                Framed-Protocol = SLIP

Now, user ‘johns’, having a valid account in the SQL database, logs in as ‘johns.ppp’. She then is provided the PPP service, and her PPP session is accounted under user name ‘johns’. Later on, she logs in as ‘johns.slip’. In this case she is provided the SLIP service and again her session is accounted under her real user name ‘johns’.

13.3.27 Suffix

ATTRIBUTE Suffix 1004 string

The Suffix attribute indicates the suffix that the user name should contain in order for a particular record in the profile to be matched. This attribute should be specified in LHS of the ‘users’ or ‘hints’ file.

For example, if the ‘users’ file contained

DEFAULT Suffix = ".ppp", Auth-Type = System,
                Strip-User-Name = Yes
        Service-Type = Framed-User,
                Framed-Protocol = PPP        

then the user names ‘gray.ppp’ and ‘yoda.ppp’ would match this record, whereas ‘gray’ and ‘yoda’ would not.

Both Prefix and Suffix attributes may be specified in a profile. In this case the record is matched only if the user name contains both the prefix and the suffix specified.

See section Prefix, and Strip-User-Name.

13.3.28 Termination-Menu

ATTRIBUTE Termination-Menu 1002 string

This attribute should be used in the RHS. If it is used, it should be the only reply item.

The Termination-Menu specifies the name of the menu file to be presented to the user after finishing his session. The corresponding menu code is looked up in the ‘RADIUS_DIR/menus/’ directory (see section Login Menus — ‘raddb/menus’).

This document was generated by Sergey Poznyakoff on December, 6 2008 using texi2html 1.78.