Cleaned up text, and added notes on 2.0

[freeradius.git] / README

diff --git a/README b/README
index 93b59fe..74b569e 100644 (file)
--- a/README
+++ b/README
@@ -4,27 +4,64 @@
 configurable RADIUS server that 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
 configurable RADIUS server that 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 ordeleting new users.
+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
 
   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, 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.
-
-  Version 2.0 of the server is similar in many respects to previous
-versions.  It also contains many new features, such as "virtual
-server" support (raddb/sites-available/README), and a simple policy
-language ("man unlang").  Administrators upgrading from a previous
-version should install this version in a different location from their
-existing systems.  They should then migrate their current
-configuration to the new server, being careful to take advantage of
-the new features which can greatly simply the servers configuration.
-  
-  Please see the web page http://www.freeradius.org for more
-information.  The wiki (http://wiki.freeradius.org) also contains a
-large amount of documentation that addresses common scenarios.
+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.
+
+  Version 2.0 of the server is intended to be backwards compatible
+with previous versions, but also to have many new features, such as:
+
+  * simple policy language (see "man unlang")
+  * virtual servers (raddb/sites-available/README)
+  * IPv6 support
+  * better proxy support (raddb/proxy.conf)
+  * More EAP types
+  * Debugging output should be MUCH easier to understand
+  * VMPS support
+  * More modules are marked "stable" (python, etc.)
+  * SQL configuration has been cleaned up (see raddb/sql/*)
+  * limited support for HUP
+  * check configuration and exit (radiusd -C)
+  * Server core is now event based (simpler, more powerful)
+
+  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.
+
+  While every attempt has been made to ensure that this version is
+backwards compatible with previous versions, there may be cases where
+it is not backwards compatible.  In most cases, incompatibilities are
+a side-effect of fixing bugs, or of adding new features.  Some
+configuration differences are noted below:
+
+  * The recommended format for clients has changed.  See "clients.conf".
+    The old format should still work, but should be changed to use the
+    new format.
+
+  * The recommended formant for realms has changed.  See "proxy.conf"
+    The old format should still work, but should be changed to use the
+    new format.  In addition, the new format has much more flexibility.
+
+  * Any configuration using TTLS or PEAP should be updated to use
+    virtual servers. See "virtual_server" in "eap.conf", and
+    "raddb/sites-available/inner-tunnel".  In most cases, using an
+    "inner-tunnel" virtual server will make the configuration MUCH
+    simpler.
+
+  * A number of deprecated command-line options have been removed.
+    (-y -z -A -l -g) See "man radiusd".  These configurations can be
+    controlled in "radiusd.conf", so it is not necessary to have them
+    as command-line options.
+
+  Please see http://freeradius.org and http://wiki.freeradius.org for
+more information.

 
 
 2. INSTALLATION
 
 
 2. INSTALLATION


@@ -61,19 +98,19 @@ discussions about common problems and solution.
 
   See 'doc/README' for more information about FreeRADIUS.
 
 
   See 'doc/README' for more information about FreeRADIUS.
 

-  There is an O'Reilly book available, which we recommend for people
-new to RADIUS.  It is almost 5 years old, however, and is not much
-more than a basic introduction to the subject.
+  There is an O'Reilly book available.  It serves as a good
+introduction for anyone new to RADIUS.  However, it is almost 5 years
+old, and is not much more than a basic introduction to the subject.

 
 http://www.amazon.com/exec/obidos/ASIN/0596003226/freeradiusorg-20/
 
   For other RADIUS information, the Livington internet site had a lot
 
 http://www.amazon.com/exec/obidos/ASIN/0596003226/freeradiusorg-20/
 
   For other RADIUS information, the Livington internet site had a lot

-of information on radius online.  Unfortunately Livingston, and the
+of information about radius online.  Unfortunately Livingston, and the

 site, don't exist anymore but there is a copy of the site still at:
 
        http://portmasters.com/www.livingston.com/
 
 site, don't exist anymore but there is a copy of the site still at:
 
        http://portmasters.com/www.livingston.com/
 

-  Especially worth a read is the "RADIUS for Unix administrators guide"
+  Especially worth reading is the "RADIUS for Unix administrators guide"

 
 HTML:  http://portmasters.com/tech/docs/radius/1185title.html
 PDF:   http://portmasters.com/tech/docs/pdf/radius.pdf
 
 HTML:  http://portmasters.com/tech/docs/radius/1185title.html
 PDF:   http://portmasters.com/tech/docs/pdf/radius.pdf


@@ -91,7 +128,7 @@ testing their changes.  The preferred method of operation is the
 following:
 
    1) Start off with the default configuration files.
 following:
 
    1) Start off with the default configuration files.

-   2) Save a copy of the default configuration: It WORKS everywhere.
+   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.
    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.


@@ -105,8 +142,9 @@ following:
 
   This method will ensure that you have a working configuration that
 is customized to your site as quickly as possible.  While it may seem
 
   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 is
-worse.
+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!

 
 
 6. FEEDBACK
 
 
 6. FEEDBACK


@@ -116,25 +154,29 @@ 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.
 
 do our best to answer your questions, to fix the problems, and to
 generally improve the server in any way we can.
 

-  What you should NOT do is complain that the developers aren't
-answering your questions quickly enough, or fixing the problems
-quickly enough, or that they're being mean for telling you to do some
-work yourself.  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 contribute work back to the project.
-
-  We will note that the people who complain the loudest about the
-developers being mean usually can't program, can't write
-documentation, won't pay others to do that work, demand that their
-every desire be satisifed immediately by the developers for free, and
-worst of all, don't understand why their attitude is unproductive.
-They seem to believe that because they've received something (the
-server) for free, that they have every right to demand more free
-support and development from the list.  That's simply not true.
-
-  So 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.
+  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 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).
+
+  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.
+
+  Support IS available: http://freeradius.org/business
+
+  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.