- Submitting patches or diff's to the FreeRADIUS project
+Submitting patches or diff's to the FreeRADIUS project
+======================================================
For a person or company wishing to submit a change to the
FreeRADIUS project, the process can sometimes be daunting if you're
being accepted.
SECTION 1 - CREATING AND SENDING YOUR CHANGE
+--------------------------------------------
1. "diff -u"
When in doubt, re-submit.
SECTION 2 - HINTS, TIPS, AND TRICKS
+-----------------------------------
This section lists many of the common "rules" associated with code
submitted to the project. There are always exceptions... but you must
-How Authorization, Authentication, and Accounting requests are handled
-======================================================================
+Authorization, Authentication, and Accounting request handling
+==============================================================
There are a lot of questions about misconfigured FreeRADIUS servers
because of misunderstanding of FreeRADIUS operations. This document
use FreeRADIUS as a proxy): authorization and authentication.
-AUTHORIZATION
+Authorization
-------------
Authorization is a process of obtaining information about the user
authentication method. So during the authorize phase, we can deny
them the ability to use that kind of authentication.
-
-AUTHENTICATION
+Authentication
--------------
Authentication is simply a process of comparing user's credentials in
passwords to access an SQL server.
-PROCESSING A REQUEST
---------------------
+Request Processing
+------------------
During authorization and authentication processes, there are 3 lists
of RADIUS attributes supported by FreeRADIUS: request items, config
value of 'MS-CHAP' into same list. The same goes for NT-Password
(before calling MS-CHAP Password attribute should be converted to
NT-Password, it may be achieved by calling mschap module in
-authorization section after module which does actual authorization).
\ No newline at end of file
+authorization section after module which does actual authorization).
- Helpful coding methods
- by Alan DeKok <aland@ox.org>
+Helpful coding methods
+======================
- The following is a short set of guidelines to follow while
+The following is a short set of guidelines to follow while
programming. It does not address coding styles, function naming
methods, or debugging methods. Rather, it describes the processes
which SHOULD go on in the programmers mind, while he is programming.
- Coding standards apply to function names, the look of the code, and
+Coding standards apply to function names, the look of the code, and
coding consistency. Coding methods apply to the daily practices used
by the programmer to write code.
Your function CANNOT do anything right if you called another
function, and they gave you garbage output.
- One of the most common mistakes is:
+ One of the most common mistakes is::
- fp = fopen(...);
- fgetc(fp); /* core dumps! */
+ fp = fopen(...);
+ fgetc(fp); /* core dumps! */
If the programmer had bothered to check for a NULL fp (error
condition), then he could have produced a DESCRIPTIVE error
and numbers.
Don't put tabs in string constants, either. Always use '\t' to
- represent a tab, instead of ASCII 9. Literal tabs are presented to
+ represent a tab, instead of ASCII 9. Literal tabs are presented to
readers of your code as arbitrary whitespace, and it's easy to mess
up.
:maxdepth: 2
aaa
- release-method
ldap_howto
+ load-balance
+
+ coding-methods
+ DIFFS
+ release-method
Indices and tables
==================
-Freeradius OpenLDAP HOWTO
-=========================
+LDAP Configuration
+==================
This document describes how to setup Freeradius on a Freebsd machine
using LDAP as a backend. This is by no means complete and your
will process the modules in the order specified in the authorization section of
radiusd.conf. Currently, they are in the following order.
-preprocess
-suffix
-files
-ldap
+1) preprocess
+2) suffix
+3) files
+4) ldap
The first module will be preprocess. This will first check the huntgroups of
the user coming in. The huntgroups are defined in the file huntgroups and they
are a group listing of the NAS-IP-Addresses that make the access_request. This
is useful in creating specific actions based on the NAS-IP that the request is
-made from. An example, is below:
+made from. An example, is below::
-isdncombo NAS-IP-Address == 10.10.10.1
-dialup NAS-IP-Address == 10.10.10.2
-dialup NAS-IP-Address == 10.10.10.3
+ isdncombo NAS-IP-Address == 10.10.10.1
+ dialup NAS-IP-Address == 10.10.10.2
+ dialup NAS-IP-Address == 10.10.10.3
We will have one NAS that is used for both ISDN and regular dialup customers,
the other NAS's will be only used for dialup.
User-Profile := "uid=isdn,ou=profiles,ou=radius,dc=mydomain,dc=com"
Fall-Through = no
- DEFAULT Huntgroup-Name == dial, Ldap-Group == dial, User-Profile := "uid=dial,ou
- =profiles,ou=radius,dc=mydomain,dc=com"
+ DEFAULT Huntgroup-Name == dial, Ldap-Group == dial,
+ User-Profile := "uid=dial,ou=profiles,ou=radius,dc=mydomain,dc=com"
Fall-Through = no
DEFAULT Auth-Type := Reject
----End slapd.conf----
-To create a rootdn that is not stored in plain text, enter the following
-command::
+To create a rootdn that is not stored in plain text, enter the following command::
$ slappasswd
-------------------------------
The client programs used to connect to the ldap directory are:
- -ldapadd to add a record
- -ldapmodify to modify a record
- -ldapdelete to delete a record
- -ldapsearch to search for a record
- -slapcat to show the entire directory
- -slappaswd to generate a crypted password
+
+ldapadd:
+ to add a record
+ldapmodify:
+ to modify a record
+ldapdelete:
+ to delete a record
+ldapsearch:
+ to search for a record
+slapcat:
+ to show the entire directory
+slappaswd:
+ to generate a crypted password
Read the man pages on those commands, they tell you everything you
need to know.
They all follow this basic syntax::
- $ ldapwhatever -D "uid=someone,ou=admins,ou=radius,dc=mydomain,dc=com" -w
- thesecret -andthenotherstuff
+ $ ldapwhatever -D "uid=someone,ou=admins,ou=radius,dc=mydomain,dc=com" -w thesecret -andthenotherstuff
Finally, if you are having trouble with LDAP, run it in debug mode by
-changing the following in slapd.sh:
+changing the following in slapd.sh::
+
+ slapd_args=
+
+to::
-slapd_args=
-to
-slapd_args= '-d 3'
+ slapd_args= '-d 3'
There is a program included with freeradius to test the radius server,
its called radclient. Typing it alone will tell you all the options.
FREERADIUS
++++++++++
-Main Site:
- -http://www.freeradius.org
-Documentation:
- -http://www.freeradius.org/radiusd/doc
+* _`FreeRADIUS`: http://www.freeradius.org
+* _`FreeRADIUS Documentation`: http://www.freeradius.org/radiusd/doc
+* _`FreeRADIUS Wiki`: http://wiki.freeradius.org/
OPENLDAP
++++++++
-Main Site
- -http://www.openldap.org
-Documentation: Administrator's Guide
- -http://www.openldap.org/doc/admin21
+* _`OpenLDAP`: http://www.openldap.org
+* _`OpenLDAP Administrator's Guide`: http://www.openldap.org/doc/admin21
RFCs
++++
-RFC2865: RADIUS Authentication
- -http://www.freeradius.org/radiusd/doc/rfc/rfc2865.txt
-RFC2866: RADIUS Accounting
- -http://www.freeradius.org/radiusd/doc/rfc/rfc2866.txt
-RFC2869: RADIUS Extentions
- -http://www.freeradius.org/radiusd/doc/rfc/rfc2869.txt
-RFC2251: LDAP v3
- -http://www.ietf.org/rfc/rfc2251.txt
-RFC2252: LDAP v3 Attribute Syntax Definitions
- -http://www.ietf.org/rfc/rfc2252.txt
-RFC2253: LDAP UTF-8 String Representation of Distinguishe d Names (DNs)
- -http://www.ietf.org/rfc/rfc2252.txt
-RFC2849: LDAP Data Interchange Fromat (LDIFs)
- -http://www.ietf.org/rfc/rfc2849.txt
-RFC3377: LDAP v3 Technical Specs
- -http://www.ietf.org/rfc/rfc3377.txt
+* _`RFC2865: RADIUS Authentication`: http://www.freeradius.org/radiusd/doc/rfc/rfc2865.txt
+* _`RFC2866: RADIUS Accounting`: http://www.freeradius.org/radiusd/doc/rfc/rfc2866.txt
+* _`RFC2869: RADIUS Extentions`: http://www.freeradius.org/radiusd/doc/rfc/rfc2869.txt
+* _`RFC2251: LDAP v3`: http://www.ietf.org/rfc/rfc2251.txt
+* _`RFC2252: LDAP v3 Attribute Syntax Definitions`: http://www.ietf.org/rfc/rfc2252.txt
+* _`RFC2253: LDAP UTF-8 String Representation of Distinguishe d Names (DNs)`: http://www.ietf.org/rfc/rfc2252.txt
+* _`RFC2849: LDAP Data Interchange Fromat (LDIFs)`: http://www.ietf.org/rfc/rfc2849.txt
+* _`RFC3377: LDAP v3 Technical Specs`: http://www.ietf.org/rfc/rfc3377.txt
--- /dev/null
+Load Balancing
+==============
+
+As of version 2.0.0, the load balance documentation is in the
+available in the "unlang" man page. The text below may not be up to
+date, and is here only for historical purposes.
+
+As of version 1.1.0, FreeRADIUS supports load balancing in module
+sections. Please see the "configurable_failover" file in this
+directory for a more complete description of module sections.
+
+The short summary is that you can use a "load-balance" section in
+any place where a module name may be used. The semantics of the
+"load-balance" section are that one of the modules in the section will
+be chosen at random, evenly spread over the modules in the list.
+
+An example is below::
+
+ accounting {
+ load-balance {
+ sql1
+ sql2
+ sql2
+ }
+ }
+
+In this case, 1/3 of the RADIUS requests will be processed by
+"sql1", one third by "sql2", and 1/3 by "sql3".
+
+The "load-balance" section can be nested in a "redundant" section,
+or vice-versa::
+
+ accounting {
+ load-balance { # between two redundant sections below
+ redundant {
+ sql1
+ sql2
+ }
+ redundant {
+ sql2
+ sql1
+ }
+ }
+ }
+
+This says "load balance between sql1 and sql2, but if sql1 is down,
+use sql2, and if sql2 is down, use sql1". That way, you can guarantee
+both that load balancing occurs, and that the requests are *always*
+logged to one of the databases::
+
+ accounting {
+ redundant {
+ load-balance {
+ sql1
+ sql2
+ }
+ detail
+ }
+ }
+
+This says "load balance between sql1 and sql2, but if the one being
+used is down, then log to detail".
+
+And finally::
+
+ accounting {
+ redundant { # between load-balance & detail
+ load-balance { # between two redundant sections
+ redundant {
+ sql1
+ sql2
+ }
+ redundant {
+ sql2
+ sql1
+ }
+ }
+ detail
+ }
+ }
+
+This says "try to load balance between sql1 and sql2; if sql1 is down,
+use sql2; if sql2 is down use sql1; if both sql1 and sql2 are down,
+then log to the detail file"
+
+
+More complicated scenarios
+--------------------------
+
+If you want to do redundancy and load-balancing among three
+modules, the configuration is quite complex::
+
+ load-balance {
+ redundant {
+ sql1
+ load-balance {
+ redundant {
+ sql2
+ sql3
+ }
+ redundant {
+ sql3
+ sql2
+ }
+ }
+ } # sql1, etc.
+ redundant {
+ sql2
+ load-balance {
+ redundant {
+ sql3
+ sql1
+ }
+ redundant {
+ sql1
+ sql3
+ }
+ }
+ } # sql2, etc.
+ redundant {
+ sql3
+ load-balance {
+ redundant {
+ sql1
+ sql2
+ }
+ redundant {
+ sql2
+ sql1
+ }
+ }
+ } # sql3, etc.
+ }
+
+For four or more modules, it quickly becomes unmanageable.
+
+The solution is to use the "redundant-load-balance" section, which
+combines the features of "load-balance", with "redundant" fail-over
+between members. The above complex configuration for three modules
+then becomes::
+
+ redundant-load-balance {
+ sql1
+ sql2
+ sql3
+ }
+
+
+Which means "load-balance evenly among all three servers. If the
+one picked for load-balancing is down, load-balance among the
+remaining two. If that one is down, pick the one remaining 'live'
+server".
+
+The "redundant-load-balance" section can contain any number of
+modules.
+
+
+Interaction with "if" and "else"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's best to have "if" and "else" blocks contain "load-balance" or
+"redundant-load-balance" sections, rather than the other way around.
+The "else" and "elsif" sections cannot appear inside of a
+"load-balance" or "redundant-load-balance" section, because the "else"
+condition would be chose as one of the modules for load-balancing,
+which is not what you want.
+
+It's OK to have a plain "if" block inside of a "load-balance" or
+"redundant-load-balance" section. In that case, the "if" condition
+checks the return code of the module or group that executed just
+before the "load-balance" section. It does *not* check the return
+code of the previous module in the section.
+++ /dev/null
- As of version 2.0.0, the load balance documentation is in the
-available in the "unlang" man page. The text below may not be up to
-date, and is here only for historical purposes.
-
- As of version 1.1.0, FreeRADIUS supports load balancing in module
-sections. Please see the "configurable_failover" file in this
-directory for a more complete description of module sections.
-
- The short summary is that you can use a "load-balance" section in
-any place where a module name may be used. The semantics of the
-"load-balance" section are that one of the modules in the section will
-be chosen at random, evenly spread over the modules in the list.
-
- An example is below:
-
-accounting {
- load-balance {
- sql1
- sql2
- sql2
- }
-}
-
- In this case, 1/3 of the RADIUS requests will be processed by
-"sql1", one third by "sql2", and 1/3 by "sql3".
-
- The "load-balance" section can be nested in a "redundant" section,
-or vice-versa:
-
-accounting {
- load-balance { # between two redundant sections below
- redundant {
- sql1
- sql2
- }
- redundant {
- sql2
- sql1
- }
- }
-}
-
- This says "load balance between sql1 and sql2, but if sql1 is down,
-use sql2, and if sql2 is down, use sql1". That way, you can guarantee
-both that load balancing occurs, and that the requests are *always*
-logged to one of the databases.
-
-accounting {
- redundant {
- load-balance {
- sql1
- sql2
- }
- detail
- }
-}
-
- This says "load balance between sql1 and sql2, but if the one being
-used is down, then log to detail".
-
- And finally,
-
-accounting {
- redundant { # between load-balance & detail
- load-balance { # between two redundant sections
- redundant {
- sql1
- sql2
- }
- redundant {
- sql2
- sql1
- }
- }
- detail
- }
-}
-
-This says "try to load balance between sql1 and sql2; if sql1 is down,
-use sql2; if sql2 is down use sql1; if both sql1 and sql2 are down,
-then log to the detail file"
-
-
- More complicated scenarios
- ==========================
-
- If you want to do redundancy and load-balancing among three
-modules, the configuration is quite complex:
-
-...
- load-balance {
- redundant {
- sql1
- load-balance {
- redundant {
- sql2
- sql3
- }
- redundant {
- sql3
- sql2
- }
- }
- } # sql1, etc.
- redundant {
- sql2
- load-balance {
- redundant {
- sql3
- sql1
- }
- redundant {
- sql1
- sql3
- }
- }
- } # sql2, etc.
- redundant {
- sql3
- load-balance {
- redundant {
- sql1
- sql2
- }
- redundant {
- sql2
- sql1
- }
- }
- } # sql3, etc.
- }
-...
-
- For four or more modules, it quickly becomes unmanageable.
-
- The solution is to use the "redundant-load-balance" section, which
-combines the features of "load-balance", with "redundant" fail-over
-between members. The above complex configuration for three modules
-then becomes:
-
-...
- redundant-load-balance {
- sql1
- sql2
- sql3
- }
-...
-
- Which means "load-balance evenly among all three servers. If the
-one picked for load-balancing is down, load-balance among the
-remaining two. If that one is down, pick the one remaining 'live'
-server".
-
- The "redundant-load-balance" section can contain any number of
-modules.
-
-
- Interaction with "if" and "else"
- --------------------------------
-
- It's best to have "if" and "else" blocks contain "load-balance" or
-"redundant-load-balance" sections, rather than the other way around.
-The "else" and "elsif" sections cannot appear inside of a
-"load-balance" or "redundant-load-balance" section, because the "else"
-condition would be chose as one of the modules for load-balancing,
-which is not what you want.
-
- It's OK to have a plain "if" block inside of a "load-balance" or
-"redundant-load-balance" section. In that case, the "if" condition
-checks the return code of the module or group that executed just
-before the "load-balance" section. It does *not* check the return
-code of the previous module in the section.
-
-----------------------------------------------------------------------
-$Id$
-HOW TO ISSUE A RELEASE
-======================
-
+Release Method
+==============
As of 2.0, the release process is much simpler. Edit the
Changelog with the version number and any last updates.
vi doc/ChangeLog
cvs commit doc/ChangeLog
-
Change version numbers in the VERSION file:
vi VERSION
make dist-tag
-
Sign the packages. You will need the correct GPG key for this
to work.
projects / freeradius.git / commitdiff