doc/Simultaneous-Use

   1
   2         FreeRADIUS server and the Simultaneous-Use parameter.
   3
   4
   5 0. INTRODUCTION
   6
   7   Lots of people want to limit the number of times one user account can
   8   login, usually to one. This is hard to do with the radius protocol;
   9   the nature of the accounting stuff is such that the idea the radius server
  10   has about the list of logged-in users might be different from the idea
  11   the terminal server has about it.
  12
  13   However, most terminal servers have an alternative way to get a list
  14   of logged-in users. Most support some way through telnet, some have
  15   a finger-daemon builtin and a lot of them support SNMP. So if the
  16   radius server thinks that someone is trying to login a second time,
  17   it is possible to check on the terminal server itself if the first
  18   login is indeed still active.  Only then access is denied for the
  19   second login.
  20
  21
  22 1. PREREQUISITES
  23
  24   You need to have perl installed.
  25
  26   For SNMP checks, you have 2 options. You can use the `snmpget' program
  27   from the cmu-snmp tools. You can probably get precompiled ones,
  28   maybe even packaged for your system (Debian/Linux, Redhat/Linux, FreeBSD
  29   ports collection etc). The source code is at
  30   http://www.net.cmu.edu/projects/snmp/snmpapps/. The Linux-specific
  31   version of this is at http://www.gaertner.de/snmp/
  32
  33   The other option is to install the SNMP_Session and BER modules that
  34   for example the well known `mrtg' package uses. This is recommended.
  35   In that case you need no external snmpget program, checkrad will
  36   speak SNMP directly. See http://www.switch.ch/misc/leinen/snmp/perl/
  37
  38   The checkroutine for USR/3Com Total Control racks uses the Net::Telnet
  39   module from CPAN, at least version 3.00. If you need that, obtain it from
  40   your local CPAN mirror (or see http://www.perl.com/CPAN/). The checkrad.pl
  41   perl script will autodetect if that module is installed.
  42
  43 2. USAGE.
  44
  45   It works by adding the `check' parameter "Simultaneous-Use" to the entry
  46   for a users or DEFAULT in /etc/raddb/users. It should be at least one;
  47   it defines the maximum number of users logged in with the same account name.
  48   For example:
  49
  50   #
  51   # Simultaneous use restrictions.
  52   #
  53   DEFAULT Group == "staff", Simultaneous-Use := 4
  54           Fall-Through = 1
  55   DEFAULT Group == "business", Simultaneous-Use := 2
  56           Fall-Through = 1
  57   DEFAULT Simultaneous-Use := 1
  58           Fall-Through = 1
  59
  60
  61   NOTE!!! The "Simultaneous-Use" parameter is in the "check" A/V pairs,
  62           and not in the Reply A/V pairs (it _is_ a check).
  63
  64   For SQL, after creating and populating your schema, you should
  65   execute the following statement (for MySQL, others may vary):
  66
  67   INSERT INTO radgroupcheck (GroupName, Attribute, op, Value) values("dialup", "Simultaneous-Use", ":=", "1");
  68
  69   Once that is done, your users should be limited to only one login at a time.
  70
  71 3. IMPLEMENTATION
  72
  73   The server keeps a list of logged-in users in the /var/log/radutmp file.
  74   This is also called "the session database". When you execute "radwho",
  75   all that radwho really does is list the entries in this file in a pretty
  76   format. Only when someone tries to login who _already_ has an active
  77   session according to the radutmp file, the server executes the perl
  78   script /usr/local/sbin/checkrad (or /usr/sbin/checkrad, it checks for
  79   the presence of both and in that order). This script queries the terminal
  80   server to see if the user indeed already has an active session.
  81
  82   The script uses SNMP for Livingston Portmasters and Ciscos, finger for
  83   Portslave, Computone and Ascend, and Net::Telnet for USR/3Com TC.
  84
  85   Since the script has been witten in perl, it's easy to adjust for
  86   any type of terminal server. There are implementations in the script for
  87   checks using SNMP, finger, and telnet, so it should be easy to add
  88   your own check routine if your terminal server is not supported yet.
  89
  90   You can find the script in the file src/checkrad.pl.
  91
  92   You need to set the correct type in the file /etc/raddb/naslist so that
  93   checkrad KNOWS how it should interrogate the terminal server. At this
  94   time you can define the following types:
  95
  96   type        Vendor      Uses method     needs               Need naspasswd
  97   ====        ======      ===========     =====               ==============
  98   ascend      Lucent      SNMP            SNMP                No
  99   bay         Nortel      finger          finger command      No
 100   cisco       Cisco       SNMP            SNMP                Optional  [1]
 101   computone   Computone   finger          finger command      No
 102   cvx         Nortel      SNMP            SNMP                No
 103   digitro     Digitro     rusers          rusers command      No
 104   livingston  Livingston  SNMP            SNMP                No        [2]
 105   max40xx     Lucent      finger          finger command      No
 106   netserver   USR/3com    telnet          CPAN Net::Telnet    Yes
 107   pathras     Cyclades    telnet          CPAN Net::Telnet    Yes
 108   patton      Patton      SNMP            SNMP                No
 109   portslave   ?           finger          finger command      No
 110   pr3000      Cyclades    SNMP            snmpwalk command    No
 111   pr4000      Cyclades    SNMP            snmpwalk command    No
 112   tc          USR/3com    telnet          CPAN Net::Telnet    Yes
 113   usrhyper    USR/3com    SNMP            SNMP                No        [3]
 114   versanet    VersaNet    SNMP            SNMP                No
 115
 116   other       none        N/A             -                   No
 117
 118   [1] In naspasswd file: set username to SNMP, password is community.
 119   [2] Needs at least ComOS 3.5, SNMP enabled.
 120   [3] Set "Reported Port Density" to 256 (default)
 121
 122   "other" means "don't bother checking, I believe what radutmp says".
 123   This really is not recommended, if a user has a "stuck" entry in the
 124   session database she will not be able to login again - hence the
 125   extra check that "checkrad" does.
 126
 127 4. IF IT DOESN'T WORK
 128
 129   Note that you need to add the Simultaneous-Use parameter to the
 130   check item (first line), not the reply item, using the ':=' operator.
 131
 132   You can edit the `checkrad' perl script and turn on debugging. Then
 133   watch the debug file. The `radius.log' file also gives some hints.
 134
 135   You can also run the "checkrad" script manually, use the "-d"
 136   switch to get debug output on standard output instead of in the log.
 137
 138   See also:
 139
 140         http://wrath.geoweb.ge/simult.html
 141
 142   which has a good discussion of the use of Simultaneous-Use.
 143
 144
 145 5. CAVEATS
 146
 147   This solution checks the radutmp file. This file is kept up-to-date from
 148   the Accounting records the NAS sends. Since some NASes delay these records
 149   for quite some time, it is possible to get a double login by logging in
 150   twice at _exactly_ the same time (plus or minus the mentioned delay time),
 151   since neither of the logins are registered yet.
 152
 153   The solution would be to create a small 1-minute cache of Authentication
 154   records, that is also checked for double login attempts. Perhaps in the
 155   next version.
 156
 157   When implementing this one thing was considered the most important: when
 158   trying to detect double logins, we always try to err on the safe side. So
 159   in rare cases, a double login is possible but we try never to limit access
 160   for a legitimate login.
 161
 162 6. PROBLEMS WITH DROPPED CONNECTIONS
 163
 164   Our PM3, with 2 ISDN-30 lines coming into it, had the habit of sometimes
 165   dropping connections. In a few cases, the portmaster thought the session was
 166   still alive so if the user tried to login again, he or she was denied access.
 167   In our case, this problem was caused by a bad PRI line from the phone
 168   company.
 169
 170   We tried to compensate this by setting the Idle-Timeout to 15 minutes. That
 171   way, even if a user did get locked out the portmaster would clear the rogue
 172   session within 15 minutes and the user could login again.
 173