README.rst

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