summaryrefslogtreecommitdiffstats
path: root/README.rst
diff options
context:
space:
mode:
Diffstat (limited to 'README.rst')
-rw-r--r--README.rst179
1 files changed, 179 insertions, 0 deletions
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..75cc11c
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,179 @@
+The FreeRADIUS server
+=====================
+
+|BuildStatus|_ |CoverityStatus|_
+
+.. contents::
+ :local:
+
+Introduction
+------------
+
+The FreeRADIUS Server Project is a high performance and highly
+configurable multi-protocol policy server, supporting RADIUS, DHCPv4
+and VMPS. It is available under the terms of the GNU GPLv2.
+Using RADIUS allows authentication and authorization for a network
+to be centralized, and minimizes the number of changes that have to
+be done when adding or deleting new users to a network.
+
+FreeRADIUS can authenticate users on systems such as 802.1X (WiFi),
+dialup, PPPoE, VPN's, VoIP, and many others. It supports back-end
+databases such as MySQL, PostgreSQL, Oracle, Microsoft Active
+Directory, Redis, OpenLDAP, and many more. It is used daily to
+authenticate the Internet access for hundreds of millions of people,
+in sites ranging from 10 to 10 million+ users.
+
+Version 3.0 of the server is largely compatible with version 2.x, but
+we highly recommend that you recreate your configuration, rather than
+trying to get the older configuration to work.
+
+For a list of changes in version 3.0, please see ``doc/ChangeLog``.
+
+See ``raddb/README.rst`` for information on what to do to update your
+configuration.
+
+Administrators upgrading from a previous version should install this
+version in a different location from their existing systems. Any
+existing configuration should be carefully migrated to the new
+version, in order to take advantage of the new features which can
+greatly simply configuration.
+
+Please see https://freeradius.org and https://wiki.freeradius.org for
+more information.
+
+
+Installation
+------------
+
+To install the server, please see the INSTALL file in this directory.
+
+Configuring the server
+----------------------
+
+We understand that the server may be difficult to configure,
+install, or administer. It is, after all, a complex system with many
+different configuration possibilities.
+
+The most common problem is that people change large amounts of the
+configuration without understanding what they're doing, and without
+testing their changes. The preferred method of operation is the
+following:
+
+1. Start off with the default configuration files.
+2. Save a copy of the default configuration: It WORKS. Don't change it!
+3. Verify that the server starts - in debugging mode (``radiusd -X``).
+4. Send it test packets using "radclient", or a NAS or AP.
+5. Verify that the server does what you expect
+
+ - If it does not work, change the configuration, and go to step (3)
+ - If you're stuck, revert to using the "last working" configuration.
+ - If it works, proceed to step (6).
+
+6. Save a copy of the working configuration, along with a note of what
+ you changed, and why.
+7. Make a SMALL change to the configuration.
+8. Repeat from step (3).
+
+This method will ensure that you have a working configuration that
+is customized to your site as quickly as possible. While it may seem
+frustrating to proceed via a series of small steps, the alternative
+will always take more time. The "fast and loose" way will be MORE
+frustrating than quickly making forward progress!
+
+Debugging the Server
+--------------------
+
+Run the server in debugging mode, (``radiusd -X``) and READ the output.
+We cannot emphasize this point strongly enough. The vast majority of
+problems can be solved by carefully reading the debugging output,
+which includes WARNINGs about common issues, and suggestions for how
+they may be fixed.
+
+Many questions are answered on the Wiki:
+
+https://wiki.freeradius.org
+
+Read the configuration files. Many parts of the server are
+documented only with extensive comments in the configuration files.
+
+Search the mailing lists. For example, using Google, searching
+"site:lists.freeradius.org <search term>" will return results from
+the FreeRADIUS mailing lists.
+
+https://freeradius.org/support/
+
+
+Feedback, Defects, and Community Support
+----------------------------------------
+
+If you have any comments, or are having difficulty getting FreeRADIUS
+to do what you want, please post to the 'freeradius-users' list
+(see the URL above). The FreeRADIUS mailing list is operated, and
+contributed to, by the FreeRADIUS community. Users of the list will be
+more than happy to answer your questions, with the caveat that you've
+read documentation relevant to your issue first.
+
+If you suspect a defect in the server, would like to request a feature,
+or submit a code patch, please use the GitHub issue tracker for the
+freeradius-server `repository
+<https://github.com/FreeRADIUS/freeradius-server>`_. However, it
+is nearly always best to raise the issue on the mailing lists
+first to determine whether it really is a defect or missing
+feature.
+
+Instructions for gathering data for defect reports can be found in
+``doc/bugs`` or on the `wiki
+<https://wiki.freeradius.org/project/bug-reports>`_.
+
+Under no circumstances should the issue tracker be used for support
+requests, those questions belong on the user's mailing list. If you
+post questions related to the server in the issue tracker, the issue
+will be closed and locked. If you persist in positing questions to
+the issue tracker you will be banned from all FreeRADIUS project
+repositories on GitHub.
+
+Please do NOT complain that the developers aren't answering your
+questions quickly enough, or aren't fixing the problems quickly
+enough. Please do NOT complain if you're told to go read
+documentation. We recognize that the documentation isn't perfect, but
+it *does* exist, and reading it can solve most common questions.
+
+FreeRADIUS is the cumulative effort of many years of work by many
+people, and you've gotten it for free. No one is getting paid to answer
+your questions. This is free software, and the only way it gets better
+is if you make a contribution back to the project ($$, code, or
+documentation).
+
+We will note that the people who get most upset about any answers to
+their questions usually do not have any intention of contributing to
+the project. We will repeat the comments above: no one is getting
+paid to answer your questions or to fix your bugs. If you don't like
+the responses you are getting, then fix the bug yourself, or pay
+someone to address your concerns. Either way, make sure that any fix
+is contributed back to the project so that no one else runs into the
+same issue.
+
+Books on RADIUS
+---------------
+
+See ``doc/README`` for more information about FreeRADIUS.
+
+There is an O'Reilly book available. It serves as a good
+introduction for anyone new to RADIUS. However, it is almost 20 years
+old, and is not much more than a basic introduction to the subject.
+
+https://www.amazon.com/exec/obidos/ASIN/0596003226/freeradiusorg-20/
+
+Commercial support
+------------------
+
+Technical support, managed systems support, custom deployments,
+sponsored feature development and many other commercial services
+are available from `Network RADIUS <https://networkradius.com>`_.
+
+
+.. |CoverityStatus| image:: https://scan.coverity.com/projects/58/badge.svg?
+.. _CoverityStatus: https://scan.coverity.com/projects/58
+
+.. |BuildStatus| image:: https://github.com/FreeRADIUS/freeradius-server/workflows/CI/badge.svg?branch=v3.2.x
+.. _BuildStatus: https://github.com/FreeRADIUS/freeradius-server/actions?query=workflow%3ACI