*** xref:modules/chap/index.adoc[CHAP]
*** xref:modules/eap/index.adoc[EAP]
*** xref:modules/expiration/index.adoc[Expiration]
-*** xref:modules/krb5/index.adoc[Krb5]
+*** xref:modules/krb5/index.adoc[KRB5]
*** xref:modules/ldap/index.adoc[LDAP]
-**** xref:modules/ldap/bootstrap_openldap/index.adoc[Installing and Configuring OpenLDAP]
+**** xref:modules/ldap/bootstrap_openldap/index.adoc[Install and Configure OpenLDAP]
***** xref:modules/ldap/bootstrap_openldap/docker.adoc[Docker]
***** xref:modules/ldap/bootstrap_openldap/packages.adoc[Packages]
-**** xref:modules/ldap/ldapsearch/index.adoc[Mapping and testing with ldapsearch]
-***** xref:modules/ldap/ldapsearch/before_starting.adoc[Before starting]
-***** xref:modules/ldap/ldapsearch/connection_parameters.adoc[Determining connection parameters]
-***** xref:modules/ldap/ldapsearch/locating_objects.adoc[Locating objects]
-***** xref:modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc[Translating ldapsearch arguments to LDAP configuration items]
+**** xref:modules/ldap/ldapsearch/index.adoc[Test with Ldapsearch]
+***** xref:modules/ldap/ldapsearch/before_starting.adoc[Prerequisites]
+***** xref:modules/ldap/ldapsearch/connection_parameters.adoc[Determine Connection Parameters]
+***** xref:modules/ldap/ldapsearch/locating_objects.adoc[Locate objects]
+***** xref:modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc[Generate LDAP Configuration Items]
-**** xref:modules/ldap/base_configuration/index.adoc[Base configuration]
+**** xref:modules/ldap/base_configuration/index.adoc[Base Configuration]
-**** xref:modules/ldap/authorization/index.adoc[Configuring authorization]
-***** xref:modules/ldap/authorization/locating_the_user.adoc[Locating the user]
-***** xref:modules/ldap/authorization/user_disambiguation.adoc[Disambiguating user objects]
-***** xref:modules/ldap/authorization/user_account_controls.adoc[Controlling user accounts]
+**** xref:modules/ldap/authorization/index.adoc[Configure Authorization]
+***** xref:modules/ldap/authorization/locating_the_user.adoc[Locate a User]
+***** xref:modules/ldap/authorization/user_disambiguation.adoc[Disambiguate User Objects]
+***** xref:modules/ldap/authorization/user_account_controls.adoc[Control User Accounts]
***** xref:modules/ldap/authorization/groups.adoc[Group Membership]
-**** xref:modules/ldap/authentication.adoc[Configuring authentication]
-**** xref:modules/ldap/accounting.adoc[Configuring accounting]
+**** xref:modules/ldap/authentication.adoc[Configure Authentication]
+**** xref:modules/ldap/accounting.adoc[Configure Accounting]
*** xref:modules/mschap/index.adoc[MS-CHAP]
*** xref:modules/pam/index.adoc[PAM]
*** xref:modules/python/index.adoc[Python]
*** xref:modules/rest/index.adoc[REST]
-**** xref:modules/rest/bootstrap_nginx.adoc[Installing and Configuring NGINX]
+**** xref:modules/rest/bootstrap_nginx.adoc[Install and Configure NGINX]
**** xref:modules/rest/configuration.adoc[Base configuration]
*** xref:modules/sql/index.adoc[SQL]
*** xref:modules/sqlcounter/index.adoc[SQL-Counter]
*** xref:modules/sqlippool/index.adoc[SQL-IP-Pool]
**** xref:modules/sqlippool/configure.adoc[Configuration]
-***** xref:modules/sqlippool/testing.adoc[Test Basic Setup]
+***** xref:modules/sqlippool/testing.adoc[Basic Setup Tests]
***** xref:modules/sqlippool/populating.adoc[Generate IPs for the Pools]
***** xref:modules/sqlippool/insert.adoc[Insert IPs into SQL]
**** xref:modules/sqlippool/recommendations.adoc[Recommendations]
-
-** xref:datastores/index.adoc[Setting up Datastores]
+** xref:datastores/index.adoc[Set up Datastores]
*** xref:datastores/ad/index.adoc[Active Directory]
**** xref:datastores/ad/samba.adoc[Using Samba]
-**** xref:datastores/ad/ntlm_mschap.adoc[Configuring ntlm]
-**** xref:datastores/ad/winbind.adoc[Installing Winbind]
+**** xref:datastores/ad/ntlm_mschap.adoc[Configure NTLM]
+**** xref:datastores/ad/winbind.adoc[Install Winbind]
*** xref:datastores/ldap.adoc[LDAP]
*** xref:datastores/redis.adoc[Redis]
*** xref:datastores/sql.adoc[SQL]
*** xref:protocols/radius/index.adoc[RADIUS]
**** xref:protocols/radius/using_coa.adoc[Using CoA]
***** xref:protocols/radius/coa_examples.adoc[CoA Examples]
-**** xref:protocols/radius/proxy_config.adoc[Proxy configuration]
+**** xref:protocols/radius/proxy_config.adoc[Proxy Configuration]
***** xref:protocols/radius/proxy_extensions.adoc[Proxy Extensions]
** xref:os/index.adoc[Security Certificates]
*** xref:vendors/cisco.adoc[Cisco]
*** xref:vendors/proxim.adoc[ProxIM]
-** xref:optimization/index.adoc[Optimization]
+** xref:optimization/index.adoc[Optimisation]
*** xref:optimization/auditing.adoc[Auditing]
*** xref:optimization/monitoring/index.adoc[Monitoring]
**** xref:optimization/monitoring/logging_examples.adoc[Log Examples]
The services manage network activities by:
-* authenticating users by verifying their identity and credentials, and
-* authorizating resource use by applying policies to restrict access to data.
+* Authenticates users by verifying their identity and credentials.
+* Authorizes resource use by applying policies to restrict access to data.
== What is it?
For MS-CHAP based authentications, FreeRADIUS uses tools such as Samba, including winbind and the `ntlm_auth` helper program to communicate with the AD server.Â
-=== FreeRADIUS Active Directory Authentication Process
+=== FreeRADIUS AD authentication process
The authentication process flow of steps to authenticate a user is as follows:
```
-This configuration requires Freeradius to be built with winbind auth. For example, on linux-based systems, you rebuild the packages and add the winbind libraries to the ./configure path. See xref:datastores/ad/winbind.adoc[Installing winbind] for more details.
+This configuration requires Freeradius to be built with winbind auth. For example, on linux-based systems, you rebuild the packages and add the winbind libraries to the ./configure path. See xref:datastores/ad/winbind.adoc[Install Winbind] for more details.
-=== Testing
+=== Tests
If everything works successfully, you'll see an entry in the AD Domain Controller's audit log similar to the snippit below:
When FreeRADIUS is integrated with Active Directory, only authorized users gain access to network resources, enhancing the overall security of your network. Active Directory functions as a centralized datastore for user accounts and security policies, simplifying user management and access rights across the network. By integrating with AD, FreeRADIUS can leverage the exisiting infrastructure and be scaled up for larger systems.
-== xref:datastores/ad/samba.adoc[Using Samba]
-
-FreeRADIUS uses Samba to integrate with Active Directory for authentication. For authorization such as group membership, FreeRADIUS can query Active Directory over LDAP.
-
-For the next steps, see the following:
+For your next steps, see the following:
* xref:datastores/ad/samba.adoc[Using Samba]
-* xref:datastores/ad/ntlm_mschap.adoc[Configuring ntlm]
-* xref:datastores/ad/winbind.adoc[Installing winbind]
+* xref:datastores/ad/ntlm_mschap.adoc[Configure NTLM]
+* xref:datastores/ad/winbind.adoc[Install Winbind]
= Join FreeRADIUS to AD Domain
-Some deployments use Active Directory services to use in mschap based authentications. The RADIUS server must alreay be up and running and basic authentication works (pap/chap). For a freeRADIUS server to fully leverage the AD server and relevant services, the RADIUS server must first be configured and then joined to the domain (or samba realm).
+Some deployments use Active Directory services to use in mschap based authentications. The RADIUS server must alreay be up and running and basic authentication works (pap/chap). For a FreeRADIUS server to fully leverage the AD server and relevant services, the RADIUS server must first be configured and then joined to the domain (or samba realm).
== Configuration of variables
-= Configuring ntlm_auth
+= Configure ntlm_auth
Once you have verified that Samba is installed and working correctly, and that the `ntlm_auth` program works, you can proceed with configuring FreeRADIUS to use ntlm_auth. For initial testing, we use the exec module, and will run the exact command line used in the previous testing step.
}
```
-== Testing `ntlm_auth`
+== Test ntlm_auth
Add the following text for testing purposes only to the top of the users file. The "users" file is located at `raddb/mods-config/files/authorize`.
This text means that authentication succeeded. A few lines above this text, the debug output will also show the exact command line used to run `ntlm_auth`.
-== Configuring FreeRADIUS to use `ntlm_auth` for MS-CHAP
+== Configure FreeRADIUS to use `ntlm_auth` for MS-CHAP
-Once you have the previous steps working, configuring FreeRADIUS to use `ntlm_auth` for MS-CHAP is simple. First, delete the testing entry used above from the users file, as leaving it in will break other authentication types. Then, find the mschap module in raddb/modules/mschap file, and look for the line containing `ntlm_auth = `. It is commented out by default, and should be uncommented, and edited to be as follows. As before, update the fields in bold to match your local configuration.
+Once you have the previous steps working, configure FreeRADIUS to use `ntlm_auth` for MS-CHAP. First, delete the testing entry used above from the users file, as leaving it in will break other authentication types. Then, find the mschap module in raddb/modules/mschap file, and look for the line containing `ntlm_auth = `. It is commented out by default, and should be uncommented, and edited to be as follows. As before, update the fields in bold to match your local configuration.
```
-== Configuring Authentication with Active Directory (AD)
+= Using Samba to Authenticate against AD
-Once the PAP authentication test has been successful, the next step for sites using Active Directory is to configure the system to perform user authentication against Active Directory. The clear-text passwords are unavailable through Active Directory, so we have to use Samba, and the ntlm_auth helper program. In this configuration, we are using Active Directory as an authentication oracle, and not as an LDAP database.
+FreeRADIUS uses Samba to integrate with Active Directory (AD) for authentication. For authorization such as group membership, FreeRADIUS can query an Active Directory over LDAP.
-Using ntlm_auth for PAP authentication may not work on recent versions of Samba and Active Directory. If so, just skip to the next section.
+== Configure Authentication with AD
-Once Samba has been installed on your system, you should edit the smb.conf file, and configure the [global] section to point to your NT server, including hostname and NT domain.
+Once the PAP authentication test has been successful, the next step for sites using AD is to configure the system to perform user authentication against AD. The clear-text passwords are unavailable through Active Directory, so we have to use Samba, and the `ntlm_auth` helper program. In this configuration, we are using AD as an authentication oracle, and not as an LDAP database.
+Using `ntlm_auth` for PAP authentication may not work on recent versions of Samba and Active Directory. If so, just skip to the next section.
+
+Once Samba has been installed on your system, you should edit the `smb.conf` file, and configure the [global] section to point to your NT server, including hostname and NT domain.
+
+```
# workgroup = NT-Domain-Name
workgroup = MYDOMAIN
-...
+
+
# Security mode. Most people will want user level security. See
# security_level.txt for details.
security = ads
# Use password server option only with security = server
password server = nt-server-hostname.company.com
-...
+
realm = realm.company.com
-For Samba 4, you also have to set the ntlm authconfiguration variable. It should be set to either yes, or to mschapv2-and-ntlmv2-only. This configuration needs to be set all participating Samba members, and also on (Samba4) AD-DC servers.
+```
- ntlm auth = mschapv2-and-ntlmv2-only
-...
-You may also have to edit the /etc/krb5.conf file, to add an entry that points to the Active Directory Server. This is often not necessary, as Samba can just "figure it out" when Active Directory is also the main DNS server.
+For Samba 4, you also have to set the `ntlm auth` configuration variable. It should be set to either `yes`, or to `mschapv2-and-ntlmv2-only`. This configuration needs to be set all participating Samba members, and also on (Samba4) AD-DC servers.
+ `ntlm auth = mschapv2-and-ntlmv2-only`
+
+You may also have to edit the `/etc/krb5.conf` file, to add an entry that points to the Active Directory Server. This is often not necessary, as Samba can just "figure it out" when Active Directory is also the main DNS server.
+
+```
[realms]
-...
+
realm.company.com = {
kdc = nt-server-hostname.company.com
}
-...
+```
== Start the Samba and Kerberos servers, and as root join the domain:
-$ net join -U Administrator
+`$ net join -U Administrator`
+
Enter the administrator password at the prompt.
Next, verify that a user in the domain can be authenticated:
-$ wbinfo -a user%password
-You should see a number of lines of text, followed by authentication succeeded. The next step is to try the same login with the ntlm_auth program, which is what FreeRADIUS will be using:
+`$ wbinfo -a user%password`
+
+You should see a number of lines of text, followed by authentication succeeded. The next step is to try the same login with the `ntlm_auth` program, which is what FreeRADIUS will be using:
+`$ ntlm_auth --request-nt-key --domain=MYDOMAIN --username=user --password=password`
-$ ntlm_auth --request-nt-key --domain=MYDOMAIN --username=user --password=password
-If all goes well, you should see authentication succeeding (NT_STATUS_OK). You may also see the NT_KEY output, which is needed in order for FreeRADIUS to perform MS-CHAP authentication.
+If all goes well, you should see authentication succeeding (`NT_STATUS_OK`). You may also see the `NT_KEY` output, which is needed in order for FreeRADIUS to perform MS-CHAP authentication.
-== Configuring FreeRADIUS to use ntlm_auth
-Once you have verified that Samba is installed and working correctly, and that the ntlm_auth program works, you can proceed with configuring FreeRADIUS to use ntlm_auth. For initial testing, we will be using the exec module, and will run the exact command line used above.
+== Configure FreeRADIUS to use ntlm_auth
-Create or edit the ntlm_auth module configuration. In version 2, this file should be saved as raddb/modules/ntlm_auth. In version 3, it should be saved as raddb/mods-enabled/ntlm_auth. The contents of the file are below, with the fields to edit in bold.
+Once you have verified that Samba is installed and working correctly, and that the `ntlm_auth` program works, you can proceed with configuring FreeRADIUS to use `ntlm_auth`. For initial testing, we will be using the `exec` module, and will run the exact command line used above.
+The module configuration is located in `mods-enabled/ntlm_auth`. The contents of the file are below, with the fields to edit in bold.
+
+```
exec ntlm_auth {
wait = yes
program = "/path/to/ntlm_auth --request-nt-key --domain=MYDOMAIN --username=%{mschap:User-Name} --password=%{User-Password}"
}
-This configuration tells the server to run the ntlm_auth program with the user name and password obtained from the Access-Request. You will also have to list ntlm_auth in the authenticate sections of each the raddb/sites-enabled/default file, and of the raddb/sites-enabled/inner-tunnel file:
+```
+
+This configuration tells the server to run the `ntlm_auth` program with the user name and password obtained from the Access-Request. You will also have to list `ntlm_auth` in the authenticate sections of each the `sites-enabled/default` file, and of the `sites-enabled/inner-tunnel` file:
-authenticate {
+```
+authenticate ntlm_auth {
...
ntlm_auth
...
}
-and add the following text for testing purposes only to the top of the users file. In version 3, the "users" file has moved to raddb/mods-config/files/authorize.
+```
+
+Add the following text for testing purposes only to the top of the `users` file. In version 3 and above, the "users" file has moved to `mods-config/files/authorize`.
+
+`DEFAULT Auth-Type = ntlm_auth`
-DEFAULT Auth-Type = ntlm_auth
This configuration says "for all users, if the authenticate method has not been set, set it to use the ntlm_auth program".
-Start the server using radiusd -X, and wait for the debugging text to stop scrolling by. If all goes well, you should see the following text:
+Start the server using `radiusd -X`, and wait for the debugging text to stop scrolling by. If all goes well, you should see the following text:
Ready to process requests.
In another terminal window on the same machine, type the following command:
-$ radtest user password localhost 0 testing123
-If all goes well, you should see the server returning an Access-Accept message, and the window with radtest should print text similar to the following:
+`$ radtest user password localhost 0 testing123`
+
+If all goes well, you should see the server returning an Access-Accept message, and the window with `radtest` should print text similar to the following:
+```
rad_recv: Access-Accept packet from host 127.0.0.1 port 1812, length=20
-This text means that authentication succeeded. A few lines above this text, the debug output will also show the exact command line used to run ntlm_auth.
+```
-== Configuring FreeRADIUS to use ntlm_auth for MS-CHAP
-Once you have the previous steps working, configuring FreeRADIUS to use ntlm_auth for MS-CHAP is simple. First, delete the testing entry used above from the users file, as leaving it in will break other authentication types. Then, find the mschap module in raddb/modules/mschap file, and look for the line containing ntlm_auth = . It is commented out by default, and should be uncommented, and edited to be as follows. As before, update the fields in bold to match your local configuration.
+This text means that authentication succeeded. A few lines above this text, the debug output will also show the exact command line used to run `ntlm_auth`.
+== Configure FreeRADIUS to use ntlm_auth for MS-CHAP
+
+Once you have the previous steps working, configuring FreeRADIUS to use `ntlm_auth` for MS-CHAP is simple. First, delete the testing entry used above from the `users` file, as leaving it in will break other authentication types. Then, find the mschap module in raddb/modules/mschap file, and look for the line containing `ntlm_auth = `. It is commented out by default, and should be uncommented, and edited to be as follows. As before, update the fields in bold to match your local configuration.
+
+```
ntlm_auth = "/path/to/ntlm_auth --request-nt-key --allow-mschapv2 --username=%{mschap:User-Name:-None} --domain=%{%{mschap:NT-Domain}:-MYDOMAIN} --challenge=%{mschap:Challenge:-00} --nt-response=%{mschap:NT-Response:-00}"
-Start the server and use radtest to send an MS-CHAP authentication request. You will need to have version 2.1.10 or later for this to work:
+```
+
+Start the server and use radtest to send an MS-CHAP authentication request.
+
+`$ radtest -t mschap bob hello localhost 0 testing123`
-$ radtest -t mschap bob hello localhost 0 testing123
If everything goes well, you should see the server returning an Access-Accept message as above.
If it does not work, double-check the password you entered on the supplicant against the password in Active Directory. If it still does not work, it might be a bug in Samba. Change your version of Samba, either by installing a fixed version, or by repeatedly down-grading it (and testing) until it works.
-If it does not work, then it is possible to test authentication with just the ntlm_auth command-line. Look at the FreeRADIUS debug output, and see the arguments passed to ntlm_auth. Copy and paste them to a command-line, and then use that command line for testing. This limited test is often simpler and faster than running a complex test with a full RADIUS server. When this limited test passes, then authentication with FreeRADIUS will work, too.
+If it does not work, then it is possible to test authentication with just the `ntlm_auth` command-line. Look at the FreeRADIUS debug output, and see the arguments passed to ntlm_auth. Copy and paste them to a command-line, and then use that command line for testing. This limited test is often simpler and faster than running a complex test with a full RADIUS server. When this limited test passes, then authentication with FreeRADIUS will work, too.
-= Installing Winbind
+= Install Winbind
To integrate linux-based systems with a Windows Active Directory domain, you need to install Winbind.
== Build winbind from packages
*Debian or Ubuntu*
+
`apt-get install -y samba winbind krb5-user`
-*RHEL or Rocky or Linux based systems
+*RHEL or Rocky or Linux based systems*
+
`yum install -y samba-winbind krb5-workstation`
-== Restart the winbind service:
+== Restart the winbind service
`systemctl stop winbind`
`systemctl start winbind`
-= Datastores
+= Set Up Datastores
-Datastores store data and are accessed by the FreeRADIUS server to retrieve that data. Datastores do not perform authentications and possess limited decision making capabilities.
+Datastores are used for storing information, such as user credentials or session data, which the FreeRADIUS server can access when needed. Datastores do not perform authentications and have limited decision making capabilities.
The key differences between RADIUS servers and datastores are the way they support policies and authentication. The role of a datastore is to provide data to a RADIUS server. The RADIUS server authenticates the user with a select authentication method on the retrieved data.
When a RADIUS server authenticates a user or stores accounting data for that user, it reads from or writes to a datastore. User information (i.e., user name, password, credit amount) and session data (i.e., total session time and statistics for total traffic to and from the user) are stored on this datastore or directory. We use the term "datastore" to mean that some of the storage methods are not traditional databases, but they do still store data.
-== Setting up Datastores
+== Preparation
To set up a datastore, you'll need to install the software, configure the data storage location, and connect the datastore with FreeRADIUS. The main steps to complete are:
* Provision the datastore and populate records.
* Connect the datastore with FreeRADIUS.
-== Integrate Datastore with FreeRADIUS
+== Integrate datastore with FreeRADIUS
To configure a datastore with FreeRADIUS, you'll need to edit the FreeRADIUS configuration files and enable the relevant modules. This section outlines the supported datastores, how to connect, and implementations. See the following sub-sections for your specific datastore application instructions:
-* xref:datastores/ad/index.adoc[Active Directory]
-* xref:datastores/ldap.adoc[LDAP]
-* xref:datastores/redis.adoc[Redis]
-* xref:datastores/sql.adoc[SQL]
+== Sections in this guide
+
+=== xref:datastores/ad/index.adoc[Active Directory]
+
+Integrate FreeRADIUS with Microsoft Active Directory(AD), using Samba as an intermediary, especially for Wi-Fi authentication.
+
+=== xref:datastores/ldap.adoc[LDAP]
+
+Enable the ldap module to allow FreeRADIUS to authenticate users against an LDAP directory. Configure connection details, authentication methods, and user attribute mappings by modifying configuration files.
+
+=== xref:datastores/redis.adoc[Redis]
+
+Enable the Redis module and configure it to connect to your Redis server. Modify the FreeRADIUS configuration files to specify the Redis server's hostname, port, and password.
+
+=== xref:datastores/sql.adoc[SQL]
}
-## Configuring logging
+## Configure logging
The examples above use the linelog module as an example, but in
reality many different logging methods could be used in the same
The section is broken down into the following top-level areas:
-xref:howto:installation/index.adoc[Installing and Upgrading] contains instructions for building and installing freeRADIUS from packages and source.
-
-xref:modules/configuring_modules.adoc[Configuring Modules] provides worked examples on using the various modules in common deployment scenarios.
-
-xref:protocols/index.adoc[Protocols]
-*** xref:protocols/dhcp/index.adoc[DHCP]
-**** xref:protocols/dhcp/prepare.adoc[Preparation]
-**** xref:protocols/dhcp/enable.adoc[Enabling the DHCP service]
-**** xref:protocols/dhcp/test.adoc[Testing the DHCP service]
-**** xref:protocols/dhcp/policy.adoc[Defining the DHCP policy]
-***** xref:protocols/dhcp/policy_ippool_creation.adoc[IP pool creation]
-***** xref:protocols/dhcp/policy_common_options.adoc[Common options]
-***** xref:protocols/dhcp/policy_network_options.adoc[Network options and IP pool selection]
-***** xref:protocols/dhcp/policy_subnet_options.adoc[Subnet options]
-***** xref:protocols/dhcp/policy_device_options.adoc[Device, class and group options]
-***** xref:protocols/dhcp/policy_ippool_access.adoc[IP pool access restriction]
+xref:howto:installation/index.adoc[Install and Upgrade] contains instructions for building and installing FreeRADIUS from packages and source.
+
+xref:modules/configuring_modules.adoc[Configure Modules] provides worked examples on using the various modules in common deployment scenarios.
+
+* xref:protocols/index.adoc[Protocols]
+** xref:protocols/dhcp/index.adoc[DHCP]
+*** xref:protocols/dhcp/prepare.adoc[Preparation]
+*** xref:protocols/dhcp/enable.adoc[Enabling the DHCP service]
+*** xref:protocols/dhcp/test.adoc[Testing the DHCP service]
+*** xref:protocols/dhcp/policy.adoc[Defining the DHCP policy] that includes ip pool management.
** Security Certificates
*** xref:os/letsencrypt.adoc[Using LetsEncrypt certificates]
-= Attribute name changes from v3 to v4.
+= Attribute name changes from v3 to v4
Version 4 has significantly changed much of the server internals. One
part of that is renaming the dictionary attributes. In v3, the names
...
```
-
-== Alias Dictionaries for compatibility with v3
+== Alias dictionaries for v3 compatibility
The dictionaries in the `${dictdir}/radius/alias` directory are
intended to help administrators migrate from version 3 to version 4.
-= Build and Install FreeRadius on Ubuntu
+= Debian and Ubuntu
+
+To Build and Install FreeRadius on Ubuntu, obtain the install files from one of two ways:
* Install from repositories
* Build and Install from Source
-== Installing from repositories
+== Install from repositories
This is usually the easiest solution, as long as the system packages are the latest in their own main version, or can be updated before building. Building from source is recommended as it will contain the latest version, that contains the most recent bug fixes.
sudo freeradius -X
----
-== Installing from Source
+== Install from source
Installing from source can be daunting for first time users, but as long as you read the output of the building process, it tell you what went wrong or what is missing.
The install might show errors. Read the error !! Ask questions on freeradius list if you cannot figure it out. v2 will fail install often on open_ssl issues. Quick thing to change to prevent just that error is to edit a config file so freeradius will not complain about ssl that might be vulnerable. ( /etc/freeradius/eap.conf (v2) or /etc/freeradius/modules-enabled/eap )
-== Building on Debian or Ubuntu
+== Build on Debian or Ubuntu
Building Debian packages (including Ubuntu) of FreeRADIUS from source is kept as simple as possible.
-== Building the stable release (v3.0)
+== Build the stable release (v3.0)
Building packages is very simple. First obtain a copy of the source and unpack it. Second, build the packages.
-== Getting the source
+== Get the source
include::partial$get_the-source
sudo mk-build-deps -ir debian/control
----
-== Building Packages
+== Build Packages
Having retrieved whichever version of the source you require and installed dependencies, build the FreeRADIUS packages:
On recent releases you should ensure the source tree is completely clean before running `make deb`, e.g. do not run `./configure` first. (However, on releases before 3.0.16 you _must_ run `./configure` first.)
-== Building from source
+== Build from source
Alternatively, rather than building packages, you can build the source directly. Note that you will need to ensure all required dependencies are installed first (such as `libkqueue-dev`, `libtalloc-dev`, and `libssl-dev`).
sudo make install
----
-== Building development versions (v4.0)
+== Build development versions (v4.0)
Note that version 4 is for developers only. **Do not use these versions unless you know what you are doing.**
-== Upgrading GCC
+== Upgrade GCC
include::partial$upgrade_gcc.adoc[]
-== Hard Dependencies
+== Dependencies
----
sudo apt-get install libssl-dev libtalloc-dev libkqueue-dev
----
-== Building
+== Build and install
Get the source as described above, then:
-= Installing and Upgrading
+= Install and Upgrade
FreeRADIUS is available from many locations. Select one of the options below to begin installing your server:
installation methods, as well as instructions on building
packages locally.
-== Getting Started
-
-This page describes how to perform the first install of
+The following steps describes how to perform the first install of
FreeRADIUS. It assumes a basic knowledge of Unix system administration.
No RADIUS knowledge is required.
-## Install the Server
+== Install the server
Where possible, while learning the basics, it's recommended that
beginners use the packaging system that is used by your operating
`radiusd` and `/etc/raddb/` are used in this guide for simplicity.
====
-### Best Practice
+=== Best practice
Once the server has been installed, the first thing to do is *change as
little as possible*. The default configuration is designed to work
and usually contains error messages which describe what went wrong, and
how to fix it.
-## Start the server
+== Start the server
include::partial$start_server.adoc[]
explanation of the debug output.
-## Initial Tests
+== Initial tests
Once your server is up and running, test basic authentication.
include::partial$initial_tests.adoc[]
-## Add a client
+== Add a client
After a successful authentication, add a client, and verify that packets are successfully sent and received.
include::partial$add_client.adoc[]
***
-## Configure the Server
+## Configure the server
include::partial$config_server.adoc[]
-= Building on OSX
+= OSX
-FreeRADIUS can be installed on OSX platforms, however some environment setup is required. Additional dev tools are also configured before the server installation.
+FreeRADIUS can be built and installed on OSX platforms, however some environment setup is required. Additional dev tools are also configured before the server installation.
-== Hard Dependencies
+== Dependencies
=== Homebrew
```bash
brew install talloc
```
-=== Install Script
+=== Install script
Run the `install_deps.sh` script to install the build dependencies. It's recommended to create a copy of this file and edit locally. You can remove apps, libs, or utilites that you don't need such as postgresql. Ensure that you use the updated file when running the script.
-=== Xcode Tools
+=== Xcode tools
Install Xcode from the https://www.apple.com/ca/app-store/[app store]. This tool is used to help develop, test, and manage your applications.
If using a different shell, ensure you copy the environment paramenters to your current shell.
====
-=== Getting the Source
+=== Get the source
Get the FreeRADIUS source from one of these methods:
include::partial$get_the_source.adoc[]
-=== Build= from Source and Install
+=== Build from source and install
To begin the install process, enter the following commands:
make
```
-=== Running FreeRADIUS in the background all of the time.
+=== Run FreeRADIUS in the background all of the time
The information below is for future reference.
-== Install from packages
+= Install from Packages
include::ROOT:partial$v3_warning.adoc[]
* https://packages.inkbridgenetworks.com/#fr32-centos[Centos]
* https://packages.inkbridgenetworks.com/#fr32-rhel[RHEL]
-=== Distribution-supplied packages
+== Distribution-supplied packages
While many operating system distributions ship FreeRADIUS
packages, the versions they include are often years out of date.
-= Building on RHEL7
+= Redhat and Rocky
-There are minimal requirements to building on RHEL, including Rocky or Alma versions.
+There are minimal requirements to building on Redhat (RHEL), including Rocky or Alma versions.
[NOTE]
====
Centos Stream is now a rolling release, feeder distribution for RHEL and no longer supported.
====
-== Hard Dependencies
+== Dependencies
=== libtalloc
include::partial$libkqueue-rpm.adoc
-=== Upgrading GCC (>= v4.0.x and master branch only)
+=== Upgrade GCC (>= v4.0.x and master branch only)
> GCC upgrade only required for versions >= v4.0.x you can skip this step for v3.0.x and below.
If you're building on older versions of RedHat then you'll need to compile GCC from source.
-== Getting the source
+== Get the source
include::partial$get_the_source.adoc[]
-== Build from Source and Install
+== Build from source and install
If you're using unstable code or encountering issues with the install, use `configure --enable-developer` option.
sudo make install
----
-== Building Packages
+== Build packages
=== With Oracle support
-== Build from Source
+= Build from Source
We recommend that you xref:howto:installation/packages.adoc[install from packages] if possible. Full instructions on building and installing from source
code follow.
sudo make install
----
-=== Custom build
+== Custom build
FreeRADIUS has GNU autoconf support. This means you have to run
`./configure`, and then run `make`. To see which configuration
without first carefully reading the output of this process as it
often contains the information needed to resolve a problem.
-== Upgrading To A New Minor Release
+== Upgrade to a new minor release
The installation process will not over-write your existing configuration
files. It will, however, warn you about the files it did not install.
that is is both simpler and safer to migrate your configurations rather
than to try and just get the old configuration to work.
-== Running the server
+== Run the server
If the server builds and installs, but doesn’t run correctly, then
you should first use xref:ROOT:debugging/radiusd_X.adoc[debugging mode] to figure out
of the messages which are printed to the screen, the answer to
your problem will often be in a warning or error message.
-Configuring a RADIUS server for complex local authentication isn’t a trivial
+Configure a RADIUS server for complex local authentication isn’t a trivial
task. Your _best_ and _only_ method for debugging it is to read
the debug messages, where the server will tell you exactly what
it’s doing, and why. You should then compare its behaviour to what
make the appropriate investment in order to properly support a critical
resource such as your authentication servers.
-Configuring and running the server MAY be complicated. Many modules have
+Configure and running the server MAY be complicated. Many modules have
`man` pages. See `man rlm_pap`, or `man rlm_*` for information.
Please read the documentation in the doc/ directory. The comments in the
configuration files also contain a lot of documentation.
`authorize`, etc.
* each `listen` section needs to be converted to the v4 format.
-== Upgrading from older versions
+== Upgrade from older versions
-=== Upgrading from v2
+=== Upgrade from v2
If you are upgrading from v2 you should read the v3 version of this
file. It describes changed from v2 to v3. This file describes only
the changes from v3 to v4.
-=== Upgrading from v3
+=== Upgrade from v3
When upgrading, please start with the default configuration of v4. Then,
move your v3 configuration over, one module at a time. Check this file
protocols.
-== Attribute Names
+== Attribute names
Much of the information in this section is also in the
`raddb/dictionary` file
for a way to regain one global configuration for `Access-Request`
packets.
-=== Instantiate Section
+=== Instantiate section
The `instantiate` section has been removed. It originally started out
as a way to ensure that modules were instantiated in a particular
In this case, this definition creates a `redundant_sql` virtual module.
-== Virtual Servers
+== Virtual servers
There are some changes to the virtual servers in `v4`. First, every
virtual server has to begin with an entry:
contains a `namespace` parameter. Please look at those files for
examples of configuring and running each supported protocol.
-=== Listen Sections
+=== Listen sections
The `listen` sections have changed. There is now a `type` entry, which
lists the packet type by their correct name (e.g._`Access-Request`
The dynamic client functionality behaves the same for all protocols
supported by the server. e.g. RADIUS, DHCP, VMPS, TACACS+, etc.
-== Processing Sections
+== Processing sections
All of the processing sections have been renamed. Sorry, but this was
required for the new features in v4.
examples and more information.
====
-=== Update Sections
+=== Update sections
A major difference between v3 and v4 is that `update` sections are no
longer necessary. See the <<Unlang Syntax>> section below for full
details.
-== Proxying
+== Proxy
-Proxying has undergone massive changes. The `proxy.conf` file no
+The proxy feature has undergone massive changes. The `proxy.conf` file no
longer exists, and everything in it has been removed. e.g. `realm`,
`home_server`, `home_server_pool` no longer exist. The old proxying
functionality was welded into the server core, which made many useful
}
----
-NOTE: Of course, you will have to use the names of the `radius`
+[NOTE]
+====
+Of course, you will have to use the names of the `radius`
modules in your configuration, and not `home_server_1`, etc.
+====
* `type = load-balance` - replaced with `unlang`
special meaning in v4. You can use any attribute or string expansion as
part of the `load-balance` key.
-=== Things which were impossible in v3
+=== Limitations in v3
In v3, it was impossible to proxy the same request to multiple
destinations. This is now trivial. In any processing section, do:
an alternative configuration item (e.g. `radius_db` in the case of
postgresql).
-== Unlang Syntax
+== Unlang syntax
Many new xref:reference:unlang/index.adoc[unlang] keywords have been added.
`%{expr:...}` has been removed. You can instead use in-place expressions, such as `%{1 + 2}` or `%{NAS-Port + 14}`.
-== New Modules
+== New modules
The following modules are new in v4.
from the NAS. That behavior is good, but there are times where
retransmitting packets at the proxy is better.
-== Changed Modules
+== Changed modules
The following modules exhibit changed behaviour.
will return `true`.
-==== Accounting and Post-Auth module calls
+=== Accounting and Post-Auth module calls
The `reference` option has been removed from `accounting` and `post-auth`
sql module configuration.
}
```
-==== Profiles
+=== Profiles
The `default_user_profile` has been removed. No one used it, as that
behavior was already supported by the group functionality. See
`=<hexit><hexit>` escape sequences in expanded values. The
`safe_characters` config item is ignored when using MySQL databases.
-==== rlm_sql_postgresql
+=== rlm_sql_postgresql
Now calls `PQescapeStringConn` and no longer produces
`=<hexit><hexit>` escape sequences in expanded values. The
The `winbind` module uses an expansion `%winbind.group(<name>)` instead of
`Winbind-Group == <name>`.
-== Deleted Modules
+== Deleted modules
The following modules have been deleted
}
```
-== Deleted Functionality
+== Deleted functionality
Many "virtual" or "fake" attributes have been removed or renamed.
`Packet-Src-Port` should be replaced by `Net.Src.Port`.
-== Recommended Changes
+== Recommended changes
In v3, many people had a habit of just adding `"..."` around _everything_. For example:
:module_name:
-= Configuring the CHAP module
+= CHAP
-The xref:reference:raddb/mods-available/chap.adoc[mods-available/chap]
+When configuring the CHAP module, see the xref:reference:raddb/mods-available/chap.adoc[mods-available/chap]
configuration file describes the configuration parameters accepted by
the CHAP module, and what they do. This document explains how to
perform testing with the CHAP module.
include::howto:partial$pre_test.adoc[]
-== Editing mods-available/chap
+== Edit mods-available/chap
The xref:reference:raddb/mods-available/chap.adoc[mods-available/chap] module
contains no configuration items, and does not need to be edited.
-== Enabling mods-available/chap
+== Enable mods-available/chap
The `chap` module is enabled by creating a soft link from the
`mods-enabled/` directory to the `mods-available/` directory.
The default installation will automatically enable the `chap` module.
In most circumstances, no additional work is required.
-== Testing the Server
+== Test the server
include::howto:partial$post_test.adoc[]
-== Testing CHAP Authentication
+== Test CHAP authentication
Once the server is started in debugging mode, CHAP authentication can
be performed via the following command:
CHAP calculations in order to put the correct `CHAP-Password` value
into the packet.
-NOTE: The server must be configured with a known user and a "known
+[NOTE]
+====
+The server must be configured with a known user and a "known
good" password before any CHAP tests are performed. In this case, we
assume that the server knows about a user `bob` with password `hello`.
+====
The output of `radclient` should look like the following. Some of the
numbers may be different, but the general format should be the same.
that it has been given a `Password.Cleartext` in order to authenticate
the user. The source of that `Password.Cleartext` is unimportant.
-== Disabling CHAP
+== Disable CHAP
The local system requirements may be that CHAP authentication is
forbidden. In that case, the `chap` module should be removed from the
to ensure that the current configuration works _before_ making changes
to it.
-== Editing mods-available/MODULE
+== Edit mods-available/MODULE
As with all FreeRADIUS configuration files, please change at little as
possible in the default configuration. The defaults are usually close
to being correct. All that is necessary is to make minor changes, and
_test_ them. FreeRADIUS should look for data.
-== Enabling mods-available/MODULE
+== Enable mods-available/MODULE
A module is enabled by creating a soft link from the `mods-enabled/`
directory to the `mods-available/` directory.
file in place, if there is a need to refer to it in the future. The
choice of which method to use is up to the local administrator.
-== Testing the Server
+== Test the server
The configuration of the server can be tested for syntactical
correctness via the following command:
-= Extensible Authentication Protocol (EAP)
+= EAP
include::ROOT:partial$v3_warning.adoc[]
-== Introduction
-
-Extensible Authentication Protocol(EAP), `RFC 3748`, is an authentication
+The Extensible Authentication Protocol (EAP), `RFC 3748`, is an authentication
framework and data link layer protocol that allows network access points
to support multiple authentication methods. Each EAP Type indicates a
specific authentication mechanism. The `802.1X` standard authenticates
The following IEEE standards are also relevant:
* https://standards.ieee.org/ieee/802.1X/7345/:"IEEE 802.1X" - Port-Based Network Access Control
-== EAP Code Organization
+== 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
}
----
-NOTE: You cannot have empty eap stanza. At least one EAP-Type sub-stanza
+[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
NOTE: `EAP-SIM` will send WEP attributes to the resquestor.
-== EAP Sub-Types
+== EAP sub-types
=== LEAP
Although there is no in-built support for PEAP-GTC in MS Windows, it is supported by the Cisco CCX extensions program. CCX compatability is enabled by default on many vendor-provided 802.11A/B/G clients.
-Note: The PEAP standard was created by Microsoft, Cisco, and RSA after EAP-TTLS had already come on the market. Even with its late start, Microsoft’s and Cisco’s size allowed them to quickly overtake EAP-TTLS in the market. Microsoft and Cisco parted ways when Microsoft only supported the PEAPv0 standard while Cisco supported both PEAPv0 and PEAPv1. PEAPv0 and PEAPv1 both refer to the outer authentication method and is the mechanism that creates the secure TLS tunnel to protect subsequent authentication transactions while EAP-MSCHAPv2, EAP-GTC, and EAP-SIM refer to the inner authentication method which facilitates user or device authentication. From Cisco’s perspective, PEAPv0 supports inner EAP methods EAP-MSCHAPv2 and EAP-SIM while PEAPv1 supports inner EAP methods EAP-GTC and EAP-SIM. Since Microsoft only supports PEAPv0 and doesn’t support PEAPv1, Microsoft simply calls PEAPv0 PEAP without the v0 or v1 designator. Another difference between Microsoft and Cisco is that Microsoft only supports PEAPv0/EAP-MSCHAPv2 mode but not PEAPv0/EAP-SIM mode. However, Microsoft supports another form of PEAPv0 (which Microsoft calls PEAP-EAP-TLS) that Cisco and other third-party server and client software don’t support. PEAP-EAP-TLS does require a client-side digital certificate located on the client’s hard drive or a more secure smartcard. PEAP-EAP-TLS is very similar in operation to the original EAP-TLS but provides slightly more protection due to the fact that portions of the client certificate that are unencrypted in EAP-TLS are encrypted in PEAP-EAP-TLS. Since few third-party clients and servers support PEAP-EAP-TLS, users should probably avoid it unless they only intend to use Microsoft desktop clients and servers. Ultimately, PEAPv0/EAP-MSCHAPv2 is the only form of PEAP that most people will ever know. PEAP is so successful in the market place that even Funk Software, the inventor and backer of EAP-TTLS, had no choice but to support PEAP in their server and client software for wireless networks.
+[NOTE]
+====
+The PEAP standard was created by Microsoft, Cisco, and RSA after EAP-TTLS had already come on the market. Even with its late start, Microsoft’s and Cisco’s size allowed them to quickly overtake EAP-TTLS in the market. Microsoft and Cisco parted ways when Microsoft only supported the PEAPv0 standard while Cisco supported both PEAPv0 and PEAPv1. PEAPv0 and PEAPv1 both refer to the outer authentication method and is the mechanism that creates the secure TLS tunnel to protect subsequent authentication transactions while EAP-MSCHAPv2, EAP-GTC, and EAP-SIM refer to the inner authentication method which facilitates user or device authentication. From Cisco’s perspective, PEAPv0 supports inner EAP methods EAP-MSCHAPv2 and EAP-SIM while PEAPv1 supports inner EAP methods EAP-GTC and EAP-SIM. Since Microsoft only supports PEAPv0 and doesn’t support PEAPv1, Microsoft simply calls PEAPv0 PEAP without the v0 or v1 designator. Another difference between Microsoft and Cisco is that Microsoft only supports PEAPv0/EAP-MSCHAPv2 mode but not PEAPv0/EAP-SIM mode. However, Microsoft supports another form of PEAPv0 (which Microsoft calls PEAP-EAP-TLS) that Cisco and other third-party server and client software don’t support. PEAP-EAP-TLS does require a client-side digital certificate located on the client’s hard drive or a more secure smartcard. PEAP-EAP-TLS is very similar in operation to the original EAP-TLS but provides slightly more protection due to the fact that portions of the client certificate that are unencrypted in EAP-TLS are encrypted in PEAP-EAP-TLS. Since few third-party clients and servers support PEAP-EAP-TLS, users should probably avoid it unless they only intend to use Microsoft desktop clients and servers. Ultimately, PEAPv0/EAP-MSCHAPv2 is the only form of PEAP that most people will ever know. PEAP is so successful in the market place that even Funk Software, the inventor and backer of EAP-TTLS, had no choice but to support PEAP in their server and client software for wireless networks.
+====
This version of PEAP is defined through the IETF internet draft "draft-josefsson-pppext-eap-tls-eap-05 http://www.watersprings.org/pub/id/draft-josefsson-pppext-eap-tls-eap-05.txt." Note that this is an expired draft.
*EAP for UMTS Authentication and Key Agreement* is used for authentication and session key distribution using the Universal Mobile Telecommunications System (UMTS) UMTS Subscriber Identity Module (USIM). EAP AKA is defined in RFC 4187.
-== EAP Clients
+== EAP clients
The main EAP client is https://w1.fi/wpa_supplicant/
https://github.com/ANSSI-FR/audit-radius
-== FAQ and Examples
+== FAQ and examples
How do i use it?
...
}
- # ldap gets the Configured password.
+ # ldap gets the configured password.
# eap sets the authenticate type as EAP
recv Access-Request {
...
-= Kerberos 5 (krb5)
+= KRB5
The `rlm_krb5` FreeRADIUS module enables the use of Kerberos 5 for
authentication.
-= Configuring Accounting
+= Configure Accounting
// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Configuring Authentication
+= Configure Authentication
== Testing
- _variant 3_ - Group objects contain membership attributes referencing user objects by DN.
- _variant 4_ - Group objects contain membership attributes referencing user objects by name.
-== Configuring group lookups
+== Configure group lookups
-=== Editing mods-available/ldap to configure _variant 1_ group checks
+=== Edit mods-available/ldap to configure _variant 1_ group checks
[source,config]
----
<3> Attribute within the group object containing its name.
<4> Attribute within the user object referencing groups by their DNs.
-=== Editing mods-available/ldap to configure _variant 2_ group checks
+=== Edit mods-available/ldap to configure _variant 2_ group checks
[source,config]
----
<3> Attribute within the group object containing its name.
<4> Attribute within the user object referencing groups by their name.
-=== Editing mods-available/ldap to configure _variant 3_ group checks
+=== Edit mods-available/ldap to configure _variant 3_ group checks
[source,config]
----
<3> Attribute within the group object containing its name.
<4> Attribute within the group object referencing users by their DN.
-=== Editing mods-available/ldap to configure _variant 4_ group checks
+=== Edit mods-available/ldap to configure _variant 4_ group checks
[source,config]
----
-= Configuring Authorization
+= Configure Authorization
The `authorize` method of the LDAP module is responsible for locating the
authenticating user's LDAP object.
of the LDAP module before attempting to complete any of the howto sections
listed below.
-== xref:modules/ldap/authorization/locating_the_user.adoc[Locating the user]
+== xref:modules/ldap/authorization/locating_the_user.adoc[Locate a user]
No matter what functionality of the LDAP module is being used you must
specify search DNs and filters that uniquely identify the authenticating
This section should be competed first before attempting any more advanced
configurations.
-== xref:modules/ldap/authorization/user_disambiguation.adoc[Disambiguating user objects]
+== xref:modules/ldap/authorization/user_disambiguation.adoc[Disambiguate user objects]
In some instances the same user may have objects in different areas of the
LDAP directory.
This section discusses strategies to disambiguate user objects, and select
a single user object consistently.
-== xref:modules/ldap/authorization/user_account_controls.adoc[Configuring the enable/disable attribute]
+== xref:modules/ldap/authorization/user_account_controls.adoc[Control user accounts]
In some instances it is useful to enable or disable user accounts without
removing the objects from the directory.
xref:modules/ldap/ldapsearch/index.adoc[ldapsearch] for how to determine the
appropriate values for your directory.
-== Editing mods-available/ldap to specify how to search for user objects
+== Edit mods-available/ldap to specify how to search for user objects
[source,config]
----
-= Controlling user accounts
+= Control User Accounts
In some instances it may be useful to "lock out" user accounts.
When a user is "locked out", the LDAP module will return `disallow` in (≥ v4.0.x) and `userlock` in (≤ v3.2.x).
-=== Editing mods-available/ldap to only allow access if the 'Access Attribute' is present
+=== Edit mods-available/ldap to only allow access if the 'Access Attribute' is present
[source,config]
----
If the attribute is absent or set to false then the user will be
"locked out".
-=== Editing mods-available/ldap to disable access if the 'Access Attribute' is present
+=== Edit mods-available/ldap to disable access if the 'Access Attribute' is present
[source,config]
----
-= Disambiguating user objects
+= Disambiguate User Objects
In some instances a user may have objects located in multiple areas of
the LDAP directory.
4. As a last resort you can enable the Server Side Sorting extension (if
supported) on the LDAP server (see below).
-== Enabling and configuring Server Side Sorting
+== Enable and configure Server Side Sorting
Server Side Sorting controls are specified by
https://tools.ietf.org/html/rfc2891[RFC 2891].
[TIP]
====
If you followed the
-xref:modules/ldap/bootstrap_openldap/packages.adoc[Installing OpenLDAP from
+xref:modules/ldap/bootstrap_openldap/packages.adoc[Install OpenLDAP from
packages] section you can enable the Server Side Sorting (SSS) overlay via OLC
using the ldif below.
----
====
-== Editing mods-available/ldap to enable Server Side Sorting
+== Edit mods-available/ldap to enable Server Side Sorting
[source,config]
----
-= Base configuration
+= Base Configuration
The configuration step should be little more than
xref:modules/ldap/ldapsearch/index.adoc#_translating_ldapsearch_arguments_to_rlm_ldap_configuration_items[copying the parameters used by ldapsearch]
include::howto:partial$pre_test.adoc[]
-== Editing mods-available/ldap
+== Edit mods-available/ldap
As with all FreeRADIUS configuration files, please change at little as
possible in the default configuration. The defaults are usually close
a production server. The best approach is to test one piece in isolation,
before proceeding on to the next piece.
-== Enabling mods-available/ldap
+== Enable mods-available/ldap
The `ldap` module is enabled by creating a soft link from the
`mods-enabled/` directory to the `mods-available/` directory.
cd raddb/mods-enabled && ln -s ../mods-available/ldap
----
-== Calling the LDAP module
+== Call the LDAP module
The LDAP module needs to be listed in different section depending on the
function(s) it's performing.
See xref:modules/ldap/authentication.adoc[LDAP authentication] for more detailed
information on configuring LDAP authentication.
-== Testing the Server
+== Test the server
include::howto:partial$post_test.adoc[]
-= Using OpenLDAP in a docker container
+= Docker
+
+This page explains how to configure using OpenLDAP in a docker container.
== Bootstrap
https://github.com/osixia/docker-openldap[osixia/openldap
instructions].
-== Check it works
+== Test the configuration
As a final step you should verify that test data has been loaded correctly.
This can be done using the `ldapsearch` utility using the LDAP read only user.
-= Installing and Configuring OpenLDAP
+= Install and Configure OpenLDAP
This section of the howto describes two methods of creating an OpenLDAP instance for
testing purposes.
-= Installing OpenLDAP from packages
+= Install OpenLDAP from packages
== Switch to privileged user
= LDAP
-== Introduction
-FreeRADIUS can be configured to use an LDAP server for authentication,
-authorization and accounting.
+FreeRADIUS can integrate with an LDAP server to handle authentication, authorization, and accounting tasks. The tutorials that follow are intended for readers who already understand LDAP concepts and terminology. If you are new to LDAP or unsure about how LDAP directories work, review the https://ldap.com/basic-ldap-concepts/[basic concepts] before proceeding. The FreeRADIUS documentation doesn't cover any foundational LDAP topics.
-This series of tutorials assume that the reader is familiar LDAP. If you're not
-familiar with LDAP specific terms or how LDAP directories in general operate,
-you may wish to review https://ldap.com/basic-ldap-concepts/[ldap.com - basic
-concepts], as these concepts will not be covered in FreeRADIUS documentation.
+To use LDAP, an existing LDAP server must be and tested using the ldapsearch tool.
[NOTE]
====
In an Microsoft Active Directory environment you should use `rlm_winbind` for
authentication, and `rlm_ldap` for group membership checks as described in
-xref:modules/ldap/authorization/index.adoc[authorization] section of this tuorial.
-The WinBind protocol does not support the full range of group checks that is
+xref:modules/ldap/authorization/index.adoc[authorization] section. The winbind protocol does not support the full range of group checks that is
possible with LDAP.
====
-== Preparation
+== Sections in this guide
-These preparation steps must be completed in order for the examples in the later
-sections of this tutorial to operate correctly.
+These sections must be completed in order for the examples later
+in the tutorial to operate correctly. For additional features and configuration items see the xref:reference:raddb/mods-available/ldap.adoc[mods-available/ldap] page for more details about rlm_ldap module supports.
-=== 1. Provisioning
+=== xref:modules/ldap/bootstrap_openldap/index.adoc[Install and Configure OpenLDAP]
-In order to use LDAP, there must be an existing LDAP server populated with
+In order to use LDAP, there must be an existing LDAP server provisioned with
users, groups, and possibly clients. We highly recommend using
https://www.openldap.org/[OpenLDAP] for both its flexibility and performance.
OpenLDAP LTB https://www.ltb-project.org/documentation/openldap-rpm.html[RPM] or
https://www.ltb-project.org/documentation/openldap-deb.html[DEB] packages.
-For testing purposes it's recommended to install an LDAP instances on the same
+[TIP]
+====
+For testing purposes it's recommended to install the LDAP instances on the same
machine (or inter-container network in the case of docker) as the RADIUS server
-to avoid any potential networking issues.
-
-This recommendation applies equally to high load production environments, or
-where a high level of redundancy is required.
-
-=== 2. Testing
-
-Once an LDAP server is available, it should be tested via the command-line
-xref:modules/ldap/ldapsearch/index.adoc[ldapsearch] tool. This is to ensure that
-the LDAP server has been configured correctly. If testing via `ldapsearch`
-fails, then that *MUST* those issues must be resolved before configuring
-FreeRADIUS.
-
-=== 3. Configuring the LDAP module
-
-Once the xref:modules/ldap/ldapsearch/index.adoc[ldapsearch] validation tests pass, the
-next step is to xref:modules/ldap/base_configuration/index.adoc[configure the LDAP module].
+to avoid any potential networking issues. This recommendation applies equally to high load production environments, or where a high level of redundancy is required.
+====
-OpenLDAP configuration examples detailing how to install appropriate schemas and
-populate the server with test data will be provided at the beginning of each
-tutorial section.
+=== xref:modules/ldap/ldapsearch/index.adoc[Test with Ldapsearch]
-== Sections in this tutorial
+Once the LDAP server is provisioned and available, test the server using the command-line xref:modules/ldap/ldapsearch/index.adoc[ldapsearch] tool. If the `ldapsearch` tests fail, any LDAP server configuration issues *must* be fixed before proceeding with the FreeRADIUS integration. This step ensures that authentication and data retrieval function correctly when FreeRADIUS queries the LDAP server.
-For features and configuration items not covered by this tutorial series
-xref:reference:raddb/mods-available/ldap.adoc[mods-available/ldap] page provides a complete
-reference for all the configuration items available for the rlm_ldap module.
+=== xref:modules/ldap/base_configuration/index.adoc[Base Configuration]
-=== xref:modules/ldap/base_configuration/index.adoc[Base configuration]
+Once the xref:modules/ldap/ldapsearch/index.adoc[ldapsearch] validation tests pass, the next step is to xref:modules/ldap/base_configuration/index.adoc[Configure the LDAP Module]. All basic settings required for all functions of the LDAP module are detailed here.
-Configures basic settings required for all functions of the LDAP module.
+OpenLDAP configuration examples show how to install appropriate schemas and
+populate the server with test data will be provided in each section.
-=== xref:modules/ldap/authorization/index.adoc[Authorization]
+=== xref:modules/ldap/authorization/index.adoc[Configure Authorization]
-Covers Authorization by group, enabling/disabling accounts using attributes,
+Covers authorization by group, enabling/disabling accounts using attributes,
LDAP attribute to FreeRADIUS attribute mappings, and LDAP profiles.
-=== xref:modules/ldap/authentication.adoc[Authentication]
+=== xref:modules/ldap/authentication.adoc[Configure Authentication]
Examples of configuring different methods of LDAP based authentication
(search, bind, edir).
-=== xref:modules/ldap/accounting.adoc[Accounting]
+=== xref:modules/ldap/accounting.adoc[Configure Accounting]
Examples of updating objects in LDAP after authentication completes, or when
accounting data is received.
-= Before starting
+= Prerequisites
Try to determine answers to the following questions:
-= Determining connection parameters
+= Determine connection parameters
`ldapsearch` accepts a large number of different arguments, and allow relatively
complex commands to be sent to the LDAP server.
- `-H <ldap uri>` - The LDAP server to connect to.
- `-b <dn>` - A point in the LDAP tree to start the search from.
-.Performing an anonymous search
+.Perform an anonymous search
====
[source,shell]
----
** `netcat -vz -w3 ldap.example.com 636` will return `succeeded` when there is no
firewall blocking access.
-== Failure - No such object
+== Failure - `No such object`
[source,ldif]
----
<<Failure - Bind required>>). The anonymous user may not have access to content
in the LDAP directory.
-== Failure - Bind required
+== Failure - `Bind required`
```
ldap_bind: Server is unwilling to perform (53)
- `-D <dn>` - The bind DN. A unique identifier for the user being bound.
- `-w <password>` - The bind password.
-.Performing a search with a bound user
+.Perform a search with a bound user
====
[source,shell]
----
----
====
-== Failure - Encryption (confidentiality) required
+== Failure - `Encryption (confidentiality) required`
If a message similar to the one below is returned by `ldapsearch`. TLS must
be enabled on the connection.
is used.
.LDAPS - Retrieving the certificate chain of the fictitious ldap.example.com server
+
====
```
echo -n | openssl s_client -host ldap.example.com -port 636 -prexit -showcerts
.StartTLS - Retrieving the certificate chain of the fictitious ldap.example.com server
====
+
```
echo -n | openssl s_client -host ldap.example.com -port 389 -prexit -showcerts -starttls ldap
CONNECTED(00000003)
MIIHDjCCBPagAwIBAgIJANAO5znieeLNMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYD
...
```
+====
+
[NOTE]
+====
.Availability of `-starttls ldap`
Not all builds of `openssl s_client` support `-starttls ldap`. As of OpenSSL
1.1.1 this feature is still only available in the OpenSSL master branch. See
-this GitHub Pull Request for details:
-https://github.com/openssl/openssl/pull/2293.
+this https://github.com/openssl/openssl/pull/2293[GitHub Pull Request] for details.
====
+
****
// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
-= Mapping and testing with ldapsearch
+= Map and Test with ldapsearch
Every LDAP directory is different. Each directory has different connection parameters,
locations for objects, and attributes within those objects.
the LDAP server. Running `ldapsearch` on a third machine may not reveal these
firewall issues.
-== xref:modules/ldap/ldapsearch/before_starting.adoc[Before starting]
+== xref:modules/ldap/ldapsearch/before_starting.adoc[Prerequisites]
What questions to ask your LDAP administrator before you begin working with the
directory.
-== xref:modules/ldap/ldapsearch/connection_parameters.adoc[Determining connection parameters]
+== xref:modules/ldap/ldapsearch/connection_parameters.adoc[Determine Connection Parameters]
Discover through trial and error, what connection parameters the LDAP
directory requires.
-== xref:modules/ldap/ldapsearch/locating_objects.adoc[Locating objects]
+== xref:modules/ldap/ldapsearch/locating_objects.adoc[Locate objects]
Discover where users and groups are located within the directory.
-== xref:modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc[Using results to configure the LDAP module]
+== xref:modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc[Use Results to Configure the LDAP Module]
Translate LDAP search arguments and the results from previous sections
into LDAP module configuration items.
-= Locating objects
+= Locate Objects
Once the correct xref:modules/ldap/ldapsearch/connection_parameters.adoc[connection parameters]
have been determined, the next step in building your configuration
-= Translating ldapsearch arguments to LDAP configuration items
+= Generate LDAP Configuration Items
[width="100%",cols="30%,20%,50%",options="header",]
|===
```access_positive = 'yes'```
|===
-== Groups - Common
+== Groups - common
[width="100%",cols="30%,70%",options="header",]
|===
-= rlm_mschap
+= MS-CHAP
include::ROOT:partial$v3_warning.adoc[]
These are the ONLY possibilities; MS-CHAP is IMPOSSIBLE if you e.g. only
have the unix/md5/sha crypt of your users password.
-For more info, see:
-
-http://deployingradius.com/documents/protocols/compatibility.html
+See the xref:concepts:protocol/authproto.adoc#Proto-Password-Compat[protocol compatability chart] for more information.
== EAP-MSCHAPv2
You’ll need to fit this to your local needs.
-=== Disabling ntlm_auth for some users
+=== Disable ntlm_auth for some users
You might have some users in the domain, and others in files or SQL that
you want to authenticate locally. To do this, set::
local_cpw = `%exec('/my/script', %{User-Name}, %{MS-CHAP-New-Cleartext-Password})`
```
-WARNING: Wherever possible, you should use `MS-CHAP-New-NT-Password`. The
+[WARNING]
+====
+Wherever possible, you should use `MS-CHAP-New-NT-Password`. The
reason is that cleartext passwords have undergone unicode transformation
from the client encoding (utf-16) to the server encoding (utf-8) and the
current code does this in a very ad-hoc way. The reverse transformation
is also not done - when the server reads Password.Cleartext out of
files/database, it assumes US-ASCII and thus international characters
will fail.
+====
N.B. this could be fixed, if we wanted to pull in something like iconv.
-= PAM Support for FreeRadius
+= PAM
PAM support was done by Jeph Blaize. Miguel a.l. Paraz
mailto:map@iphil.net[map@iphil.net] ported it to FreeRADIUS’
-= rlm_passwd
+= PASSWD
Passwd-like files authorization module.
= Python
-== Introduction
-
FreeRADIUS can call Python scripts in order to utilize third party libraries
which are only available in Python, or to execute particularly complex
policy.
The Python `instantiation` function can return -1 to signal failure and abort
startup.
-== `freeradius` Python module
+== Python module
FreeRADIUS provides a module, `freeradius`, which can be used by any
Python scripts used by `rlm_python`.
-= Bootstrap NGINX
+= Install and Configure NGINX
NGINX itself should be installed from packages provided with your OS.
include::howto:partial$pre_test.adoc[]
-== Editing mods-available/rest
+== Edit mods-available/rest
[source,config]
----
<1> A common URL prefix for all REST API endpoints called by this module instance.
Connect URI is used to reduce repetition in the config.
-== Enabling mods-available/rest
+== Enable mods-available/rest
The `rest` module is enabled by creating a soft link from the
`mods-enabled/` directory to the `mods-available/` directory.
= REST
-== Introduction
FreeRADIUS can be used to communicate with REST APIs.
If you're attempting to integrate an existing REST API, this section will provide
hints on how to accomplish this.
+== Sections in this Guide
+
+== xref:modules/rest/bootstrap_nginx.adoc[Install and Configure NGINX]
+
+== xref:modules/rest/configuration.adoc[Base Configuration]
+
// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Periodic Data Usage Reporting
+= Data Usage Reporting
== Introduction
caveat that _it is not possible to retrospectively determine in which time
period data was consumed for any session that spans multiple time periods_.
-CAUTION: There exists several guides for configuring FreeRADIUS to report
+[CAUTION]
+====
+There exists several guides for configuring FreeRADIUS to report
periodic data usage by users. These typically amend the standard queries to
write potentially large amounts of additional accounting data, or artificially
limit the lifetime of sessions by splitting them so that the start of each
does not extend significantly beyond the end of the same interval. This places
unnecessary load on both the RADIUS and database servers and may inconvenience
a network’s users. There is usually no need to do either of these things.
+====
FreeRADIUS provides a schema extension that implements a recommended approach
suitable for most circumstances, which we describe here.
-
== Requirements
FreeRADIUS only knows the data consumed during each session if the NAS reports
so, either through its static configuration or by returning an
`Acct-Interim-Interval` RADIUS attribute in authentication response.
-NOTE: If you cannot enable the generation of interim-update packets yet
+[NOTE]
+====
+If you cannot enable the generation of interim-update packets yet
still require reasonably accurate data usage reporting then you may have no
choice but to set a `Session-Timeout` RADIUS attribute dynamically to cause the
NAS to terminate long-running sessions and report their final data usage close
while other are still being disconnected. Either approach to terminating
existing sessions will of course result in an interruption of connectivity for
users.
-
+====
== Solution
that is equal to the number of users whose sessions were active within the
current accounting period. It therefore makes efficient use of storage.
-TIP: The update process does not have to be called at regular intervals but in
+[TIP]
+====
+ The update process does not have to be called at regular intervals but in
production is likely to be invoked either as a cronjob or using the database
server’s event scheduler. It can be safely manually invoked (for debugging or
ad hoc reporting purposes) as often as necessary outside of the normal schedule
without impacting normal usage reporting.
+====
For reporting purposes, the ad hoc periods within the `data_usage_by_period`
table can be efficiently aggregated to provide data bucketed into the required
mysql radius < /etc/raddb/mods-config/sql/main/mysql/process-radacct.sql
----
-NOTE: The above command assumes that passwordless login has been configured via
+[NOTE]
+====
+The above command assumes that passwordless login has been configured via
the user's `~/.my.cnf` file, or otherwise. This command and subsequent commands
should be adjusted accordingly where this is not the case.
+====
Call the update process manually to create the initial accounting period for
the historical data usage and start of the next period for future use:
usage data to be reported for any interval that is some multiple of a day, yet
no more often.
-CAUTION: If storage requirements and resources allow then the frequency with
+[CAUTION]
+====
+If storage requirements and resources allow then the frequency with
which the `radacct` table is processed could be increased to hourly or even
more often. However database _partitioning_ should be considered for
performance reasons if this would result in an enormous number of rows in the
`data_usage_by_period` table.
+====
Next, enable daily processing of the `radacct` table by adding something like
the following into the database user’s crontab:
| 2020-January | 5.436280540000 | 49.067775280000 |
+----------------+----------------+-----------------+
-TIP: To obtain the overall data usage for all users the restriction on
+[TIP]
+====
+To obtain the overall data usage for all users the restriction on
`username='bob'` can be dropped from the `WHERE` condition.
-
-TIP: The `process-radacct.sql` files contain example queries for reporting
+====
+[TIP]
+====
+The `process-radacct.sql` files contain example queries for reporting
per-user data usage per month for the respective database flavour.
+====
================================================================================================
-NOTE: This example setup procedure will differ between databases but the steps
+[NOTE]
+====
+This example setup procedure will differ between databases but the steps
will be substantially similar.
+====
== Summary
= SQL Module
-== Introduction
-
The SQL module is composed of two parts: a generic SQL front-end
(rlm_sql), and a series of database-dependent back-end drivers,
(rlm_sql_mysql, rlm_sql_postgresql, etc.)
=== Example with groups
-For any fairly complex setup, it is likely that most of the actual
+For any complex setup, it is likely that most of the actual
processing will be done using groups. In these cases, the user entries
in radcheck and radreply will be of limited use except for things like
setting user-specific attributes such as the user’s password. So, one
^ ATTRIBUTE ^ ^ OP ^ ^ VALUE ^
----
-If you want the server to be completely misconfigured, and to never do
-what you want, leave the `op' field blank. If you want to be rudely told
-to RTFM, then post questions on the mailing list, asking
-
_Why doesn’t my SQL configuration work when I leave the `op` field
-empty?_
+empty?
-The short answer is that with the op field empty, the server does not
-know what you want it to do with the attribute.
+If leave the `op' field blank, the server is misconfigured, and unpreditable behaviour occurs. Read this documentation thoroughly before you post questions on the mailing list.
+
+If the op field is empty, the server does not know what you want it to do with the attribute.
* Is it a check item that should be compared against the request?
* Should it be added to the control or reply list?
value in the field. The value is the string form of the operator: "=",
">=", etc. See below for more details.
-
== Authentication versus Authorization
Many people ask if they can "authenticate" users to their SQL
-= ODBC Driver (rlm_sql_unixodbc)
+= ODBC
FreeRADIUS supports connections to ODBC data sources by interfacing with the
-unixODBC framework together with a backend driver.
+unixODBC framework together with a backend driver (rlm_sql_unixodbc).
-TIP: Where FreeRADIUS provides a specific SQL driver for a particular database
+[TIP]
+====
+Where FreeRADIUS provides a specific SQL driver for a particular database
server, using the specific driver is usually preferable since less indirection
often leads to better performance and stability. Nevertheless, you may have a
reason to use ODBC.
+====
ODBC is a library specification for accessing multiple data sources using a
common API. FreeRADIUS uses the unixODBC implementation of ODBC and the data
property to one of the entries in `odbcinst.ini`, unless the driver's library
is specified directly in `odbc.ini`.
-TIP: The locations of the various ODBC configuration files can be determined
+[TIP]
+====
+The locations of the various ODBC configuration files can be determined
from the output of running `odbcinst -j`.
+====
-Configuring FreeRADIUS to connect to a data source using ODBC requires the
+Configure FreeRADIUS to connect to a data source using ODBC requires the
following steps:
-. Test connectivity directly using a native database client, if possible
-. Install a backend database driver for ODBC
-. Register the backend driver
-. Configure a DSN for the data source
-. Test the ODBC connection using the DSN
-. Configure an instance of the `rlm_sql` module to use the `rlm_sql_unixodbc`
- driver to connect to the DSN
-. Test FreeRADIUS connectivity in debug mode (`-X`)
-
-NOTE: Not all errors arising from ODBC issues are reported to FreeRADIUS in a
+. Test connectivity directly using a native database client, if possible.
+. Install a backend database driver for ODBC.
+. Register the backend driver.
+. Configure a DSN for the data source.
+. Test the ODBC connection using the DSN.
+. Configure an instance of the `rlm_sql` module to use the `rlm_sql_unixodbc`.
+ driver to connect to the DSN.
+. Test FreeRADIUS connectivity in debug mode (`-X`).
+
+[NOTE]
+====
+Not all errors arising from ODBC issues are reported to FreeRADIUS in a
meaningful way. In the event that you have ODBC-related problems connecting the
a data source you should first consult the documentation for unixODBC (or ODBC
generally) and/or backend driver. For some issues you should consider
enabling ODBC tracing as described later in this document.
-
+====
== Worked example: FreeRADIUS with MS SQL Server over ODBC
FreeRADIUS packages that include the `rlm_unixodbc` module then these may also
work, however they are likely to be out of date.
-Follow the instructions for installing the Network RADIUS repository:
-https://networkradius.com/freeradius-packages/
+Follow the https://packages.inkbridgenetworks.com/[instructions] for installing the FreeRADIUS repository:
-Follow the instructions for installing the Microsoft MSSQL-Release repository
-for RHEL/CentOS 7 from here:
-https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server?view=sql-server-ver15#redhat17
+Follow the https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server?view=sql-server-ver15#redhat17[RHEL/CentOS 7 instructions] for installing the Microsoft MSSQL-Release repository.
The specific step that is required is as follows, but the remainder of the
instructions are worth reviewing:
.Example of deploying a schema and application-specific user via CLI
================================================================================================
-Configuring a production MS SQL Server to permit the required access and
+Configure a production MS SQL Server to permit the required access and
deploying a database is beyond the scope of this document, however if the
FreeRADIUS schema and user do not already exist and the server is accessible
with a database administrator account (e.g. `sa`) then the schema and user can
================================================================================================
-WARNING: Do not proceed until the above non-ODBC test is known to work using
+[WARNING]
+====
+ Do not proceed until the above non-ODBC test is known to work using
the database and credentials that will be used by FreeRADIUS.
-
+====
=== Install the ODBC backend driver
dnf install msodbcsql17 unixodbc
----
-
=== Register the driver
The Microsoft ODBC Driver for SQL Server package will normally register itself
...
----
-NOTE: The config section name in `[square brackets]` is the ODBC name of the
+[NOTE]
+====
+The config section name in `[square brackets]` is the ODBC name of the
database driver. It is an arbitrary name but must be referenced exactly in the
DSN definitions within `/etc/odbc.ini`.
+====
You can verify that the ODBC driver definition can be successfully found by
name with:
include a `Database` parameter since this is not indicated by the rlm_sql
configuration.
-NOTE: The config section name in `[square brackets]` is the name of the DSN
+[NOTE]
+====
+The config section name in `[square brackets]` is the name of the DSN
which is the lookup key for the connection. It is an arbitrary name but it
must be referenced identically in connection strings such as in the FreeRADIUS
`rlm_sql` module configuration.
+====
=== Test the ODBC connection
================================================================================================
-WARNING: Do not proceed with testing FreeRADIUS until the above ODBC test is
+[WARNING]
+====
+Do not proceed with testing FreeRADIUS until the above ODBC test is
known to work.
-
+====
=== Configure an instance of rlm_sql to use rlm_sql_unixodbc
================================================================================================
-CAUTION: If ODBC tracing has been enabled during testing then you should
+[CAUTION]
+====
+If ODBC tracing has been enabled during testing then you should
remember to disable this before moving into production.
+====
// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= SQL counter module
+= SQL-Counter
== Introduction
= SQL-IP-Pool
-== Introduction
-
The `sqlippool` module allocates IP addresses from one or more pools
of addresses. It tracks addresses to that it does not issue the same
leased IP address to multiple devices.
generate_pool_addresses.pl ... | align_sql_pools.pl postgresql
----
-Once the IP addresses have been generated,
+Once the IP addresses have been generated, decide how you want to orgaise your pools within a range or multiple ranges. Properly defining these ranges ensure efficient distribution of IP addresses to end-users and devices on the network.
== Use with a single address range
-= Testing the Basic Setup
+= Basic Setup Tests
Start by creating some text files holding the test request data based on the
actual form of the contents of packets originating from the NAS.
-= Optimization
+= Optimisation
Once the FreeRADIUS server is successfully installed, optimizing your eco-system, particularly your FreeRADIUS server, becomes a top priority. A well-tuned server is critical for ensuring high performance, robust security, and reliability. These factors are especially important in environments with many users or high authentication traffic. This process involves tuning various components such as datastore performance, network connections, and server resources.
It can be challenging to identify issues or what component needs adjusting. To start, you need to gather statistics through monitoring to identify the bottlenecks in your system. This important activity allows you to determine the most critical areas for improvement.
-== Why optimize?
+== Why optimise?
A poorly optimized FreeRADIUS server can lead to slow authentication times, timeouts, and even system instability. Enhance your FreeRADIUS server’s performance, reliability, and resource efficiency to enhance the user experience while maintaining a secure environment.
Optimizing resource usage (CPU, memory, disk I/O) allows you to run FreeRADIUS effectively even on limited hardware. If FreeRADIUS is integrated with a datastore, implementing well-structured querires prevents bottlenecks.
-The optimization section is organized by the following topic areas:
+== Sections in this guide
-== xref:optimization/auditing.adoc[Auditing]
+=== xref:optimization/auditing.adoc[Auditing]
Auditing provides valuable insights into user behavior, policy enforcement, and potential security risks. Auditing is the basis of robust network security and management processes.
-== xref:optimization/monitoring/index.adoc[Monitoring]
+=== xref:optimization/monitoring/index.adoc[Monitoring]
Monitoring the FreeRADUS server and network components includes observing the AAA processes and how the overall system is operating. Several logging options help the administrator generate statistics to determine where issues are occurring such as slow connectivity or authentications.
FreeRADIUS is packaged with a xref:optimization/monitoring/statistics.adoc[virtual statistics server] that enables you to select what you want to watch or help find a problem.
-== xref:tuning/performance-testing.adoc[Performance Testing]
+=== xref:tuning/performance-testing.adoc[Performance Testing]
Performance testing helps you figure out what the maximum loads can be without affecting operations. As your network grows, a non-optimized server may struggle to handle the increased authentication and accounting loads, especially during peak hours.
-== xref:optimization/tools/index.adoc[Tools]
+=== xref:optimization/tools/index.adoc[Tools]
FreeRADIUS is packaged with some useful tools such as radsniff and radclient that are used in testing, monitoring, and gathering statistics. These tools give you a top-level view of the health of your server, clients, and processess.
-== xref:tuning/tuning_guide.adoc[Tuning Guide]
+=== xref:tuning/tuning_guide.adoc[Tuning Guide]
Tuning the FreeRADIUS server and relevant components ensures optimal performance across the network.
- Running `certbot` to issue the certificate.
-- Configuring FreeRADIUS to use the LetsEncrypt issued certificate
+- Configure FreeRADIUS to use the LetsEncrypt issued certificate
and associated private key.
This document is based on a Debian system (version 12 at the time
-== Configuring FreeRADIUS as a RadSec test client
+== Configure FreeRADIUS as a RadSec test client
Unfortunately, the `radclient` program does not support RadSec. We
must therefore configure an instance of FreeRADIUS as a "transport
This guide is organised into four parts that should be read in order:
1. xref:protocols/radius/enable_radsec.adoc[Enabling RadSec]
-2. xref:protocols/radius/radsec_client.adoc[Configuring a test RadSec client]
+2. xref:protocols/radius/radsec_client.adoc[Configure a test RadSec client]
3. xref:protocols/radius/radsec_with_haproxy.adoc[Proxying RadSec with HAproxy]
4. xref:protocols/radius/radsec_with_traefik.adoc[Proxying RadSec with Traefik]
5. xref:protocols/radius/enable_proxy_protocol.adoc[Enabling PROXY Protocol for RadSec]
There may be packages available for other systems, else you'll need to build the libraries from source, satisfying their dependencies manually.
-### Configuring
+### Configure
If you wish to build a standalone binary of radsniff, you need to pass ``--with-shared-libs=no`` to the configure script, this disabled building with share libraries.
```text
-l 0 --vertical-label "PPS"
-DEF:received=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_count-<packet type>.rrd:received:AVERAGE
-DEF:linked=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_count-<packet type>.rrd:linked:AVERAGE
-DEF:unlinked=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_count-<packet type>.rrd:unlinked:AVERAGE
+DEF:received=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_count-<packet type>.rrd:received:AVERAGE
+DEF:linked=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_count-<packet type>.rrd:linked:AVERAGE
+DEF:unlinked=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_count-<packet type>.rrd:unlinked:AVERAGE
DEF:reused=/var/lib/collectd/rrd/<host>/<instance>exchanged/radius_count-<packet type>.rrd:reused:AVERAGE
AREA:received#DD44CC:received
AREA:linked#66BBCC:linked
```text
-l 0 --vertical-label "Requests completed per second"
-DEF:none=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:none:AVERAGE
-DEF:1=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:1:AVERAGE
-DEF:2=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:2:AVERAGE
+DEF:none=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:none:AVERAGE
+DEF:1=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:1:AVERAGE
+DEF:2=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:2:AVERAGE
DEF:3=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:3:AVERAGE
DEF:4=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:4:AVERAGE
DEF:more=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:more:AVERAGE
-DEF:lost=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:lost:AVERAGE
+DEF:lost=/var/lib/collectd/rrd/<host>/<instance>-exchanged/radius_rtx-<packet type>.rrd:lost:AVERAGE
AREA:none#2AD400:none
STACK:1#4DB000:1
STACK:2#718D00:2
To monitor multiple packet types create additional symlinks to the radsniff plugin, and alter ``env.pkt_type``. If running multiple instances of radsniff you should also set ``env.instance`` to the ``<instance name>`` used above.
-If collectd is aggregating stats from multiple hosts you'll also need to set ``env.host``.
+If collectd is aggregating stats from multiple hosts you'll also need to set ``env.host``.
### Caveats
# authenticate users against twitter. It is purely for integration with
# the API.
#
-# Note: Unless you're using twitter as part of an authorisation scheme, you should
+# Note: Unless you're using twitter as part of an authorization scheme, you should
# use a detail reader/writer pair to provide a buffer in case the twitter
# API becomes unavailable/unreachable. You don't want authentication to be
# delayed while waiting for a twitter API request to time out.
This will let a user (called _youruser_) in for the first level of access to your Cisco. You still need to **enable** to perform any configuration changes or anything requiring a higher level of access.
-See Configuring Basic AAA on a http://www.cisco.com/en/US/tech/tk59/technologies_tech_note09186a0080093c81.shtml[Cisco Access Server] for more details.
+See Configure Basic AAA on a http://www.cisco.com/en/US/tech/tk59/technologies_tech_note09186a0080093c81.shtml[Cisco Access Server] for more details.
## Enable Mode
exit
```
-## RFC 3576 Change of Authorisation & Disconnect Message
+## RFC 3576 Change of Authorization & Disconnect Message
RFC3576 operation is currently supported on all K and W branch switches. It is considered to be a 'premium' feature, so is unlikely to be backported, or included in lower end switch models.
A RADIUS request with a Code of either 40 (Disconnect Request) or 43 (CoA Request) is sent to UDP port 3799 (default) on the switch.
-This request must include attributes that identify the NAS, attributes that identify the session, and in the case of CoA, attributes that form the new authorisation profile.
+This request must include attributes that identify the NAS, attributes that identify the session, and in the case of CoA, attributes that form the new authorization profile.
RFC 3576 also recommends that an Event-Timestamp attribute be present for replay protection purposes, and that there be a maximum (default) delta of 300 seconds between the NAS time and the Event-Timestamp attribute included in the request.
_Note: HP switches will silently discard any CoA or DM requests that do not have a valid Event-Timestamp attribute, this behaviour may be disabled on a server by server basis (see below for example)._
|NAS-IP-Address |1 |Source IP for RADIUS requests (sent from the switch) |- |``<ip-address>``
|===
-### Authorisation attributes
+### Authorization attributes
-At least one of these attribute/attribute sets must be present in the CoA request else the NAS will return a CoA-NAK (Missing-Attribute). No authorisation attributes must be included in the disconnect message else the NAS will return a DM-NAK (Unsupported-Attribute).
+At least one of these attribute/attribute sets must be present in the CoA request else the NAS will return a CoA-NAK (Missing-Attribute). No authorization attributes must be included in the disconnect message else the NAS will return a DM-NAK (Unsupported-Attribute).
|===
|RADIUS Attribute |Times Used|Description
!
```
-Freeradius server-side is set up normally like:
+Freeradius server-side is set up normally like:
**Server-side setup:**
```text
client <network_device_management_ip> {
-* xref:howto:installation/index.adoc[Installing and Upgrading]
+* xref:howto:installation/index.adoc[Install and Upgrade]
** xref:howto:installation/dependencies.adoc[Dependencies]
** xref:howto:installation/source.adoc[Build and Install from Source]
*** Building Packages
**** xref:howto:installation/debian.adoc[Debian and Ubuntu]
**** xref:howto:installation/redhat.adoc[RedHat and CentOS]
** xref:howto:installation/packages.adoc[Install from packages]
-** xref:howto:installation/upgrade.adoc[Upgrading from v3 to v4]
+** xref:howto:installation/upgrade.adoc[Upgrade from v3 to v4]
*** xref:howto:installation/attribute_names.adoc[Attribute Name Changes from v3 to v4]
*** xref:dictionary/begin-vendor.adoc[BEGIN-VENDOR]
*** xref:dictionary/end-vendor.adoc[END-VENDOR]
-** xref:policy/index.adoc[Writing Policy Rules]
+** xref:policy/index.adoc[Create Policy Rules]
*** xref:policy/different.adoc[Why FreeRADIUS is different]
** xref:man/index.adoc["man" pages]
projects / thirdparty / freeradius-server.git / commitdiff
