README.rst

   1 The FreeRADIUS server
   2 =====================
   3 |BuildStatus|_
   4
   5 0. VERSION 2 IS END OF LIFE
   6 ---------------------------
   7
   8 The version 2 branch of FreeRADIUS is officially end of life (EOL).
   9 We may push security fixes for safety reasons, but no more.
  10
  11 i.e. **THERE WILL BE NO MORE RELEASES OF VERSION 2**.
  12
  13 Anyone using version 2 is *strongly recommended* to ugprade to
  14 version 3.  Questions on the freeradius-users mailing list about
  15 version 2 will be answered with a recommendation to upgrade to
  16 version 3.
  17
  18 1. INTRODUCTION
  19 ---------------
  20
  21 The FreeRADIUS Server Project is a high performance and highly
  22 configurable AAA server.  Is available under the terms of the GNU
  23 GPLv2.  It has been in steady development for over a decade.  It is
  24 the most widely used RADIUS server in the world, by quite a large
  25 margin.
  26
  27 AAA stands for "Authentication, Authorization, and Accounting".  The
  28 server can do any or all of the AAA functions, across three protocols:
  29 RADIUS, DHCP, and VMPS.  The reason is that at its core, it is a
  30 policy engine.  The policy engine connects network protocols to
  31 back-end systems such as SQL, LDAP, Active Directory, etc.
  32
  33 FreeRADIUS started out as a RADIUS server, of course.  We then added
  34 VMPS and DHCP when it became clear that doing so was both easy and
  35 useful.
  36
  37 It supports all popular authentication methods for RADIUS.  This
  38 includes PAP, CHAP, MS-CHAP, EAP, etc.  It works with all known
  39 networking equipment.  The authors of FreeRADIUS have written the
  40 official specifications for how RADIUS works (RFC 5080 and RFC 6158,
  41 among others).  It is compliant with all RADIUS standards.  This means
  42 that if a NAS does not inter-operate with FreeRADIUS, the most likely
  43 reason is that the NAS is wrong.
  44
  45 FreeRADIUS can authenticate users on systems such as 802.1x (WiFi),
  46 dialup, PPPoE, VPN's, VoIP, and many others.  It supports back-end
  47 databases such as MySQL, PostgreSQL, Oracle, Microsoft Active
  48 Directory, OpenLDAP, and many more.  It is used daily to authenticate
  49 the Internet access for hundreds of millions of people, in sites
  50 ranging from 10 users, to 10 million and more users.  It is used in
  51 appliances, WiFi boxes, ISPs, enterprises, and large
  52 telecommunications providers.
  53
  54 Version 2.2 of the server is intended to be backwards compatible with
  55 previous versions.  It has features not available in Version 1, many
  56 of which are also not available in any commercial server.
  57
  58 * simple policy language (see ``man unlang``)
  59 * virtual servers (raddb/sites-available/README)
  60 * DHCP support (server and relay)
  61 * VMPS support
  62 * IPv6 support
  63 * better proxy support (raddb/proxy.conf)
  64 * More EAP types
  65 * verbose and descriptive Debugging output
  66 * Almost 50 "stable" modules, and many more experimental ones.
  67 * Sample SQL configuration for all major SQL databases.
  68 * Some support for on-the-fly changing of configuration (HUP)
  69 * check configuration test (``radiusd -C``)
  70 * Event-based server core.
  71
  72 Please see http://freeradius.org and http://wiki.freeradius.org for
  73 more information.
  74
  75
  76 2. INSTALLATION
  77 ---------------
  78
  79 To install the server, please see the INSTALL file in this directory.
  80 In general, we recommend using a pre-packaged installation for your
  81 operating system.
  82
  83
  84 3. DEBUGGING THE SERVER
  85 -----------------------
  86
  87 RADIUS systems can be complicated to configure.  Unlike a simple
  88 "query-response" protocol such as DNS, RADIUS systems need to juggle
  89 large amounts of information.  There may be dozens of attributes in
  90 the request.  Processing the request may involve querying any or all
  91 of LDAP, SQL, flat files, external scripts, etc.
  92
  93 There is no easy solution to creating a working RADIUS configuration.
  94 The only method that works is to run the server in debugging mode,
  95 (``radiusd -X``) and READ the output.  We cannot emphasize this point
  96 strongly enough.  The vast majority of problems can be solved by
  97 carefully reading the debugging output, which includes WARNINGs about
  98 common issues, and suggestions for how they may be fixed.
  99
 100 Read the FAQ.  Many questions are answered there.  See the Wiki
 101
 102 http://wiki.freeradius.org
 103
 104 Read the configuration files.  Many parts of the server have NO
 105 documentation, other than comments in the configuration file.  That
 106 being said, there are dozens of examples in the configuration files.
 107 The configuration items are extensively commented, with all of their
 108 behavior documented.
 109
 110 Search the mailing lists.  Many questions come up repeatedly, and are
 111 answered there.  There is a Google link on the bottom of the page:
 112
 113 http://www.freeradius.org/list/users.html
 114
 115 Type some key words into the search box, and you should find
 116 discussions about common problems and solution.
 117
 118
 119 4. ADDITIONAL INFORMATION
 120 -------------------------
 121
 122 See 'doc/README' for more information about FreeRADIUS.
 123
 124 See raddb/sites-available/README for documentation on virtual servers.
 125
 126 5. PROBLEMS AND CONCERNS
 127 ------------------------
 128
 129 We understand that the server may be difficult to configure,
 130 install, or administer.  It is, after all, a complex system with many
 131 different configuration possibilities.
 132
 133 The most common problem is that people change large amounts of the
 134 configuration without understanding what they're doing, and without
 135 testing their changes.  The preferred method of operation is the
 136 following:
 137
 138 1. Start off with the default configuration files.
 139 2. Save a copy of the default configuration: It WORKS.  Don't change it!
 140 3. Run the server in debugging mode. (radiusd -X)
 141 4. Send it test packets using "radclient", or a NAS or AP.
 142 5. Verify that the server does what you expect.
 143       - If it does not work, change the configuration, and go to step (3)
 144         If you're stuck, revert to using the "last working" configuration.
 145       - If it works, proceed to step (6).
 146 6. Save a copy of the working configuration, along with a note of what
 147    you changed, and why.
 148 7. Make a SMALL change to the configuration.
 149 8. Repeat from step (3).
 150
 151 This method will ensure that you have a working configuration that
 152 is customized to your site as quickly as possible.  While it may seem
 153 frustrating to proceed via a series of small steps, the alternative
 154 will always take more time.  The "fast and loose" way will be MORE
 155 frustrating than quickly making forward progress!
 156
 157
 158 6. FEEDBACK
 159 -----------
 160
 161 If you have any comments, bug reports, problems, or concerns, please
 162 send them to the 'freeradius-users' list (see the URL above).  We will
 163 do our best to answer your questions, to fix the problems, and to
 164 generally improve the server in any way we can.
 165
 166 Please do NOT complain that the developers aren't answering your
 167 questions quickly enough, or aren't fixing the problems quickly
 168 enough.  Please do NOT complain if you're told to go read
 169 documentation.  We recognize that the documentation isn't perfect, but
 170 it *does* exist, and reading it can solve most common questions.
 171
 172 The list policy changed in mid 2012, due to the high volume of
 173 inappropriate posts from a subset of users.  These users would refuse
 174 to read the documentation, even when asked to.  They would ask
 175 questions, and then refuse to follow the instructions given them on
 176 the list.  They would argue over the answers given on the list, even
 177 when it was clear that they understood less about RADIUS than the
 178 people trying to help them.
 179
 180 The new policy is to warn people engaging in this asocial behavior.
 181 If they continue after a warning, they are unsubscribed and banned
 182 permanently from the list.
 183
 184 The decision to enforce etiquette came after over 10 years of having a
 185 more open policy.  Sadly, a small subset of users abused the help
 186 given by the volunteers on the list.  This behavior is unacceptable,
 187 and will not be tolerated.
 188
 189 FreeRADIUS is the cumulative effort of many years of work by many
 190 people, and you've gotten it for free.  No one gets paid to work on
 191 FreeRADIUS, and no one is getting paid to answer your questions.
 192
 193 If you want the community to help you, you need to make it easy for
 194 the community to help you.
 195
 196 Support is available.  See http://networkradius.com/.
 197
 198 Please submit bug reports, suggestions, or patches.  That feedback
 199 gives the developers a guide as to where they should focus their work.
 200 If you like the server, feel free to mail the list and say so.
 201
 202 .. |BuildStatus| image:: https://travis-ci.org/FreeRADIUS/freeradius-server.png?branch=v2.x.x
 203 .. _BuildStatus: https://travis-ci.org/FreeRADIUS/freeradius-server