README.rst

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