X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=README.rst;h=45005faf856682d2f1d6f7b5743685de2c49ed14;hb=refs%2Fheads%2Ftr-integ;hp=e974439fa7ccd4f07834484e8be6f0fd323412e2;hpb=e044f1801d2a94c3d54f7ed603ab96466b0f53cb;p=freeradius.git diff --git a/README.rst b/README.rst index e974439..45005fa 100644 --- a/README.rst +++ b/README.rst @@ -10,18 +10,18 @@ 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 +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, OpenLDAP, and many more. It is used daily to authenticate -the Internet access for hundreds of millions of people, in sites -ranging from 10 users, to 10 million and more users. +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 @@ -47,6 +47,38 @@ 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 -------------------- @@ -73,56 +105,31 @@ Type some key words into the search box, and you should find discussions about common problems and solution. -Additional Information ----------------------- - -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 12 years -old, and is not much more than a basic introduction to the subject. - -http://www.amazon.com/exec/obidos/ASIN/0596003226/freeradiusorg-20/ - -Problems and Concerns ---------------------- +Feedback, Defects, and Community Support +---------------------------------------- -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. +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. -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: +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 +`_. -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. (You ARE using debugging mode, right?) -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). +Instructions for gathering data for defect reports can be found in +``doc/bugs`` or on the `wiki +`_. -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! - - -Feedback --------- - -If you have any comments, bug reports, problems, or concerns, please -send them to the 'freeradius-users' list (see the URL above). We will -do our best to answer your questions, to fix the problems, and to -generally improve the server in any way we can. +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 @@ -131,10 +138,10 @@ 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 gets paid to work on -FreeRADIUS, and 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). +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 @@ -145,17 +152,28 @@ 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. -Support is available. See the "support" link at the top of the main -web page: +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 12 years +old, and is not much more than a basic introduction to the subject. + +http://www.amazon.com/exec/obidos/ASIN/0596003226/freeradiusorg-20/ + +Commercial support +------------------ -http://freeradius.org +Technical support, managed systems support, custom deployments, +sponsored feature development and many other commercial services +are available from `Network RADIUS +`_. -Please submit bug reports, suggestions, or patches. That feedback -gives the developers a guide as to where they should focus their work. -If you like the server, feel free to mail the list and say so. .. |CoverityStatus| image:: https://scan.coverity.com/projects/58/badge.svg? .. _CoverityStatus: https://scan.coverity.com/projects/58 -.. |BuildStatus| image:: https://travis-ci.org/FreeRADIUS/freeradius-server.png?branch=master +.. |BuildStatus| image:: https://travis-ci.org/FreeRADIUS/freeradius-server.png?branch=v3.0.x .. _BuildStatus: https://travis-ci.org/FreeRADIUS/freeradius-server