--- /dev/null
+= FreeRADIUS Howto
+
+List with some usual howtos for FreeRADIUS.
+
+## Topics
+
+* [Ascend](ascend.md)
+* [Bay](bay.md)
+* [Cisco](cisco.md)
+* modules
+ * [RADIUS-LDAP-eDirectory](modules/RADIUS-LDAP-eDirectory.md)
+ * [EAP](modules/eap)
+ * [Expiration](modules/expiration.md)
+ * [Krb5](modules/krb5.md)
+ * [LDAP Howto](modules/ldap_howto.md)
+ * [MS-CHAP](modules/mschap.md)
+ * [PAM](modules/pam.md)
+ * [Passwd](modules/passwd.md)
+ * [Python](modules/python.md)
+ * [SoH](modules/soh.md)
+ * [SQL](modules/sql.md)
+ * [SQL-Counter](modules/sqlcounter.md)
+ * [SQL-IP-Pool](modules/sqlippool.md)
+* [Performance Testing](performance-testing.md)
+* [ProxIM](proxim.md)
+* [Supervise Radiusd](supervise-radiusd.md)
+* [Tuning Guide](tuning_guide.md)
+
+// Copyright (C) 2019 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
+// Development of this documentation was sponsored by Network RADIUS SAS.
+include::../img/footer.adoc[]
- Ascend Radius Options
- or
- What happens when a big vendor ignores an RFC
+= Ascend Radius Options
+What happens when a big vendor ignores an RFC
+
+## Description
FreeRADIUS uses Vendor-Specific attributes to send the Ascend attributes.
By default, Ascend NASes send the Ascend specific attributes as NON VSA's,
becomes the OLD Ascend attribute:
X-Ascend-Data-Filter
-
-$Id$
+= BAY Software
+
+## Description
+
All versions of the BAY software prior to 18.0.2 are broken in
regards to the Message-Authenticator. They send a strictly MD5
encoded secret instead of the encoding required by the RFC. This has
been fixed in 18.0.2 and only 18.0.2.
- If you see messages in the radius log like:
+If you see messages in the radius log like:
-Received packet from xxx.xxx.xxx.xxx with invalid Message-Authenticator!
+ Received packet from xxx.xxx.xxx.xxx with invalid Message-Authenticator!
- and you are using a Bay Annex, then you MUST upgrade the software on
+and you are using a Bay Annex, then you MUST upgrade the software on
your Annex. There is NO other solution to the problem.
--- /dev/null
+= Cisco IOS and Radius
+
+## Introduction
+
+Cisco NAS equipment has become quite popular of late, but being Cisco
+equipment running IOS, the configuration can be a bit non-obvious to the
+unfamiliar. This document aims to describe the most common configuration
+options to make your Ciscos interoperate with radius as you would expect a
+well-behaved NAS to do.
+
+## IOS 12.x
+
+For Cisco 12.x (12.0 and 12.1), the following AAA configuration directives
+are suggested:
+
+```
+aaa new-model
+aaa authentication login default group radius local
+aaa authentication login localauth local
+aaa authentication ppp default if-needed group radius local
+aaa authorization exec default group radius local
+aaa authorization network default group radius local
+aaa accounting delay-start
+aaa accounting exec default start-stop group radius
+aaa accounting network default start-stop group radius
+aaa processes 6
+```
+
+this configuration works very well with most radius servers. One of the more
+important configurations is:
+
+```
+aaa accounting delay-start
+```
+
+This directive will delay the sending of the Accounting Start packet until
+after an IP address has been assigned during the PPP negotiation process.
+This will supersede the need to enable the sending of _Alive_ packets as
+described below for IOS versions 11.x
+
+NOTE: The above it will use the radius server to authenticate
+your inbound 'telnet' connections. You will need to create an entry
+in your users file similar to the following to allow access:
+
+```
+!root Cleartext-Password := "somepass" Service-Type = NAS-Prompt-User
+```
+
+This will let a user in for the first level of access to your Cisco. You
+will still need to `enable` ( using the locally configured enable secret )
+to perform any configuration changes or anything requiring a higher level
+of access. The username `!root` was used as an example here, you can make
+this any username you want, of course.
+
+## Unique Acct-Session-Id's
+
+From: http://isp-lists.isp-planet.com/isp-australia/0201/msg05143.html
+
+Just a note to all cisco ISPs out there who want `RFC 2866` compliance need to
+enable the hidden command `radius-server unique-ident <n>`
+
+```
+Minimum IOS: 12.1(4.1)T.
+```
+
+`Acct-Session-Id` should be unique and wrap after every 256 reboots.
+
+You must reboot after entering this command to take effect. If not, you
+will observe after 10 minutes
+of entering this command, the following message.
+
+```
+%RADIUS-3-IDENTFAIL: Save of unique accounting ident aborted.
+```
+
+## IOS 11.x
+
+For Cisco 11.1, you normally use:
+
+```
+aaa new-model
+aaa authentication ppp radppp if-needed radius
+aaa authorization network radius none
+aaa accounting network wait-start radius
+```
+
+to get the Cisco to talk to a radius server.
+
+## With IOS 11.3
+
+```
+aaa accounting update newinfo
+```
+
+If you want the IP address of the user to show up in the radutmp file
+(and thus, the output of `radwho`).
+
+This is because with `IOS 11.3`, the Cisco first sends a `Start` accounting
+packet without the IP address included. By setting `update newinfo` it
+will send an account `Alive` packet which updates the information.
+
+Also you might see a lot of `duplicates` in the logfile. That can be
+fixed by:
+
+```
+aaa accounting network wait radius
+radius-server timeout 3
+```
+
+To disable the Ascend style attributes (which is a VERY good idea!):
+
+```
+radius-server host X.Y.Z.A auth-port 1645 acct-port 1646
+```
+
+To enable the Ascend style attributes (which we do NOT recommend!):
+
+```
+radius-server host X.Y.Z.A auth-port 1645 acct-port 1646 non-standard
+```
+
+To see Cisco-AVPair attributes in the Cisco debugging log:
+
+```
+radius-server vsa accounting
+```
+
+## Cisco 36xx & 26xx, keeping the NAS IP static
+
+The Cisco 36/26 by default selects (it seems at random) any IP address
+assigned to it (serial, ethernet etc.) as it's RADIUS client source
+address, thus the access request may be dropped by the RADIUS server,
+because it can not verify the client. To make the cisco box always use
+one fixed address, add the following to your configuration:
+
+```
+ip radius source-interface Loopback0
+```
+
+and configure the loopback interface on your router as follows:
+
+```
+interface Loopback0
+ip address 192.0.2.250 255.255.255.255
+```
+
+Use a real world IP address and check the Cisco documentation for why
+it is a good idea to have working loopback interface configured on
+your router.
+
+If you don't want to use the loopback interface of course you can set
+the source-interface to any interface on your Cisco box which has an
+IP address.
+
+## Credits
+
+* Original - Alan DeKok <aland@freeradius.org>
+* 12.x Info - Chris Parker <cparker@starnetusa.net> 2000-10-12
+
+## More Information
+
+For more information, the following page on Cisco's web site may help:
+
+http://www.cisco.com/univercd/cc/td/doc/product/access/acs_serv/vapp_dev/vsaig3.htm
+++ /dev/null
-Cisco IOS and Radius
-====================
-
-Introduction
-------------
-
-Cisco NAS equipment has become quite popular of late, but being Cisco
-equipment running IOS, the configuration can be a bit non-obvious to the
-unfamiliar. This document aims to describe the most common configuration
-options to make your Ciscos interoperate with radius as you would expect a
-well-behaved NAS to do.
-
-IOS 12.x
---------
-
-For Cisco 12.x ( 12.0 and 12.1 ), the following AAA configuration directives
-are suggested:
-
-::
-
- aaa new-model
- aaa authentication login default group radius local
- aaa authentication login localauth local
- aaa authentication ppp default if-needed group radius local
- aaa authorization exec default group radius local
- aaa authorization network default group radius local
- aaa accounting delay-start
- aaa accounting exec default start-stop group radius
- aaa accounting network default start-stop group radius
- aaa processes 6
-
-this configuration works very well with most radius servers. One of the more
-important configurations is:
-
-::
-
- aaa accounting delay-start
-
-This directive will delay the sending of the Accounting Start packet until
-after an IP address has been assigned during the PPP negotiation process.
-This will supersede the need to enable the sending of "Alive" packets as
-described below for IOS versions 11.x
-
-*Note* with the above it will use the radius server to authenticate
-your inbound 'telnet' connections. You will need to create an entry
-in your users file similar to the following to allow access:
-
-::
-
- !root Cleartext-Password := "somepass" Service-Type = NAS-Prompt-User
-
-This will let a user in for the first level of access to your Cisco. You
-will still need to 'enable' ( using the locally configured enable secret )
-to perform any configuration changes or anything requiring a higher level
-of access. The username '!root' was used as an example here, you can make
-this any username you want, of course.
-
-Unique Acct-Session-Id's
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-From: http://isp-lists.isp-planet.com/isp-australia/0201/msg05143.html
-
-Just a note to all cisco ISPs out there who want RFC2866 compliance need to
-enable the hidden command ``radius-server unique-ident <n>``
-
-Minimum IOS: 12.1(4.1)T.
-
-Acct-Session-Id should be unique and wrap after every 256 reboots.
-
-You must reboot after entering this command to take effect. If not, you
-will observe after 10 minutes
-of entering this command, the following message.
-
-::
-
- %RADIUS-3-IDENTFAIL: Save of unique accounting ident aborted.
-
-IOS 11.x
---------
-
-For Cisco 11.1, you normally use
-
-::
-
- aaa new-model
- aaa authentication ppp radppp if-needed radius
- aaa authorization network radius none
- aaa accounting network wait-start radius
-
-to get the Cisco to talk to a radius server.
-
-With IOS 11.3
-^^^^^^^^^^^^^
-
-::
-
- aaa accounting update newinfo
-
-If you want the IP address of the user to show up in the radutmp file
-(and thus, the output of "radwho").
-
-This is because with IOS 11.3, the Cisco first sends a "Start" accounting
-packet without the IP address included. By setting "update newinfo" it
-will send an account "Alive" packet which updates the information.
-
-Also you might see a lot of "duplicates" in the logfile. That can be
-fixed by:
-
-::
-
- aaa accounting network wait radius
- radius-server timeout 3
-
-To disable the Ascend style attributes (which is a VERY good idea!):
-
-::
-
- radius-server host X.Y.Z.A auth-port 1645 acct-port 1646
-
-To enable the Ascend style attributes (which we do NOT recommend!):
-
-::
-
- radius-server host X.Y.Z.A auth-port 1645 acct-port 1646 non-standard
-
-To see Cisco-AVPair attributes in the Cisco debugging log:
-
- radius-server vsa accounting
-
-Cisco 36xx & 26xx, keeping the NAS IP static
---------------------------------------------
-
-The Cisco 36/26 by default selects (it seems at random) any IP address
-assigned to it (serial, ethernet etc.) as it's RADIUS client source
-address, thus the access request may be dropped by the RADIUS server,
-because it can not verify the client. To make the cisco box always use
-one fixed address, add the following to your configuration:
-
-::
-
- ip radius source-interface Loopback0
-
-and configure the loopback interface on your router as follows:
-
-::
-
- interface Loopback0
- ip address 192.0.2.250 255.255.255.255
-
-Use a real world IP address and check the Cisco documentation for why
-it is a good idea to have working loopback interface configured on
-your router.
-
-If you don't want to use the loopback interface of course you can set
-the source-interface to any interface on your Cisco box which has an
-IP address.
-
-Credits
--------
-
-Original - Alan DeKok <aland@freeradius.org>
-12.x Info - Chris Parker <cparker@starnetusa.net> 2000-10-12
-
-More Information
-----------------
-For more information, the following page on Cisco's web site may help:
-
-http://www.cisco.com/univercd/cc/td/doc/product/access/acs_serv/vapp_dev/vsaig3.htm
+++ /dev/null
-= Howto
-
-List with some usual howtos for FreeRADIUS.
-
-* link:ascend[ascend]
-* link:bay[bay]
-* link:cisco.rst[cisco.rst]
-* modules
-** link:modules/RADIUS-LDAP-eDirectory[RADIUS-LDAP-eDirectory]
-** link:modules/eap[eap]
-** link:modules/expiration[expiration]
-** link:modules/krb5[krb5]
-** link:modules/ldap_howto.rst[ldap_howto.rst]
-** link:modules/mschap.rst[mschap.rst]
-** link:modules/pam[pam]
-** link:modules/passwd[passwd]
-** link:modules/python[python]
-** link:modules/soh[soh]
-** link:modules/sql[sql]
-** link:modules/sqlcounter[sqlcounter]
-** link:modules/sqlippool[sqlippool]
-* link:performance-testing[performance-testing]
-* link:proxim[proxim]
-* link:supervise-radiusd.rst[supervise-radiusd.rst]
-* link:tuning_guide[tuning_guide]
-
-// Copyright (C) 2019 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
-// Development of this documentation was sponsored by Network RADIUS SAS.
-include::../img/footer.adoc[]
-"Integrating Novell eDirectory with FreeRADIUS"
+= Integrating Novell eDirectory with FreeRADIUS
+
+# Overview
-Overview
You can integrate Novell eDirectoryTM 8.7.1 or later with FreeRADIUS
1.0.2 onwards to allow wireless authentication for eDirectory users.
By integrating eDirectory with FreeRADIUS, you can do the following:
+
* Use universal password for RADIUS authentication.
Universal password provides single login and authentication for
eDirectory users. Therefore, the users need not have a separate
password for RADIUS and eDirectory authentication.
+
* Enforce eDirectory account policies for users.
The existing eDirectory policies on the user accounts can still be
applied even after integrating with RADIUS. Also, you can make use
+++ /dev/null
-
-
- Extensible Authentication Protocol (EAP)
-
-
-INTRODUCTION
-
- Extensible Authentication Protocol(EAP), rfc2284, is a general protocol
- that allows network access points to support multiple authentication
- methods. Each EAP-Type indicates a specific authentication mechanism.
- 802.1x standard authenticates wireless LAN users trying to access
- enterprise networks.
-
- RADIUS attribute used for EAP is EAP-Message, 79(rfc2869). RADIUS
- communicates all EAP messages by embedding them in this attribute.
-
- General Terminology
- Supplicant/EAP Client - is the software on the end-user/client machine
- (machine with the wireless card).
- Authenticator/NAS/Access Point(AP) - A network device providing users
- with a point of entry into the network.
- EAPOL - EAP over LAN as defined in 802.1x standard.
- EAPOW - EAP over Wireless.
-
-
- +----------+ +----------+ +----------+
- | | EAPOL | | RADIUS | |
- | EAP |<------>| Access |<------>| RADIUS |
- | Client | EAPOW | Point | (EAP) | Server |
- | | | | | |
- +----------+ +----------+ +----------+
-
-
- The sequence of events, for EAP-MD5, runs as follows:
- 1. The end-user associates with the Access Point(AP).
- 2. The supplicant specifies AP to use EAP by sending EAP-Start.
- 3. AP requests the supplicant to Identify itself (EAP-Identity).
- 4. Supplicant then sends its Identity (username) to the AP.
- 5. AP forwards this EAP-response AS-IS to the RADIUS server.
- (The supplicant and the RADIUS server mutually authenticate via AP.
- AP just acts as a passthru till authentication is finished.)
- 6. The server sends a challenge to the supplicant.
- 7. The supplicant carries out a hash on the password and sends
- this hashed password to the RADIUS server as its response.
- 8. The RADIUS server performs a hash on the password for that supplicant
- in its user database and compares the two hashed values and
- authenticates the client if the two values match(EAP-Success/EAP-Failure)
- 9. AP now opens a port to accept data from the end-user.
-
- Currently, EAP is widely used in wireless networks than in wired networks.
- In 802.11/wireless based networking, following sequence of events happen in
- addition to the above EAP events.
-
- 10. RADIUS server and the supplicant agree to a specific WEP key.
- 11. The supplicant loads the key ready for logging on.
- 12. The RADIUS server sends the key for this session (Session key) to the AP.
- 13. The AP encrypts its Broadcast key with the Session key
- 14. The AP sends the encypted key to the supplicant
- 15. The supplicant decrypts the Broadcast key with the Session key and
- the session continues using the Broadcast and Session keys until
- the session ends.
-
- References:
- The Implementation of EAP over RADIUS is based on the following RFCs
- rfc2869 -- RADIUS Extensions
- rfc2284 -- PPP Extensible Authentication Protocol (EAP)
- rfc2716 -- PPP EAP TLS Authentication Protocol
-
- Following links help to understand HOW EAP works
- www.ieee802.org/1/mirror/8021/docs2000/ieee_plenary.PDF
-
-
-EAP CODE ORGANIZATION
-
- EAP is implemented as a module in freeradius
- and the code is placed in src/modules/rlm_eap.
- All EAP-Types are organized as subdirectories in rlm_eap/types/.
-
- Each EAP-Type, like types/rlm_eap_md5, contains a chunk of code that
- knows how to deal with a particular kind of authentication mechanism.
-
- To add a new EAP-Type then a new directory should be created as
- rlm_eap/types/rlm_eap_XXXX, where XXXX is EAP-Type name
- ie for EAP-Type like ONE TIME PASSWORD (OTP) it would be rlm_eap_otp
-
- src/modules/rlm_eap -- contains the basic EAP and generalized interfaces
- to all the EAP-Types.
- rlm_eap/types -- contains all the supported EAP-Types
- rlm_eap/types/rlm_eap_md5 -- EAP-MD5 authentication.
- rlm_eap/types/rlm_eap_tls -- EAP-TLS based authentication.
- rlm_eap/types/rlm_eap_ttls -- TTLS based authentication.
- rlm_eap/types/rlm_eap_peap -- Windows PEAP based authentication.
- rlm_eap/types/rlm_eap_leap -- Cisco LEAP authentication.
- rlm_eap/types/rlm_eap_sim -- EAP-SIM (GSM) based authentication
-
-CONFIGURATION
-
- Add the eap configuration stanza to the modules section in radiusd.conf
- to load and control rlm_eap and all the supported EAP-Types:
-
- For example:
- modules {
- ...
- eap {
- default_eap_type = md5
-
- md5 {
- }
- ...
- }
- ...
- }
-
- NOTE: You cannot have empty eap stanza. At least one EAP-Type sub-stanza
- should be defined as above, otherwise the server will not know what type
- of eap authentication mechanism to be used and the server will exit
- with error.
-
- All the various options and their associated default values for each
- EAP-Type are documented in the sample radiusd.conf that is provided
- with the distribution.
-
- Since the EAP requests may not contain a requested EAP type, the
- 'default_eap_type' configuration options is used by the EAP module
- to determine which EAP type to choose for authentication.
-
- NOTE: EAP cannot authorize a user. It can only authenticate.
- Other Freeradius modules authorize the user.
-
-
-EAP SIM server
-
- To configure EAP-SIM authentication, the following attributes must be
- set in the server. This can be done in the users file, but in many cases
- will be taken from a database server, via one of the SQL interface.
-
- If one has SIM cards that one controls (i.e. whose share secret you know),
- one should be able to write a module to generate these attributes
- (the triplets) in the server.
-
- If one has access to the SS7 based settlement network, then a module to
- fetch appropriate triplets could be written. This module would act as
- an authorization only module.
-
- The attributes are:
- EAP-Sim-Rand1 16 bytes
- EAP-Sim-SRES1 4 bytes
- EAP-Sim-KC1 8 bytes
- EAP-Sim-Rand2 16 bytes
- EAP-Sim-SRES2 4 bytes
- EAP-Sim-KC2 8 bytes
- EAP-Sim-Rand3 16 bytes
- EAP-Sim-SRES3 4 bytes
- EAP-Sim-KC3 8 bytes
-
- EAP-SIM will send WEP attributes to the resquestor.
-
-EAP CLIENTS
-
- 1. XSupplicant - freeradius (EAP/TLS) notes may be found at:
-
- http://www.eax.com/802/
- or http://www.missl.cs.umd.edu/wireless/eaptls/
-
- XSupplicant is hosted by:
-
- http://www.open1x.org/
-
- 2. XP - freeradius (EAP/TLS) notes may be found at:
-
- http://www.denobula.com/EAPTLS.pdf
-
-TESTING
-
- You will find several test cases in src/tests/ for the EAP-SIM code.
-
-
-HOW DO I USE IT (FAQ/Examples)
-
- 1. How can I enable EAP-MD5 authentication ?
-
- In radiusd.conf
-
- modules {
- ...
- eap {
- default_eap_type = md5
- md5 {
- }
- ...
- }
- ...
- }
-
- # eap sets the authenticate type as EAP
- recv Access-Request {
- ...
- eap
- }
-
- # eap authentication takes place.
- process Access-Request {
- eap
- }
-
- # If you are proxying EAP-LEAP requests
- # This is required to make LEAP work.
- post-proxy {
- eap
- }
-
- 2. My Userbase is in LDAP and I want to use EAP-MD5 authentication
-
- In radiusd.conf
-
- modules {
- ...
- eap {
- default_eap_type = md5
- md5 {
- }
- ...
- }
- ...
- }
-
- # ldap gets the Configured password.
- # eap sets the authenticate type as EAP
- recv Access-Request {
- ...
- ldap
- eap
- ...
- }
-
- # eap authentication takes place.
- process Access-Request {
- ...
- eap
- ...
- }
-
- 3. How can I Proxy EAP messages, with/without User-Name attribute
- in the Access-Request packets
-
- With User-Name attribute in Access-Request packet,
- EAP-proxying is just same as RADIUS-proxying.
-
- If User-Name attribute is not present in Access-Request packet,
- Freeradius can proxy the request with the following configuration
- in radiusd.conf
-
- # eap module should be configured as the First module in
- # the authorize stanza
-
- recv Access-Request {
- eap
- ... other modules.
- }
-
- With this configuration, eap_authorize creates User-Name attribute
- from EAP-Identity response, if it is not present.
- Once User-Name attribute is created, RADIUS proxying takes care
- of EAP proxying.
-
- 4. How Freeradius can handle EAP-START messages ?
-
- In most of the cases this is handled by the Authenticator.
-
- Only if it is required then, in radiusd.conf
-
- recv Access-Request {
- eap
- ... other modules.
- }
-
- With the above configuration, RADIUS server immediately responds with
- EAP-Identity request.
-
- NOTE: EAP does not check for any Identity or maintains any state in case
- of EAP-START. It blindly responds with EAP-Identity request.
- Proxying is handled only after EAP-Identity response is received.
-
- 5. I want to enable multiple EAP-Types, how can I configure ?
-
- In radiusd.conf
-
- modules {
- ...
- eap {
- default_eap_type = tls
- md5 {
- }
- tls {
- ...
- }
- ...
- }
- ...
- }
-
- The above configuration will let the server load all the EAP-Types,
- but the server can have only one default EAP-Type, as above.
-
- Once EAP-Identity response is received by the server, based on the
- default_eap_type, the server will send a new request (MD5-Challenge
- request incase of md5, TLS-START request incase of tls) to the supplicant.
- If the supplicant is rfc2284 compliant and does not support the
- EAP-Type sent by the server then it sends EAP-Acknowledge with the
- supported EAP-Type. If this EAP-Type is supported by the server then it
- will send the respective EAP-request.
-
- Example: If the supplicant supports only EAP-MD5 but the server
- default_eap_type is configured as EAP-TLS, as above, then the server
- will send TLS-START after EAP-Identity is received. Supplicant will
- respond with EAP-Acknowledge(EAP-MD5). Server now responds with
- MD5-Challenge.
-
-
-INSTALLATION
- EAP, EAP-MD5, and Cisco LEAP do not require any additional packages.
- Freeradius contains all the required packages.
-
- For EAP-TLS, EAP-TTLS, and PEAP, OPENSSL, <http://www.openssl.org/>,
- is required to be installed.
- Any version from 0.9.7, should fairly work with this module.
-
- EAP-SIM should not require any additional packages.
-
-
-IMPLEMENTATION (For Developers)
-
- The rlm_eap module only deals with EAP specific authentication mechanism
- and the generic interface to interact with all the EAP-Types.
-
- Currently, these are the existing interfaces,
- int attach(CONF_SECTION *conf, void **type_arg);
- int initiate(void *type_arg, EAP_HANDLER *handler);
- int authenticate(void *type_arg, EAP_HANDLER *handler);
- int detach(void **type_arg);
-
- attach() and detach() functions allocate and deallocate all the
- required resources.
-
- initiate() function begins the conversation when EAP-Identity response
- is received. Incase of EAP-MD5, initiate() function sends the challenge.
-
- authenticate() function uses specific EAP-Type authentication mechanism
- to authenticate the user. During authentication many EAP-Requests and
- EAP-Responses takes place for each authentication. Hence authenticate()
- function may be called many times. EAP_HANDLER contains the complete
- state information required.
-
-
-HOW EAP WORKS
- as posted to the list, by John Lindsay <jlindsay@internode.com.au>
-
- To make it clear for everyone, the supplicant is the software on the
- client (machine with the wireless card).
-
- The EAP process doesn't start until the client has associated with
- the Access Point using Open authentication. If this process isn't
- crystal clear you need to go away and gain understanding.
-
- Once the association is made the AP blocks all traffic that is not
- 802.1x so although associated the connection only has value for EAP.
- Any EAP traffic is passed to the radius server and any radius traffic
- is passed back to the client.
-
- So, after the client has associated to the Access Point, the
- supplicant starts the process for using EAP over LAN by asking the
- user for their logon and password.
-
- Using 802.1x and EAP the supplicant sends the username and a one-way
- hash of the password to the AP.
-
- The AP encapsulates the request and sends it to the RADIUS server.
-
- The radius server needs a plaintext password so that it can perform
- the same one-way hash to determine that the password is correct. If
- it is, the radius server issues an access challenge which goes back
- via to the AP to the client. (my study guide says client but my
- brain says 'supplicant')
-
- The client sends the EAP response to the challenge via the AP to the
- RADIUS server.
-
- If the response is valid the RADIUS server sends a success message
- and the session WEP key (EAP over wireless) to the client via the
- AP. The same session WEP key is also sent to the AP in the success
- packet.
-
- The client and the AP then begin using session WEP keys. The WEP key
- used for multicasts is then sent from the AP to the client. It is
- encrypted using the session WEP key.
-
-ACKNOWLEDGEMENTS
- Primary author - Raghu <raghud@mail.com>
-
- EAP-SIM - Michael Richardson <mcr@sandelman.ottawa.on.ca>
- The development of the EAP/SIM support was funded by
- Internet Foundation Austria (http://www.nic.at/ipa).
-
-
--- /dev/null
+= Extensible Authentication Protocol (EAP)
+
+## Introduction
+
+Extensible Authentication Protocol(EAP), rfc2284, is a general protocol
+that allows network access points to support multiple authentication
+methods. Each EAP-Type indicates a specific authentication mechanism.
+802.1x standard authenticates wireless LAN users trying to access
+enterprise networks.
+
+RADIUS attribute used for EAP is EAP-Message, 79(rfc2869). RADIUS
+communicates all EAP messages by embedding them in this attribute.
+
+General Terminology
+Supplicant/EAP Client - is the software on the end-user/client machine
+ (machine with the wireless card).
+Authenticator/NAS/Access Point(AP) - A network device providing users
+ with a point of entry into the network.
+EAPOL - EAP over LAN as defined in 802.1x standard.
+EAPOW - EAP over Wireless.
+
+```
+ +----------+ +----------+ +----------+
+ | | EAPOL | | RADIUS | |
+ | EAP |<------>| Access |<------>| RADIUS |
+ | Client | EAPOW | Point | (EAP) | Server |
+ | | | | | |
+ +----------+ +----------+ +----------+
+```
+
+The sequence of events, for EAP-MD5, runs as follows:
+
+1. The end-user associates with the Access Point(AP).
+2. The supplicant specifies AP to use EAP by sending EAP-Start.
+3. AP requests the supplicant to Identify itself (EAP-Identity).
+4. Supplicant then sends its Identity (username) to the AP.
+5. AP forwards this EAP-response AS-IS to the RADIUS server.
+ (The supplicant and the RADIUS server mutually authenticate via AP.
+ AP just acts as a passthru till authentication is finished.)
+6. The server sends a challenge to the supplicant.
+7. The supplicant carries out a hash on the password and sends
+ this hashed password to the RADIUS server as its response.
+8. The RADIUS server performs a hash on the password for that supplicant
+ in its user database and compares the two hashed values and
+ authenticates the client if the two values match(EAP-Success/EAP-Failure)
+9. AP now opens a port to accept data from the end-user.
+
+Currently, EAP is widely used in wireless networks than in wired networks.
+In 802.11/wireless based networking, following sequence of events happen in
+addition to the above EAP events.
+
+10. RADIUS server and the supplicant agree to a specific WEP key.
+11. The supplicant loads the key ready for logging on.
+12. The RADIUS server sends the key for this session (Session key) to the AP.
+13. The AP encrypts its Broadcast key with the Session key
+14. The AP sends the encypted key to the supplicant
+15. The supplicant decrypts the Broadcast key with the Session key and
+ the session continues using the Broadcast and Session keys until
+ the session ends.
+
+References:
+
+The Implementation of EAP over RADIUS is based on the following RFCs
+
+* `rfc2869` -- RADIUS Extensions
+* `rfc2284` -- PPP Extensible Authentication Protocol (EAP)
+* `rfc2716` -- PPP EAP TLS Authentication Protocol
+
+Following links help to understand HOW EAP works
+http://www.ieee802.org/1/mirror/8021/docs2000/ieee_plenary.PDF
+
+## EAP Code Organization
+
+EAP is implemented as a module in freeradius and the code is placed
+in src/modules/rlm_eap.
+All EAP-Types are organized as subdirectories in rlm_eap/types/.
+
+Each EAP-Type, like types/rlm_eap_md5, contains a chunk of code that
+knows how to deal with a particular kind of authentication mechanism.
+
+To add a new EAP-Type then a new directory should be created as
+rlm_eap/types/rlm_eap_XXXX, where XXXX is EAP-Type name
+ie for EAP-Type like ONE TIME PASSWORD (OTP) it would be rlm_eap_otp
+
+Path | Description
+-----------------------------|------------------------------------
+`src/modules/rlm_eap` | Contains the basic EAP and generalized interfaces \
+ to all the EAP-Types.
+`rlm_eap/types` | Contains all the supported EAP-Types
+`rlm_eap/types/rlm_eap_md5` | EAP-MD5 authentication.
+`rlm_eap/types/rlm_eap_tls` | EAP-TLS based authentication.
+`rlm_eap/types/rlm_eap_ttls` | TTLS based authentication.
+`rlm_eap/types/rlm_eap_peap` | Windows PEAP based authentication.
+`rlm_eap/types/rlm_eap_leap` | Cisco LEAP authentication.
+`rlm_eap/types/rlm_eap_sim` | EAP-SIM (GSM) based authentication
+
+## Configuration
+
+Add the eap configuration stanza to the modules section in `radiusd.conf`
+to load and control rlm_eap and all the supported EAP-Types:
+
+ For example:
+
+```unlang
+modules {
+ ...
+ eap {
+ default_eap_type = md5
+
+ md5 {
+ }
+ ...
+ }
+ ...
+}
+```
+
+NOTE: You cannot have empty eap stanza. At least one EAP-Type sub-stanza
+should be defined as above, otherwise the server will not know what type
+of eap authentication mechanism to be used and the server will exit
+with error.
+
+All the various options and their associated default values for each
+`EAP-Type` are documented in the sample radiusd.conf that is provided
+with the distribution.
+
+Since the EAP requests may not contain a requested EAP type, the
+`default_eap_type` configuration options is used by the EAP module
+to determine which EAP type to choose for authentication.
+
+NOTE: EAP cannot authorize a user. It can only authenticate.
+Other Freeradius modules authorize the user.
+
+
+## EAP SIM server
+
+To configure EAP-SIM authentication, the following attributes must be
+set in the server. This can be done in the users file, but in many cases
+will be taken from a database server, via one of the SQL interface.
+
+If one has SIM cards that one controls (i.e. whose share secret you know),
+one should be able to write a module to generate these attributes
+(the triplets) in the server.
+
+If one has access to the SS7 based settlement network, then a module to
+fetch appropriate triplets could be written. This module would act as
+an authorization only module.
+
+The attributes are:
+
+Attribute | Size
+--------------|-----------
+EAP-Sim-Rand1 | 16 bytes
+EAP-Sim-SRES1 | 4 bytes
+EAP-Sim-KC1 | 8 bytes
+EAP-Sim-Rand2 | 16 bytes
+EAP-Sim-SRES2 | 4 bytes
+EAP-Sim-KC2 | 8 bytes
+EAP-Sim-Rand3 | 16 bytes
+EAP-Sim-SRES3 | 4 bytes
+EAP-Sim-KC3 | 8 bytes
+
+NOTE: `EAP-SIM` will send WEP attributes to the resquestor.
+
+## EAP Clients
+
+1. XSupplicant - freeradius (EAP/TLS) notes may be found at:
+
+http://www.eax.com/802/
+or http://www.missl.cs.umd.edu/wireless/eaptls/
+
+XSupplicant is hosted by:
+
+http://www.open1x.org/
+
+2. XP - freeradius (EAP/TLS) notes may be found at:
+
+http://www.denobula.com/EAPTLS.pdf
+
+## Testing
+
+You will find several test cases in src/tests/ for the EAP-SIM code.
+
+## FAQ & Examples
+
+How do i use it?
+
+1. How can I enable EAP-MD5 authentication ?
+
+In radiusd.conf
+
+```
+ modules {
+ ...
+ eap {
+ default_eap_type = md5
+ md5 {
+ }
+ ...
+ }
+ ...
+ }
+
+ # eap sets the authenticate type as EAP
+ recv Access-Request {
+ ...
+ eap
+ }
+
+ # eap authentication takes place.
+ process Access-Request {
+ eap
+ }
+
+ # If you are proxying EAP-LEAP requests
+ # This is required to make LEAP work.
+ post-proxy {
+ eap
+ }
+```
+
+2. My Userbase is in LDAP and I want to use EAP-MD5 authentication
+
+In radiusd.conf
+
+```
+ modules {
+ ...
+ eap {
+ default_eap_type = md5
+ md5 {
+ }
+ ...
+ }
+ ...
+ }
+
+ # ldap gets the Configured password.
+ # eap sets the authenticate type as EAP
+ recv Access-Request {
+ ...
+ ldap
+ eap
+ ...
+ }
+
+ # eap authentication takes place.
+ process Access-Request {
+ ...
+ eap
+ ...
+ }
+```
+
+3. How can I Proxy EAP messages, with/without User-Name attribute
+in the `Access-Request` packets
+
+With `User-Name` attribute in `Access-Request` packet,
+`EAP-proxying` is just same as RADIUS-proxying.
+
+If `User-Name` attribute is not present in `Access-Request` packet,
+Freeradius can proxy the request with the following configuration
+in radiusd.conf
+
+```
+ # eap module should be configured as the First module in
+ # the authorize stanza
+
+ recv Access-Request {
+ eap
+ ... other modules.
+ }
+```
+
+With this configuration, eap_authorize creates `User-Name` attribute
+from `EAP-Identity` response, if it is not present.
+Once `User-Name` attribute is created, RADIUS proxying takes care
+of EAP proxying.
+
+4. How Freeradius can handle `EAP-START` messages ?
+
+In most of the cases this is handled by the Authenticator.
+
+Only if it is required then, in radiusd.conf
+
+```
+recv Access-Request {
+ eap
+ ... other modules.
+}
+```
+
+With the above configuration, RADIUS server immediately responds with
+EAP-Identity request.
+
+NOTE: EAP does not check for any Identity or maintains any state in case
+of EAP-START. It blindly responds with EAP-Identity request.
+Proxying is handled only after EAP-Identity response is received.
+
+5. I want to enable multiple EAP-Types, how can I configure ?
+
+In radiusd.conf
+
+```
+modules {
+ ...
+ eap {
+ default_eap_type = tls
+ md5 {
+ }
+ tls {
+ ...
+ }
+ ...
+ }
+ ...
+}
+```
+
+The above configuration will let the server load all the EAP-Types,
+but the server can have only one default EAP-Type, as above.
+
+Once EAP-Identity response is received by the server, based on the
+default_eap_type, the server will send a new request (MD5-Challenge
+request incase of md5, TLS-START request incase of tls) to the supplicant.
+If the supplicant is rfc2284 compliant and does not support the
+EAP-Type sent by the server then it sends EAP-Acknowledge with the
+supported EAP-Type. If this EAP-Type is supported by the server then it
+will send the respective EAP-request.
+
+Example: If the supplicant supports only EAP-MD5 but the server
+default_eap_type is configured as EAP-TLS, as above, then the server
+will send TLS-START after EAP-Identity is received. Supplicant will
+respond with EAP-Acknowledge(EAP-MD5). Server now responds with
+MD5-Challenge.
+
+## Installation
+
+EAP, EAP-MD5, and Cisco LEAP do not require any additional packages.
+Freeradius contains all the required packages.
+
+For EAP-TLS, EAP-TTLS, and PEAP, OPENSSL, <http://www.openssl.org/>,
+is required to be installed.
+Any version from 0.9.7, should fairly work with this module.
+
+EAP-SIM should not require any additional packages.
+
+## Implementation (For Developers)
+
+The rlm_eap module only deals with EAP specific authentication mechanism
+and the generic interface to interact with all the EAP-Types.
+
+Currently, these are the existing interfaces,
+
+```
+int attach(CONF_SECTION *conf, void **type_arg);
+int initiate(void *type_arg, EAP_HANDLER *handler);
+int authenticate(void *type_arg, EAP_HANDLER *handler);
+int detach(void **type_arg);
+```
+
+`attach()` and `detach()` functions allocate and deallocate all the
+required resources.
+
+`initiate()` function begins the conversation when EAP-Identity response
+is received. Incase of EAP-MD5, `initiate()` function sends the challenge.
+
+`authenticate()` function uses specific EAP-Type authentication mechanism
+to authenticate the user. During authentication many EAP-Requests and
+EAP-Responses takes place for each authentication. Hence authenticate()
+function may be called many times. EAP_HANDLER contains the complete
+state information required.
+
+## How EAP works
+
+as posted to the list, by John Lindsay <jlindsay@internode.com.au>
+
+To make it clear for everyone, the supplicant is the software on the
+client (machine with the wireless card).
+
+The EAP process doesn't start until the client has associated with
+the Access Point using Open authentication. If this process isn't
+crystal clear you need to go away and gain understanding.
+
+Once the association is made the AP blocks all traffic that is not
+802.1x so although associated the connection only has value for EAP.
+Any EAP traffic is passed to the radius server and any radius traffic
+is passed back to the client.
+
+So, after the client has associated to the Access Point, the
+supplicant starts the process for using EAP over LAN by asking the
+user for their logon and password.
+
+Using 802.1x and EAP the supplicant sends the username and a one-way
+hash of the password to the AP.
+
+The AP encapsulates the request and sends it to the RADIUS server.
+
+The radius server needs a plaintext password so that it can perform
+the same one-way hash to determine that the password is correct. If
+it is, the radius server issues an access challenge which goes back
+via to the AP to the client. (my study guide says client but my
+brain says 'supplicant')
+
+The client sends the EAP response to the challenge via the AP to the
+RADIUS server.
+
+If the response is valid the RADIUS server sends a success message
+and the session WEP key (EAP over wireless) to the client via the
+AP. The same session WEP key is also sent to the AP in the success
+packet.
+
+The client and the AP then begin using session WEP keys. The WEP key
+used for multicasts is then sent from the AP to the client. It is
+encrypted using the session WEP key.
+
+## ACKNOWLEDGEMENTS
+
+* Primary author - Raghu <raghud@mail.com>
+* EAP-SIM - Michael Richardson <mcr@sandelman.ottawa.on.ca>
+* The development of the EAP/SIM support was funded by
+ Internet Foundation Austria (http://www.nic.at/ipa).
+= Expiration
+
Module to expire user accounts.
This module can be used to expire user accounts. Expired users receive
on the Expiration attribute which should be present in the check item
list for the user we wish to perform expiration checks.
-
+## Topics
Expiration attribute format:
The nas will receive a Session-Timeout attribute calculated to kick
the user off when the Expiration time occurs.
-
-
Example entry (users files):
+```
user1 Expiration := "23 Sep 2004"
+``
-
- PAM Support for FreeRadius
-
+PAM Support for FreeRadius
+==========================
0. INTRODUCTION
- SQL Module
+SQL Module
+==========
0. Introduction
-Welcome to the SQL Based IP Pool module.
+SQL Based IP Pool module.
+=========================
-**********************************************************************
+# Description
As of September 2006 this module is still under some development and
currently is only tested by the developers on PostgreSQL (Version 8.1)
Use it at your own risk!
have to do extra work which is not for SQL newbies.
Having said that it works great for us in production and should (with
some work) function correctly with other SQL server types.
-**********************************************************************
-
To use the sqlipool module you simply need to have an IP-Pool Attribute
(Keep in mind that its a **CHECK** item, not reply) in the required
We are currently using the variable definitions of the xlat module, so
before editing the sqlippool.conf file, please go and read the
-variables.rst in the doc/configuration directory. It will help you alot!..
+variables.md in the doc/configuration directory. It will help you alot!..
As you may noticed, there is a pool-key variable in the config file which
allows you to select which attribute is unique according to your NAS setup.
+++ /dev/null
-
-Radius Test Procedures
-
-0. INTRODUCTION
-
-This document describes how to test your radius server authentication
-using random usernames and passwords with the 'radclient' program.
-
-1. WHY TEST
-
-Many people want to see the difference in efficiency behind the various
-authentication methods, compilation methods, etc of their radius server.
-Before now, this was difficult to do efficiently across a large number
-of users. However, with this document, you'll be able to test your
-radius server and determine the best options to use for your system.
-
-2. GETTING STARTED
-
-First thing we have to do is generate a large number of users. You'll
-want to do this even if you have a large passwd file you want to use
-from your system, because the create user script sets up other files
-you need for testing. So head to the scripts/ directory, and do this:
-
-Make a tmp dir
-# mkdir tmp
-# cp create-users.pl tmp
-# cd tmp
-
-Run the script to create 10,000 (or however many you want) random users
-and passwords
-# ./create-users.pl 10000
-
-Output from the script will include several files:
- passwd : A standard passwd file you can append to /etc/passwd
- shadow : A standard shadow file you can append to /etc/shadow
-passwd.nocrypt : A file with *unencrypted* users & passes in form "user:pass"
- radius.test : File you'll use as input for radclient
- radius.users : A standard radius 'users' file
-
-So, equipped with lots of users and passwords, there's several methods of
-authentication you can test:
-
- o System users (Auth-Type:=System)
- o Local users (Auth-Type:=Local)
- o Cached system (passwd) users
- o Others
-
-NOTE: Before moving on, you will probably want to add '/dev/null' to
-/etc/shells *temporarily* so that default system authentication will
-work. REMEMBER TO TAKE IT OUT!
-
-3. TEST PROCEDURES
-
- A. System (/etc/passwd) users testing
-
- 1. Append the 'passwd' file from create-users.pl onto your
- system passwd file:
-
- # cat ./passwd >> /etc/passwd
-
- 2. If you have shadow, append the shadow file onto /etc/shadow
-
- # cat ./shadow >> /etc/shadow
-
- 3. Make sure you have a DEFAULT user similar to the following
- in your radius 'users' file:
-
- DEFAULT Auth-Type:=System
- Reply-Message = "Success!"
-
- 4. Start radiusd
-
- # /usr/local/sbin/radiusd
-
- 5. Run radclient with 'radius.test' as the input file.
-
- NOTE: First you need to setup a secret for your local
- machine in the 'clients' file and use that secret below
-
- # time /usr/local/bin/radclient -q -s -f radius.test \
- <yourhostname> auth <secret>
-
- NOTE: The above is to be put all on one line.
-
- NOTE: Some systems do not have the 'time' command,
- so you may need to break out the stopwatch instead :)
-
- Take note of the output of radclient. If there were lots of
- failures, something is wrong. All authentications should
- succeed.
-
- 6. Take note of the output from the above 'time' command.
- The output format should be something similar to the
- following (on linux, this for example only!):
-
- 1.72user 0.53system 5:11.34elapsed 0%CPU
- (0avgtext+0avgdata 0maxresident)k 0inputs+0outputs
- (340major+29minor)pagefaults 0swaps
-
- This means it took 5:11 (311 seconds) to authenticate
- 10,000 users. Simple division tells us this is:
-
- 10,000 auths / 311 seconds = 32.1543 auths/second
-
- B. Local users testing
-
- 1. Copy the 'radius.users' file from the script over your 'users'
- file. Make sure you do NOT have a DEFAULT entry or you will
- invalidate this test.
-
- 2. Restart radiusd (kill and restart)
-
- 3. Run radclient (See A-5 above for NOTES on this):
-
- # time /usr/local/bin/radclient -q -s -f radius.test \
- <yourhostname> auth <secret>
-
- 4. Take note of the output from the above 'time' command, and
- divide the number of auths (10,000 in this case) with the
- number of seconds it took to complete. See A6 above for
- more info.
-
- C. Cached system users
-
- 1. Set 'cache=yes' in your radiusd.conf file
-
- 2. Restart radiusd (ie, kill it and restart, not just a HUP)
-
- 3. Perform the same steps outlined above for testing System users (A)
-
- D. Other methods
-
- There is no reason why you can't use some of this to test modules
- for PAM, SQL, LDAP, etc, but that will require a little extra
- work on your end (ie, getting the users/passes you generated into
- the corresponding database). However, by now you should have a
- good idea of how to test once you do that.
-
- Also, play around with compile options like --with-thread,
- --with-thread-pool, etc. Run radiusd with '-s' so it runs
- one process only, etc etc. Play around with it.
-
-4. CAVEATS
-
-The above test procedures make no allowances for users that login with
-incorrect usernames or passwords. If you want a true test of performance,
-you should add in lots of bad usernames and passwords to the radius.test
-file and then re-run 'radclient' with that file as input.
-
-Additionally, these tests make no reference to how the pre-authenticate,
-post-authenticate, and accounting methods you choose could affect server
-performance. For example, checking for simultaneous use after authenti-
-cating the user is obviously going to slow down authenticate performance.
-
-The numbers you get from this test are raw authentications/second in a
-perfect environment. Do not expect this kind of result in the real world.
-However, having tested in this manner, you will have a good idea of which
-authentication methods and compilation options give you the best base to
-start from, which is key to an efficient server.
-
-5. RESULTS
-
-I'd really rather not post results because they will vary tremendously
-with other system-specific configuration. This is exactly the reason
-you should run tests of this nature, to find what's best for *your*
-system. Good luck!
-
-
--- /dev/null
+= RADIUS Test Procedures
+
+## Introduction
+
+This document describes how to test your radius server authentication
+using random usernames and passwords with the 'radclient' program.
+
+## Why test?
+
+Many people want to see the difference in efficiency behind the various
+authentication methods, compilation methods, etc of their radius server.
+Before now, this was difficult to do efficiently across a large number
+of users. However, with this document, you'll be able to test your
+radius server and determine the best options to use for your system.
+
+## Getting started
+
+First thing we have to do is generate a large number of users. You'll
+want to do this even if you have a large passwd file you want to use
+from your system, because the create user script sets up other files
+you need for testing. So head to the scripts/ directory, and do this:
+
+Make a tmp dir
+
+```
+# mkdir tmp
+# cp create-users.pl tmp
+# cd tmp
+```
+
+Run the script to create 10,000 (or however many you want) random users
+and passwords
+
+```
+# ./create-users.pl 10000
+
+Output from the script will include several files:
+ passwd : A standard passwd file you can append to /etc/passwd
+ shadow : A standard shadow file you can append to /etc/shadow
+passwd.nocrypt : A file with *unencrypted* users & passes in form "user:pass"
+ radius.test : File you'll use as input for radclient
+ radius.users : A standard radius 'users' file
+
+So, equipped with lots of users and passwords, there's several methods of
+authentication you can test:
+
+ o System users (Auth-Type:=System)
+ o Local users (Auth-Type:=Local)
+ o Cached system (passwd) users
+ o Others
+```
+
+NOTE: Before moving on, you will probably want to add `/dev/null` to
+/etc/shells *temporarily* so that default system authentication will
+work. REMEMBER TO TAKE IT OUT!
+
+## Test procedures
+
+### System (/etc/passwd) users testing
+
+1. Append the `passwd` file from `create-users.pl` onto your system passwd file:
+```
+# cat ./passwd >> /etc/passwd
+```
+2. If you have shadow, append the shadow file onto /etc/shadow
+```
+# cat ./shadow >> /etc/shadow
+```
+3. Make sure you have a DEFAULT user similar to the following in your radius 'users' file:
+```
+DEFAULT Auth-Type:=System
+ Reply-Message = "Success!"
+```
+4. Start radiusd
+```
+ # /usr/local/sbin/radiusd
+```
+5. Run radclient with `radius.test` as the input file.
+
+NOTE: First you need to setup a secret for your local
+machine in the `clients` file and use that secret below
+```
+# time /usr/local/bin/radclient -q -s -f radius.test <yourhostname> auth <secret>
+```
+NOTE: The above is to be put all on one line.
+
+NOTE: Some systems do not have the `time` command,
+so you may need to break out the stopwatch instead :)
+
+Take note of the output of `radclient`. If there were lots of
+failures, something is wrong. All authentications should
+succeed.
+
+6. Take note of the output from the above 'time' command.
+The output format should be something similar to the
+following (on linux, this for example only!):
+
+```
+1.72user 0.53system 5:11.34elapsed 0%CPU
+(0avgtext+0avgdata 0maxresident)k 0inputs+0outputs
+(340major+29minor)pagefaults 0swaps
+```
+
+_This means it took 5:11 (311 seconds) to authenticate
+10,000 users. Simple division tells us this is:_
+
+ 10,000 auths / 311 seconds = 32.1543 auths/second
+
+### Local users testing
+
+1. Copy the 'radius.users' file from the script over your 'users'
+ file. Make sure you do NOT have a DEFAULT entry or you will
+ invalidate this test.
+2. Restart radiusd (kill and restart)
+3. Run radclient (See A-5 above for NOTES on this):
+```
+# time /usr/local/bin/radclient -q -s -f radius.test <yourhostname> auth <secret>
+```
+4. Take note of the output from the above 'time' command, and
+ divide the number of auths (10,000 in this case) with the
+ number of seconds it took to complete. See A6 above for
+ more info.
+
+### Cached system users
+
+1. Set `cache=yes` in your radiusd.conf file
+2. Restart radiusd (ie, kill it and restart, not just a HUP)
+3. Perform the same steps outlined above for testing System users (A)
+
+### Other methods
+
+There is no reason why you can't use some of this to test modules
+for PAM, SQL, LDAP, etc, but that will require a little extra
+work on your end (ie, getting the users/passes you generated into
+the corresponding database). However, by now you should have a
+good idea of how to test once you do that.
+
+Also, play around with compile options like `--with-thread`,
+`--with-thread-pool`, etc. Run radiusd with `-s` so it runs
+one process only, etc etc. Play around with it.
+
+## Caveats
+
+The above test procedures make no allowances for users that login with
+incorrect usernames or passwords. If you want a true test of performance,
+you should add in lots of bad usernames and passwords to the radius.test
+file and then re-run `radclient` with that file as input.
+
+Additionally, these tests make no reference to how the pre-authenticate,
+post-authenticate, and accounting methods you choose could affect server
+performance. For example, checking for simultaneous use after authenti-
+cating the user is obviously going to slow down authenticate performance.
+
+The numbers you get from this test are raw authentications/second in a
+perfect environment. Do not expect this kind of result in the real world.
+However, having tested in this manner, you will have a good idea of which
+authentication methods and compilation options give you the best base to
+start from, which is key to an efficient server.
+
+## Results
+
+I'd really rather not post results because they will vary tremendously
+with other system-specific configuration. This is exactly the reason
+you should run tests of this nature, to find what's best for *your*
+system. Good luck!
-Proxim
-^^^^^^
+= Proxim
+
+## Description
Proxim AP-2000 NASes up to and including firmware version 2.4.5 ignore
the Session-Timeout attribute, despite the fact that Proxim's firmware
release notes specifically state that it is supported. On top of
this, firmware version 2.4.5 (the latest as of this writing) has a bug
in which the reauthentication interval on the AP cannot be set to any
-value less than 2 hours. As such, fine-grained control of client
-session times is not currently possible with this NAS. Note that this
-NAS is OEMed to several vendors, including Avaya, and may be listed
-under different names with different vendors.
+value less than 2 hours.
+
+As such, fine-grained control of client session times is not currently
+possible with this NAS. Note that this NAS is OEMed to several vendors,
+including Avaya, and may be listed under different names with different
+vendors.
+= Supervising the Radiusd Daemon
-Supervising the Radiusd Daemon
-==============================
-
-Introduction
-------------
+## Introduction
We all hope that our radius daemons won't die in the middle of the
nite stranding customer and beeping beepers. But, alas, it's going to
This text describes how to setup both the free radius daemon so that
it is automatically restarted if the process quits unexpectedly. To
-do this, we'll use either Dan Bernstein's 'daemontools' package or the
-inittab file. Note: The radwatch script that used to be part of this
-distribution, is depreciated and SHOULD NOT BE USED.
+do this, we'll use either Dan Bernstein's `daemontools` package or the
+inittab file.
+
+NOTE: The radwatch script that used to be part of this
+distribution, is depreciated and *SHOULD NOT BE USED*.
-Setting Up Daemontools
-----------------------
+## Setting Up Daemontools
First, download (and install) daemontools from:
daemontools. I usually create a dir '/var/svc' to hold all my
daemontool supervised services. i.e.::
- $ mkdir /var/svc
- $ mkdir /var/svc/radiusd
-
+```
+$ mkdir /var/svc
+$ mkdir /var/svc/radiusd
+```
Now we just need a short shell script called 'run' in our new service
directory that will start our daemon. The following should get you
-started::
+started:
- #!/bin/sh
- # Save as /var/svc/radiusd/run
- exec /usr/local/sbin/radiusd -s -f
+```
+#!/bin/sh
+# Save as /var/svc/radiusd/run
+exec /usr/local/sbin/radiusd -s -f
+```
Of course you'll want to make that 'run' file executable::
- $ chmod +x /var/svc/radiusd/run
+`$ chmod +x /var/svc/radiusd/run`
-Note, you *MUST* use the '-f' option when supervising. That option
+NOTE: you *MUST* use the '-f' option when supervising. That option
tells radiusd not to detach from the tty when starting. If you don't
use that option, the daemontools will always think that radiusd has
just died and will (try to) restart it. Not good.
Now the only left to do is to start the 'supervise' command that came
with daemontools. Do that like so::
- $ supervise /var/svc/radiusd
+`$ supervise /var/svc/radiusd`
-Maintenance With Daemontools
-----------------------------
+## Maintenance With Daemontools
Any maintenance you need to do with almost certainly be done with the
'svc' program in the deamontools package. i.e.::
- Shutdown radiusd:
- $ svc -d /var/svc/radiusd
+Shutdown radiusd: `$ svc -d /var/svc/radiusd`
- Start it back up:
- $ svc -u /var/svc/radiusd
+Start it back up: `$ svc -u /var/svc/radiusd`
- Send HUP to radiusd:
- $ svc -h /var/svc/radiusd
+Send HUP to radiusd: `$ svc -h /var/svc/radiusd`
- Shutdown and stop supervising radiusd:
- $ svc -dx /var/svc/radiusd
+Shutdown and stop supervising radiusd: `$ svc -dx /var/svc/radiusd`
-Supervising With Inittab
-------------------------
+## Supervising With Inittab
This is really pretty easy, but it is system dependent. I strongly
suggest you read the man pages for your 'init' before playing with
Add this line (or something similar to it) to your inittab::
- fr:23:respawn:/usr/local/sbin/radiusd -f -s &> /dev/null
+`fr:23:respawn:/usr/local/sbin/radiusd -f -s &> /dev/null`
Now all that's left is to have the system reread the inittab. Usually
that's done with one of the following::
- $ telinit Q
+`$ telinit Q`
-or::
+or
- $ init q
+`$ init q`
Now you should see a 'radiusd' process when you issue a 'ps'. If you
don't, try to run the radiusd command you put in inittab manually. If
properly. If it doesn't work, that means your radius start command is
bad and you need to fix it.
-Acknowledgements
-----------------
+## Acknowledgements
Document author : Jeff Carneal
daemontools auther : Dan Bernstein
Further daemontool notes (below): Antonio Dias
Radwatch note : Andrey Melnikov
-Further Daemontools notes
-=========================
+## Further Daemontools notes
Here are some notes by Antonia Dias sent to the free radius mailing
list. Some of you may find this useful after reading the above and the
docs for daemontools.
-Daemontools Instructions
-------------------------
+## Daemontools Instructions
I am running radiusd under supervise from daemontools without
problems. The only thing I am missing right now is an option to force
multilog (also included in daemontools package). Here is the procedure
I've been following (for Cistron RADIUS)::
- $ groupadd log
- $ useradd -g log log
- $ mkdir /etc/radiusd
- $ mkdir /etc/radiusd/log
- $ mkdir /etc/radiusd/log/main
- $ chmod +t+s /etc/radiusd /etc/radiusd/log
- $ chown log.log /etc/radiusd/log/main
+```
+$ groupadd log
+$ useradd -g log log
+$ mkdir /etc/radiusd
+$ mkdir /etc/radiusd/log
+$ mkdir /etc/radiusd/log/main
+$ chmod +t+s /etc/radiusd /etc/radiusd/log
+$ chown log.log /etc/radiusd/log/main
+```
Here are the contents of run files from '/etc/radiusd' and '/etc/radiusd/log'::
- $ cd /etc/radiusd
- $ cat run
- #!/bin/sh
- exec 2>&1
- exec /usr/sbin/radiusd -fyzx
- $ cd /etc/radiusd/log
- $ cat run
- #!/bin/sh
- exec setuidgid log multilog t ./main
+```
+$ cd /etc/radiusd
+$ cat run
+#!/bin/sh
+exec 2>&1
+exec /usr/sbin/radiusd -fyzx
+$ cd /etc/radiusd/log
+$ cat run
+#!/bin/sh
+exec setuidgid log multilog t ./main
+```
- To make service wake-up do::
+To make service wake-up do::
- $ ln -sf /etc/radiusd /service
+```
+$ ln -sf /etc/radiusd /service
+```
- Hang-up (to reload config) it using::
+Hang-up (to reload config) it using::
- $ svc -h /service/radiusd
+```
+$ svc -h /service/radiusd
+```
Disable (down) it using::
- $ svc -d /service/radiusd
+```
+$ svc -d /service/radiusd
+```
Reenable (up) it using::
- $ svc -u /service/radiusd
+```
+$ svc -u /service/radiusd
+```
------------- MAIN SERVER -------------
-o If you have a large user base and/or many authentication requests try
+= Tunning Guide
+
+## Main Server
+
+* If you have a large user base and/or many authentication requests try
using a scalable authentication mechanism like ldap or sql.
-o Enable noatime on all the freeradius log files or better yet on the
+
+* Enable noatime on all the freeradius log files or better yet on the
freeradius log directory.
-o Always use the latest cvs version. It will probably contain a few
+
+* Always use the latest cvs version. It will probably contain a few
fixes and enhancements.
-o Always try to use the least modules possible. In particular if you
+
+* Always try to use the least modules possible. In particular if you
can avoid it do not use the detail and radwtmp (files) modules.
They will slow down your accounting.
-o Use the users file to only set default profiles. Do not place any
+
+* Use the users file to only set default profiles. Do not place any
users there. Keep it as small as possible. Always set default
attributes in the users file and don't fill the user entries in
ldap/sql with default values. In general the ldap/sql user profiles
should contain user attributes only in special user cases.
-o Tune thread pool parameters to match your size requirements.
- Set max_requests_per_server to zero to avoid server thread restarts.
-o Enlarge the timeout (10 secs) and retries (5-7) in the access servers
+
+* Tune thread pool parameters to match your size requirements.
+ Set `max_requests_per_server` to zero to avoid server thread restarts.
+
+* Enlarge the timeout (10 secs) and retries (5-7) in the access servers
for accounting. That way you won't lose any accounting information.
-o Use well tuned Fast Ethernet connections to minimize latency.
-o freeradius is multi threaded and i/o bound. That means you should use
+
+* Use well tuned Fast Ethernet connections to minimize latency.
+
+* freeradius is multi threaded and i/o bound. That means you should use
the latest OS kernels/patches for improved multi processor and
network performance.
------------- LDAP MODULE -------------
-o Try to maximize caching in the ldap server. In particular *always*
+## LDAP Module
+
+* Try to maximize caching in the ldap server. In particular *always*
enable indexing of the uid attribute (equality index) and the
cn attribute (equality index - the cn attribute is used to search
for groups). Make the ldap server entry/directory cache memory sizes
as large as possible. In general try allocating as much memory as you
can afford to your ldap server.
-o Put default profiles in ldap. User entries should only contain
+
+* Put default profiles in ldap. User entries should only contain
non standard values in order to remain small and maximize the gains
of caching the user default/regular profiles.
-o Enable group caching in groups.
------------- SQL MODULE --------------
-o Use the sql module in the session section instead of the radutmp module.
+* Enable group caching in groups.
+
+## SQL Module
+
+* Use the sql module in the session section instead of the radutmp module.
It works *much* quicker.
-o Create a multi column index for the (UserName,AcctStopTime) attributes especially
+
+* Create a multi column index for the (`UserName`, `AcctStopTime`) attributes especially
if you are using sql for double login detection.
-o If you are using mysql and you do a lot of accounting try using InnoDB for the radacct
+
+* If you are using mysql and you do a lot of accounting try using InnoDB for the radacct
table instead of MyISAM (this should be the default in all schemas)
-o Add AcctUniqueId in the accounting_stop query. Especially if you have a lot of access
+
+* Add `AcctUniqueId` in the `Acct-Status-Type = Stop` query. Especially if you have a lot of access
servers or your NAS does not send very random Session-Ids. That way you will always have
- one candidate row to search for, instead of all the rows that have the same AcctSessionId
+ one candidate row to search for, instead of all the rows that have the same `AcctSessionId`.
+
+## RADUTMP Module
+
+* Enable noatime on the radutmp file
------------- RADUTMP MODULE ----------
-o Enable noatime on the radutmp file
-o Don't use it
+* Don't use it
projects / thirdparty / freeradius-server.git / commitdiff
