doc/rlm_dbm

   1 Radius DBM module
   2
   3 0. INTRODUCTION
   4
   5   rlm_dbm uses a Berkeley or GDBM <** database to store use information. It
   6   is a lot faster than the files and passwd modules, takes less memory than
   7   the fastusers module and does not require additional server software as
   8   the LDAP and SQL modules does. In addition it supports groups, and of
   9   course multiple entries per user or group.
  10
  11 1. WHAT DOES IT DO
  12
  13   Basically, it opens the file you specifies in radiusd.conf and authenticates
  14   users out of it. The file has to be a Berkeley or GDBM <** file database,
  15   and may be created by rlm_dbm_parse or by a custom program of your choice.
  16
  17 2. HOW TO USE IT
  18
  19   Put the module declaration in your radiusd.conf. It should in general look
  20   like this:
  21
  22   dbm {
  23       usersfile = ${confdir}/users.db
  24   }
  25   Note: some dbm libraries add .db suffix by itself.
  26
  27   Then put "dbm" in the "authorize {}" section of your radiusd.conf:
  28
  29   authorize {
  30       preprocess
  31       realms
  32       dbm
  33     }
  34
  35 3.  MODULE OPTIONS
  36
  37   The only option is "usersfile", which is the path and filename of the
  38   database file you want rlm_dbm to look for users and groups in. This
  39   file needs to be generated, either by the rlm_dbm_parse program or by
  40   some custom program, for instance a Perl program using the DB_File or
  41   GDBM_File <** modules.
  42
  43 4.  EXTERNAL UTILITIES
  44
  45   rlm_dbm_cat
  46
  47     rlm_dbm_cat: [-f file] [-w] [-i number] [-l number] [-v] [username ...]
  48
  49     rlm_dbm_cat simply lists the definition(s) of the username(s) or group
  50     name(s), or the entire database. It takes the following options:
  51
  52       -f <filename>
  53
  54       The file name of the database to list.
  55
  56       -w
  57         Long lines should be wrapped
  58
  59       -i <number>
  60 Set the left margin then wrapped.
  61       -l <number>
  62 How long line should be to be wrapped (wrap threshold)
  63
  64       -v
  65
  66       Print the version number and exit.
  67
  68     rlm_dbm_parse
  69
  70       rlm_dbm_parser [-c] [-d raddb] [-i inputfile] [-o outputfile] [-x]
  71                      [-v] [-q] [username ...]
  72
  73       rlm_dbm_parses reads a file of the syntax defined below, and writes
  74       a database file usable by rlm_dbm or edits current database.
  75       It takes the following options:
  76
  77       -i <file>
  78
  79       Use <file> as the input file. If not defined then use standard input.
  80
  81       -o
  82
  83       Use <file> as the output file.
  84
  85       -c
  86
  87       Create a new database (empty output file before writing)
  88
  89       -x
  90
  91       Enable debug mode.
  92 ; Multiple x flag increase debug level
  93
  94       -q
  95
  96       Do not print statistics (quiet).
  97
  98       -v
  99
 100       Print the version and exit.
 101
 102       -r
 103
 104       Remove a username or group name from the database.
 105
 106 5. INPUT FORMAT
 107
 108   rlm_dbm_parse reads a format similar to the one used by the files
 109   module. In incomplete RFC2234 ABNF, it looks like this:
 110
 111   entries     = *entry
 112   entry       = identifier TAB definition
 113   identifier  = username / group-name
 114   username    = +PCHAR
 115   groupname   = +PCHAR
 116   definition  = (check-item ",")* LF ( *( reply-item ",") / ";" ) LF
 117   check-item  = AS IN FILES
 118   reply-item  = AS IN FILES
 119
 120 *** need definition of username and groupname ***
 121
 122   As an example, these are the standard files definitions (files module).
 123
 124 ---8<---
 125   DEFAULT   Service-Type == Framed-User
 126             Framed-IP-Address = 255.255.255.254,
 127             Framed-MTU = 576,
 128             Service-Type = Framed-User,
 129             Fall-Through = Yes
 130
 131 #except who call from number 555-666
 132   DEFAULT   Auth-Type := Reject,Service-Type ==Framed-User,
 133             Calling-Station-ID == "555-666"
 134
 135 #or call number 555-667
 136   DEFAULT   Auth-Type := Reject,Service-Type ==Framed-User,
 137             Calling-Station-ID == "555-667"
 138 ---8<---
 139
 140   To be a valid rlm_dbm input file, it should look like this:
 141
 142 ---8<---
 143   DEFAULT   Service-Type == Framed-User                     # (1)
 144             Framed-IP-Address = 255.255.255.254,            # comma, list cont'd
 145             Framed-MTU = 576,
 146             Service-Type = Framed-User,
 147             Fall-Through =  Yes                             # \n, end of list
 148             Auth-Type := Reject,Service-Type ==Framed-User, # (2)
 149             Calling-Station-ID == "555-666"
 150             ;                                               # ;, no reply items
 151             Auth-Type := Reject,Service-Type ==Framed-User, # (3)
 152             Calling-Station-ID == "555-667"
 153             ;                                               # ditto
 154 ---8<---
 155
 156   This user (the DEFAULT user) contains three entries, 1, 2 and 3. The
 157   first entry has a list of reply items, terminated by a reply item
 158   without a trailing comma. Entries 2 and 3 has empty reply lists, as
 159   indicated by the semicolon. This is necessary to separate an empty
 160   line (which is ignored) from the empty list.
 161   Definition Fall-Through = Yes used in order to say module to check next
 162   record. By default Fall-Through = Yes.
 163
 164   Groups
 165
 166   This is implemented with the special User-Category attribute. Simply
 167   set this as a reply item, and rlm_dbm will include the groups definition
 168   when evaluating the check and reply items of the user. The group defined
 169   the same way as users. Here is a short example:
 170
 171 ---8<---
 172 # group definitions
 173 gendialup
 174             Service-Type = Framed-User,
 175             Cisco-AVPair += "ip:addr-pool=SANDY",
 176             Framed-Protocol = PPP
 177
 178 locked      Auth-Type := Reject
 179             Reply-Message = "Your account has been disabled."
 180
 181 # user definitions
 182 ssalex      Auth-Type := Local, Password == "passs"
 183             User-Category = "GenDialup"
 184
 185 ssmike      Auth-Type := Local, Password == "pass1"
 186             User-Category = "Locked"
 187 ---8<---
 188
 189 6. ACKNOWLEDGMENTS
 190
 191      Author        - Andrei Koulik <rlm_dbm@agk.nnov.ru>
 192      Documentation - Bjørn Nordbø  <bn@nextra.com>
 193 8. Bug reports:
 194     rlm_dbm_bug@agk.nnov.ru
 195