README

   1 1. INTRODUCTION
   2
   3   The FreeRADIUS Server Project is a high performance and highly
   4 configurable RADIUS server that is available under the terms of the
   5 GNU GPLv2.  Using RADIUS allows authentication and authorization for a
   6 network to be centralized, and minimizes the number of changes that
   7 have to be done when adding ordeleting new users.
   8
   9   FreeRADIUS can authenticate users on systems such as 802.1x (WiFi),
  10 dialup, PPPoE, VPN's, VoIP, and many others.  It supports back-end
  11 databases such as MySQL, PostgreSQL, Microsoft Active Directory,
  12 OpenLDAP, and many more.  It is used daily to authenticate the
  13 Internet access for hundreds of millions of people, in sites ranging
  14 from 10 users, to 10 million and more users.
  15
  16   Version 2.0 of the server is similar in many respects to previous
  17 versions.  It also contains many new features, such as "virtual
  18 server" support (raddb/sites-available/README), and a simple policy
  19 language ("man unlang").  Administrators upgrading from a previous
  20 version should install this version in a different location from their
  21 existing systems.  They should then migrate their current
  22 configuration to the new server, being careful to take advantage of
  23 the new features which can greatly simply the servers configuration.
  24
  25   Please see the web page http://www.freeradius.org for more
  26 information.  The wiki (http://wiki.freeradius.org) also contains a
  27 large amount of documentation that addresses common scenarios.
  28
  29
  30 2. INSTALLATION
  31
  32   To install the server, please see the INSTALL file in this
  33 directory.
  34
  35
  36 3. DEBUGGING THE SERVER
  37
  38   Run the server in debugging mode, (radiusd -X) and READ the output.
  39 We cannot emphasize this point strongly enough.  The vast majority of
  40 problems can be solved by carefully reading the debugging output,
  41 which includes WARNINGs about common issues, and suggestions for how
  42 they may be fixed.
  43
  44   Read the FAQ.  Many questions are answered there.  See the Wiki
  45
  46         http://wiki.freeradius.org
  47
  48   Read the configuration files.  Many parts of the server have NO
  49 documentation, other than comments in the configuration file.
  50
  51   Search the mailing lists.  There is a Google link on the bottom of
  52   the page:
  53
  54         http://www.freeradius.org/list/users.html
  55
  56   Type some key words into the search box, and you should find
  57 discussions about common problems and solution.
  58
  59
  60 4. ADDITIONAL INFORMATION
  61
  62   See 'doc/README' for more information about FreeRADIUS.
  63
  64   There is an O'Reilly book available, which we recommend for people
  65 new to RADIUS.  It is almost 5 years old, however, and is not much
  66 more than a basic introduction to the subject.
  67
  68 http://www.amazon.com/exec/obidos/ASIN/0596003226/freeradiusorg-20/
  69
  70   For other RADIUS information, the Livington internet site had a lot
  71 of information on radius online.  Unfortunately Livingston, and the
  72 site, don't exist anymore but there is a copy of the site still at:
  73
  74         http://portmasters.com/www.livingston.com/
  75
  76   Especially worth a read is the "RADIUS for Unix administrators guide"
  77
  78 HTML:  http://portmasters.com/tech/docs/radius/1185title.html
  79 PDF:   http://portmasters.com/tech/docs/pdf/radius.pdf
  80
  81
  82 5. PROBLEMS AND CONCERNS
  83
  84   We understand that the server may be difficult to configure,
  85 install, or administer.  It is, after all, a complex system with many
  86 different configuration possibilities.
  87
  88   The most common problem is that people change large amounts of the
  89 configuration without understanding what they're doing, and without
  90 testing their changes.  The preferred method of operation is the
  91 following:
  92
  93    1) Start off with the default configuration files.
  94    2) Save a copy of the default configuration: It WORKS everywhere.
  95    3) Verify that the server starts.  (You ARE using debugging mode, right?)
  96    4) Send it test packets using "radclient", or a NAS or AP.
  97    5) Verify that the server does what you expect.
  98      a) If it does not work, change the configuration, and go to step (3)
  99         If you're stuck, revert to using the "last working" configuration.
 100      b) If it works, proceed to step (6).
 101    6) Save a copy of the working configuration, along with a note
 102       of what you changed, and why.
 103    7) Make a SMALL change to the configuration.
 104    8) Repeat from step (3).
 105
 106   This method will ensure that you have a working configuration that
 107 is customized to your site as quickly as possible.  While it may seem
 108 frustrating to proceed via a series of small steps, the alternative is
 109 worse.
 110
 111
 112 6. FEEDBACK
 113
 114   If you have any comments, bug reports, problems, or concerns, please
 115 send them to the 'freeradius-users' list (see the URL above).  We will
 116 do our best to answer your questions, to fix the problems, and to
 117 generally improve the server in any way we can.
 118
 119   What you should NOT do is complain that the developers aren't
 120 answering your questions quickly enough, or fixing the problems
 121 quickly enough, or that they're being mean for telling you to do some
 122 work yourself.  FreeRADIUS is the cumulative effort of many years of
 123 work by many people, and you've gotten it for free.  No one gets paid
 124 to work on FreeRADIUS, and no one is getting paid to answer your
 125 questions.  This is free software, and the only way it gets better is
 126 if you contribute work back to the project.
 127
 128   We will note that the people who complain the loudest about the
 129 developers being mean usually can't program, can't write
 130 documentation, won't pay others to do that work, demand that their
 131 every desire be satisifed immediately by the developers for free, and
 132 worst of all, don't understand why their attitude is unproductive.
 133 They seem to believe that because they've received something (the
 134 server) for free, that they have every right to demand more free
 135 support and development from the list.  That's simply not true.
 136
 137   So please submit bug reports, suggestions, or patches.  That
 138 feedback gives the developers a guide as to where they should focus
 139 their work.  If you like the server, feel free to mail the list and
 140 say so.