README.rst

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