Provided by: freeradius-common_2.1.10+dfsg-3build2_all bug

NAME

       users - user authorization file for the FreeRADIUS server

DESCRIPTION

       The  users  file  resides  in  the  RADIUS  database directory, by default /etc/raddb.  It
       contains a series of configuration directives which are used by the files module to decide
       how to authorize and authenticate each user request.

       Every line starting with a hash sign ('#') is treated as comment and ignored.

       Each  entry  of  the  file  begins with a username, followed by a (possibly empty) list of
       check items, all on one line.  The next line begins with a tab,  and  a  (possibly  empty)
       list  of  reply  items.   Each item in the check or reply item list is an attribute of the
       form name = value.  Multiple items may be placed on one line, in which case they  must  be
       seperated  by commas.  The reply items may be specified over multiple lines, in which case
       each line must end with a comma, and the last line of the reply items must not end with  a
       comma.

       The  check  items  are  a  list  of attributes used to match the incoming request.  If the
       username matches, AND all of the check items match the incoming request,  then  the  reply
       items are added to the list of attributes which will be used in the reply to that request.
       This process is repeated for all of the entries in the users file.

       If the incoming request matches NO entry, then the request is rejected.

CAVEATS

       The special username DEFAULT matches any usernames.

       The entries are processed in order, from the top of the users file, on down.  If an  entry
       contains  the  special item Fall-Through = No as a reply attribute, then the processing of
       the file stops, and no more entries are matched.  Any reply item list  without  any  Fall-
       Through attribute is treated as though it included a Fall-Through = No attribute.

       If  an  entry  contains the special item Fall-Through = Yes as a reply attribute, then the
       processing proceeds to the next entry in order.

       Care should be taken when using Fall-Through.  The server should be  tested  in  debugging
       mode with a number of test requests, in order to verify that the configured entries behave
       as expected.

       The special attribute Auth-Type is used to identify the authentication type to be used for
       that  user.   See  the  dictionary  file  for a list of permitted values for the Auth-Type
       attribute.

       Once the users file has been processed, the request is  authenticated,  using  the  method
       given by Auth-Type.

OPERATORS

       Additional operators other than = may be used for the attributes in either the check item,
       or reply item list.  The following is a list of operators, and their meaning.

       Attribute = Value
            Not allowed as a check item for RADIUS protocol attributes.  It is allowed for server
            configuration  attributes  (Auth-Type, etc), and sets the value of on attribute, only
            if there is no other item of the same attribute.
            As a reply item, it means "add the item to the reply list, but only if  there  is  no
            other item of the same attribute."

       Attribute := Value
            Always matches as a check item, and replaces in the configuration items any attribute
            of the same name.  If no attribute of that name appears in  the  request,  then  this
            attribute is added.
            As a reply item, it has an identical meaning, but for the reply items, instead of the
            request items.

       Attribute == Value
            As a check item, it matches if the named attribute is present in the request, AND has
            the given value.
            Not allowed as a reply item.

       Attribute += Value
            Always matches as a check item, and adds the current attribute with value to the list
            of configuration items.
            As a reply item, it has an identical meaning, but the attribute is added to the reply
            items.

       Attribute != Value
            As  a check item, matches if the given attribute is in the request, AND does not have
            the given value.
            Not allowed as a reply item.

       Attribute > Value
            As a check item, it matches if the request contains an attribute with a value greater
            than the one given.
            Not allowed as a reply item.

       Attribute >= Value
            As a check item, it matches if the request contains an attribute with a value greater
            than, or equal to the one given.
            Not allowed as a reply item.

       Attribute < Value
            As a check item, it matches if the request contains an attribute with  a  value  less
            than the one given.
            Not allowed as a reply item.

       Attribute <= Value
            As  a  check  item, it matches if the request contains an attribute with a value less
            than, or equal to the one given.
            Not allowed as a reply item.

       Attribute =~ Expression
            As a check item, it matches if the request contains an attribute  which  matches  the
            given regular expression.  This operator may only be applied to string attributes.
            Not allowed as a reply item.

       Attribute !~ Expression
            As a check item, it matches if the request contains an attribute which does not match
            the  given  regular  expression.   This  operator  may  only  be  applied  to  string
            attributes.
            Not allowed as a reply item.

       Attribute =* Value
            As  a  check  item, it matches if the request contains the named attribute, no matter
            what the value is.
            Not allowed as a reply item.

       Attribute !* Value
            As a check item, it matches if the request does not contain the named  attribute,  no
            matter what the value is.
            Not allowed as a reply item.

EXAMPLES

       bob  Cleartext-Password := "hello"

              Requests   containing   the   User-Name   attribute,  with  value  "bob",  will  be
              authenticated using the "known good" password "hello".  There are no  reply  items,
              so the reply will be empty.

       DEFAULT   Auth-Type = System
            Fall-Through = Yes

              For  all  users  reaching  this  entry,  perform authentication against the system,
              unless Auth-Type has already been set.  Also, process any following  entries  which
              may match.

       DEFAULT Service-Type == Framed-User, Framed-Protocol == PPP
            Service-Type = Framed-User,
            Framed-Protocol = PPP,
            Fall-Through = Yes

              If  the  request  packet  contains the attributes Service-Type and Framed-Protocol,
              with the given values, then include those attributes in the reply.

              That is, give the user what they ask for.  This entry also  shows  how  to  specify
              multiple reply items.

       See the users file supplied with the server for more examples and comments.

HINTS

       Run  the  server  in  debugging  mode  (-X), and use the radclient program to send it test
       packets which you think will match specific entries.  The  server  will  print  out  which
       entries  were  matched for that request, so you can verify your expectations.  This should
       be the FIRST thing you do if you suspect problems with the file.

       Care should be taken when writing entries for the users file.  It is easy to  misconfigure
       the server so that requests are accepted when you wish to reject them.  The entries should
       be ordered, and the Fall-Through item should be used ONLY where it is required.

       Entries rejecting certain requests should go at the top of the file, and should not have a
       Fall-Through  item  in  their  reply items.  Entries for specific users, who do not have a
       Fall-Through item, should come next.  Any DEFAULT entries should usually come last, except
       as fall-through entries that set reply attributes.

FILES

       /etc/raddb/users

SEE ALSO

       radclient(1), radiusd(8), dictionary(5), naslist(5)

AUTHOR

       The FreeRADIUS team.

                                           04 Jan 2004                                   USERS(5)