README.rst

   1 The FreeRADIUS server
   2 =====================
   3
   4 0. BRANCH STATE
   5 ---------------
   6 .. |CoverityStatus| image:: https://scan.coverity.com/projects/58/badge.svg?
   7 .. _CoverityStatus: https://scan.coverity.com/projects/58
   8
   9 .. |BuildStatus| image:: https://travis-ci.org/FreeRADIUS/freeradius-server.png
  10 .. _BuildStatus: https://travis-ci.org/FreeRADIUS/freeradius-server
  11
  12 |BuildStatus|_ |CoverityStatus|_
  13
  14 1. INTRODUCTION
  15 ---------------
  16
  17 The FreeRADIUS Server Project is a high performance and highly
  18 configurable RADIUS server that is available under the terms of the
  19 GNU GPLv2.  Using RADIUS allows authentication and authorization for a
  20 network to be centralized, and minimizes the number of changes that
  21 have to be done when adding or deleting new users to a network.
  22
  23 FreeRADIUS can authenticate users on systems such as 802.1x (WiFi),
  24 dialup, PPPoE, VPN's, VoIP, and many others.  It supports back-end
  25 databases such as MySQL, PostgreSQL, Oracle, Microsoft Active
  26 Directory, OpenLDAP, and many more.  It is used daily to authenticate
  27 the Internet access for hundreds of millions of people, in sites
  28 ranging from 10 users, to 10 million and more users.
  29
  30 Version 3.0 of the server is largely compatible with version 2.x, but
  31 we highly recommend that you recreate your configuration, rather than
  32 trying to get the older configuration to work.
  33
  34 For a list of changes in version 3.0, please see ``doc/ChangeLog``.
  35
  36 See ``raddb/README.rst`` for information on what to do to update your
  37 configuration.
  38
  39 Administrators upgrading from a previous version should install this
  40 version in a different location from their existing systems.  Any
  41 existing configuration should be carefully migrated to the new
  42 version, in order to take advantage of the new features which can
  43 greatly simply configuration.
  44
  45 Please see http://freeradius.org and http://wiki.freeradius.org for
  46 more information.
  47
  48
  49 2. INSTALLATION
  50 ---------------
  51
  52 To install the server, please see the INSTALL file in this directory.
  53
  54
  55 3. DEBUGGING THE SERVER
  56 -----------------------
  57
  58 Run the server in debugging mode, (``radiusd -X``) and READ the output.
  59 We cannot emphasize this point strongly enough.  The vast majority of
  60 problems can be solved by carefully reading the debugging output,
  61 which includes WARNINGs about common issues, and suggestions for how
  62 they may be fixed.
  63
  64 Read the FAQ.  Many questions are answered there.  See the Wiki
  65
  66 http://wiki.freeradius.org
  67
  68 Read the configuration files.  Many parts of the server have NO
  69 documentation, other than comments in the configuration file.
  70
  71 Search the mailing lists.  There is a Google link on the bottom of
  72 the page:
  73
  74 http://www.freeradius.org/list/users.html
  75
  76 Type some key words into the search box, and you should find
  77 discussions about common problems and solution.
  78
  79
  80 4. ADDITIONAL INFORMATION
  81 -------------------------
  82
  83 See ``doc/README`` for more information about FreeRADIUS.
  84
  85 There is an O'Reilly book available.  It serves as a good
  86 introduction for anyone new to RADIUS.  However, it is almost 11 years
  87 old, and is not much more than a basic introduction to the subject.
  88
  89 http://www.amazon.com/exec/obidos/ASIN/0596003226/freeradiusorg-20/
  90
  91 For other RADIUS information, the Livington internet site had a lot
  92 of information about radius online.  Unfortunately Livingston, and the
  93 site, don't exist anymore but there is a copy of the site still at:
  94
  95 http://portmasters.com/www.livingston.com/
  96
  97 Especially worth reading is the "RADIUS for Unix administrators guide"
  98
  99 * HTML:  http://portmasters.com/tech/docs/radius/1185title.html
 100 * PDF:   http://portmasters.com/tech/docs/pdf/radius.pdf
 101
 102
 103 5. PROBLEMS AND CONCERNS
 104 ------------------------
 105
 106 We understand that the server may be difficult to configure,
 107 install, or administer.  It is, after all, a complex system with many
 108 different configuration possibilities.
 109
 110 The most common problem is that people change large amounts of the
 111 configuration without understanding what they're doing, and without
 112 testing their changes.  The preferred method of operation is the
 113 following:
 114
 115 1. Start off with the default configuration files.
 116 2. Save a copy of the default configuration: It WORKS.  Don't change it!
 117 3. Verify that the server starts.  (You ARE using debugging mode, right?)
 118 4. Send it test packets using "radclient", or a NAS or AP.
 119 5. Verify that the server does what you expect.
 120       - If it does not work, change the configuration, and go to step (3)
 121         If you're stuck, revert to using the "last working" configuration.
 122       - If it works, proceed to step (6).
 123 6. Save a copy of the working configuration, along with a note of what
 124    you changed, and why.
 125 7. Make a SMALL change to the configuration.
 126 8. Repeat from step (3).
 127
 128 This method will ensure that you have a working configuration that
 129 is customized to your site as quickly as possible.  While it may seem
 130 frustrating to proceed via a series of small steps, the alternative
 131 will always take more time.  The "fast and loose" way will be MORE
 132 frustrating than quickly making forward progress!
 133
 134
 135 6. FEEDBACK
 136 -----------
 137
 138 If you have any comments, bug reports, problems, or concerns, please
 139 send them to the 'freeradius-users' list (see the URL above).  We will
 140 do our best to answer your questions, to fix the problems, and to
 141 generally improve the server in any way we can.
 142
 143 Please do NOT complain that the developers aren't answering your
 144 questions quickly enough, or aren't fixing the problems quickly
 145 enough.  Please do NOT complain if you're told to go read
 146 documentation.  We recognize that the documentation isn't perfect, but
 147 it *does* exist, and reading it can solve most common questions.
 148
 149 FreeRADIUS is the cumulative effort of many years of work by many
 150 people, and you've gotten it for free.  No one gets paid to work on
 151 FreeRADIUS, and no one is getting paid to answer your questions.  This
 152 is free software, and the only way it gets better is if you make a
 153 contribution back to the project ($$, code, or documentation).
 154
 155 We will note that the people who get most upset about any answers to
 156 their questions usually do not have any intention of contributing to
 157 the project.  We will repeat the comments above: no one is getting
 158 paid to answer your questions or to fix your bugs.  If you don't like
 159 the responses you are getting, then fix the bug yourself, or pay
 160 someone to address your concerns.  Either way, make sure that any fix
 161 is contributed back to the project so that no one else runs into the
 162 same issue.
 163
 164 Support is available.  See the "support" link at the top of the main
 165 web page:
 166
 167 http://freeradius.org
 168
 169 Please submit bug reports, suggestions, or patches.  That feedback
 170 gives the developers a guide as to where they should focus their work.
 171 If you like the server, feel free to mail the list and say so.