From: nolade Date: Tue, 15 Jul 2025 19:21:52 +0000 (-0400) Subject: docs-v4: update top-level and sub-section landing pages HIVE 4114/8. Added xrefs... X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d0e2c62a0a497c36f543583d702ee75b464f9b16;p=thirdparty%2Ffreeradius-server.git docs-v4: update top-level and sub-section landing pages HIVE 4114/8. Added xrefs, rewrote some intros. --- diff --git a/doc/antora/modules/howto/nav.adoc b/doc/antora/modules/howto/nav.adoc index 57f3c3c520..764a391a9b 100644 --- a/doc/antora/modules/howto/nav.adoc +++ b/doc/antora/modules/howto/nav.adoc @@ -14,29 +14,29 @@ *** 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] @@ -44,7 +44,7 @@ *** 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] @@ -54,17 +54,16 @@ *** 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] @@ -84,7 +83,7 @@ *** 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] @@ -96,7 +95,7 @@ *** 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] diff --git a/doc/antora/modules/howto/pages/datastores/ad/index.adoc b/doc/antora/modules/howto/pages/datastores/ad/index.adoc index f306e10d18..1274618fc8 100644 --- a/doc/antora/modules/howto/pages/datastores/ad/index.adoc +++ b/doc/antora/modules/howto/pages/datastores/ad/index.adoc @@ -4,8 +4,8 @@ Microsoft Active Directory (AD) is a directory service that stores and manages u 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? @@ -13,7 +13,7 @@ When FreeRADIUS is integrated with Active Directory, the AD server functions as 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: @@ -64,9 +64,9 @@ winbind_domain = "%{mschap:NT-Domain}"} ``` -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: @@ -92,12 +92,8 @@ Without the "--allow-mschapv2" setting, you would see "passwordType":"NTLMv1" 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] diff --git a/doc/antora/modules/howto/pages/datastores/ad/join.adoc b/doc/antora/modules/howto/pages/datastores/ad/join.adoc index 958a0b94ef..077abf4b82 100644 --- a/doc/antora/modules/howto/pages/datastores/ad/join.adoc +++ b/doc/antora/modules/howto/pages/datastores/ad/join.adoc @@ -1,6 +1,6 @@ = 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 diff --git a/doc/antora/modules/howto/pages/datastores/ad/ntlm_mschap.adoc b/doc/antora/modules/howto/pages/datastores/ad/ntlm_mschap.adoc index cf66215fb3..aa0bd4262d 100644 --- a/doc/antora/modules/howto/pages/datastores/ad/ntlm_mschap.adoc +++ b/doc/antora/modules/howto/pages/datastores/ad/ntlm_mschap.adoc @@ -1,4 +1,4 @@ -= 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. @@ -22,7 +22,7 @@ authenticate { } ``` -== 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`. @@ -49,9 +49,9 @@ 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 +== 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. ``` diff --git a/doc/antora/modules/howto/pages/datastores/ad/samba.adoc b/doc/antora/modules/howto/pages/datastores/ad/samba.adoc index 213d83dac3..b787a149ab 100644 --- a/doc/antora/modules/howto/pages/datastores/ad/samba.adoc +++ b/doc/antora/modules/howto/pages/datastores/ad/samba.adoc @@ -1,89 +1,117 @@ -== 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. diff --git a/doc/antora/modules/howto/pages/datastores/ad/winbind.adoc b/doc/antora/modules/howto/pages/datastores/ad/winbind.adoc index 86e45c2fca..337ab9352f 100644 --- a/doc/antora/modules/howto/pages/datastores/ad/winbind.adoc +++ b/doc/antora/modules/howto/pages/datastores/ad/winbind.adoc @@ -1,16 +1,18 @@ -= 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` diff --git a/doc/antora/modules/howto/pages/datastores/index.adoc b/doc/antora/modules/howto/pages/datastores/index.adoc index ea8dc9015e..c76307eda4 100644 --- a/doc/antora/modules/howto/pages/datastores/index.adoc +++ b/doc/antora/modules/howto/pages/datastores/index.adoc @@ -1,13 +1,13 @@ -= 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: @@ -16,11 +16,22 @@ To set up a datastore, you'll need to install the software, configure the data s * 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] diff --git a/doc/antora/modules/howto/pages/eduroam_logging.adoc b/doc/antora/modules/howto/pages/eduroam_logging.adoc index e448b66b6f..2f0a6bd1c8 100644 --- a/doc/antora/modules/howto/pages/eduroam_logging.adoc +++ b/doc/antora/modules/howto/pages/eduroam_logging.adoc @@ -116,7 +116,7 @@ log the reply with the required attributes. } -## 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 diff --git a/doc/antora/modules/howto/pages/index.adoc b/doc/antora/modules/howto/pages/index.adoc index fb89ab8472..16ed971d41 100644 --- a/doc/antora/modules/howto/pages/index.adoc +++ b/doc/antora/modules/howto/pages/index.adoc @@ -5,22 +5,16 @@ FreeRADIUS. Each sub-section provides worked examples such as using the modules 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] diff --git a/doc/antora/modules/howto/pages/installation/attribute_names.adoc b/doc/antora/modules/howto/pages/installation/attribute_names.adoc index 84b94a9809..da01b1dba7 100644 --- a/doc/antora/modules/howto/pages/installation/attribute_names.adoc +++ b/doc/antora/modules/howto/pages/installation/attribute_names.adoc @@ -1,4 +1,4 @@ -= 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 @@ -38,8 +38,7 @@ ATTRIBUTE AVPair 1 string ... ``` - -== 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. diff --git a/doc/antora/modules/howto/pages/installation/debian.adoc b/doc/antora/modules/howto/pages/installation/debian.adoc index ac0be7da38..598f37a517 100644 --- a/doc/antora/modules/howto/pages/installation/debian.adoc +++ b/doc/antora/modules/howto/pages/installation/debian.adoc @@ -1,9 +1,11 @@ -= 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. @@ -50,7 +52,7 @@ Suggested is to stop the service and until all is working use freeradius in debu 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. @@ -146,15 +148,15 @@ sudo dpkg -i *freeradius*_W.X.Y*_*.deb 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 @@ -169,7 +171,7 @@ fakeroot debian/rules clean 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: @@ -181,7 +183,7 @@ This will build packages in the parent directory, which can be installed with `` 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`). @@ -192,21 +194,21 @@ make 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: diff --git a/doc/antora/modules/howto/pages/installation/index.adoc b/doc/antora/modules/howto/pages/installation/index.adoc index 0fb5c2073f..6e77fa22c2 100644 --- a/doc/antora/modules/howto/pages/installation/index.adoc +++ b/doc/antora/modules/howto/pages/installation/index.adoc @@ -1,4 +1,4 @@ -= Installing and Upgrading += Install and Upgrade FreeRADIUS is available from many locations. Select one of the options below to begin installing your server: @@ -15,13 +15,11 @@ The documents in this section cover details of the above 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 @@ -48,7 +46,7 @@ located in `/etc/freeradius/` instead of `/etc/raddb/`. The terms `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 @@ -71,7 +69,7 @@ a lot of text, it describes exactly what is happening within the server 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[] @@ -83,20 +81,20 @@ The output from `radiusd -X` is very verbose, see the xref:ROOT:debugging/radius 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[] diff --git a/doc/antora/modules/howto/pages/installation/osx.adoc b/doc/antora/modules/howto/pages/installation/osx.adoc index 6a155bf3b8..7812cbc2a9 100644 --- a/doc/antora/modules/howto/pages/installation/osx.adoc +++ b/doc/antora/modules/howto/pages/installation/osx.adoc @@ -1,8 +1,8 @@ -= 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 @@ -11,11 +11,11 @@ Install the https://brew.sh[Homebrew] package manager to streamline the installa ```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. @@ -35,12 +35,12 @@ cat scripts/osx/bash_profile >> ~/.zshrc 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: @@ -50,7 +50,7 @@ cd freeradius-server 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. diff --git a/doc/antora/modules/howto/pages/installation/packages.adoc b/doc/antora/modules/howto/pages/installation/packages.adoc index a337678814..3550e19b6e 100644 --- a/doc/antora/modules/howto/pages/installation/packages.adoc +++ b/doc/antora/modules/howto/pages/installation/packages.adoc @@ -1,4 +1,4 @@ -== Install from packages += Install from Packages include::ROOT:partial$v3_warning.adoc[] @@ -16,7 +16,7 @@ The current packages available include: * 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. diff --git a/doc/antora/modules/howto/pages/installation/redhat.adoc b/doc/antora/modules/howto/pages/installation/redhat.adoc index 2026727241..0236ae23ae 100644 --- a/doc/antora/modules/howto/pages/installation/redhat.adoc +++ b/doc/antora/modules/howto/pages/installation/redhat.adoc @@ -1,13 +1,13 @@ -= 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 @@ -29,7 +29,7 @@ yum -y install cmake3 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. @@ -55,11 +55,11 @@ Or can set ``CC=/opt/rh/devtoolset-3/root/usr/bin/gcc`` in your environment, whi 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. @@ -69,7 +69,7 @@ make sudo make install ---- -== Building Packages +== Build packages === With Oracle support diff --git a/doc/antora/modules/howto/pages/installation/source.adoc b/doc/antora/modules/howto/pages/installation/source.adoc index 555f7a6c59..de178b5f92 100644 --- a/doc/antora/modules/howto/pages/installation/source.adoc +++ b/doc/antora/modules/howto/pages/installation/source.adoc @@ -1,4 +1,4 @@ -== 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. @@ -44,7 +44,7 @@ make 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 @@ -85,7 +85,7 @@ Please do _not_ post questions to the FreeRADIUS users list 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. @@ -104,7 +104,7 @@ major version. The number of differences in the new configuration mean 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 @@ -114,7 +114,7 @@ This is your best hope for understanding the problem. Read _all_ 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 @@ -177,7 +177,7 @@ changes without impacting your active production environment. You should 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. diff --git a/doc/antora/modules/howto/pages/installation/upgrade.adoc b/doc/antora/modules/howto/pages/installation/upgrade.adoc index 17c7813302..8a7f558ecf 100644 --- a/doc/antora/modules/howto/pages/installation/upgrade.adoc +++ b/doc/antora/modules/howto/pages/installation/upgrade.adoc @@ -20,15 +20,15 @@ In general, we have the following changes: `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 @@ -51,7 +51,7 @@ information. This change was necessary in order to support the new protocols. -== Attribute Names +== Attribute names Much of the information in this section is also in the `raddb/dictionary` file @@ -132,7 +132,7 @@ subsection there. See also xref:reference:raddb/templates.conf.adoc[`templates.c 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 @@ -158,7 +158,7 @@ redundant redundant_sql { 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: @@ -187,7 +187,7 @@ Every example virtual server in the `sites-enabled/` directory 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` @@ -270,7 +270,7 @@ each client. e.g._by keying off of the `NAS-Identifier` attribute. 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. @@ -311,15 +311,15 @@ in `accounting %{Acct-Status-Type}`. See sites-available/default for 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 <> 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 @@ -388,8 +388,11 @@ redundant { } ---- -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` @@ -439,7 +442,7 @@ While the `Load-Balance-Key` was a special attribute in v3, it has no 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: @@ -666,7 +669,7 @@ Some modules such as rlm_sql_postgresql can have their timeout set via 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. @@ -743,7 +746,7 @@ xref:reference:xlat/index.adoc[xlat] expansions have been changed from syntax li `%{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. @@ -776,7 +779,7 @@ retransmitted proxied packets only when it received a retransmission 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. @@ -975,7 +978,7 @@ if (%sql.group(sales)) { 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. @@ -1008,7 +1011,7 @@ send { } ``` -==== Profiles +=== Profiles The `default_user_profile` has been removed. No one used it, as that behavior was already supported by the group functionality. See @@ -1020,7 +1023,7 @@ Now calls `mysql_real_escape_string` and no longer produces `=` 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 `=` escape sequences in expanded values. The @@ -1108,7 +1111,7 @@ will no longer work. The `winbind` module uses an expansion `%winbind.group()` instead of `Winbind-Group == `. -== Deleted Modules +== Deleted modules The following modules have been deleted @@ -1159,7 +1162,7 @@ if (%time() < (date) 'Aug 1 2023 01:02:03 UTC') { } ``` -== Deleted Functionality +== Deleted functionality Many "virtual" or "fake" attributes have been removed or renamed. @@ -1179,7 +1182,7 @@ 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: diff --git a/doc/antora/modules/howto/pages/modules/chap/index.adoc b/doc/antora/modules/howto/pages/modules/chap/index.adoc index 29b26f21db..dc91e551a9 100644 --- a/doc/antora/modules/howto/pages/modules/chap/index.adoc +++ b/doc/antora/modules/howto/pages/modules/chap/index.adoc @@ -1,20 +1,20 @@ :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. @@ -27,11 +27,11 @@ cd raddb/mods-enabled && ln -s ../mods-available/chap 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: @@ -49,9 +49,12 @@ The `radclient` program is smart enough to see that the 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. @@ -119,7 +122,7 @@ etc. The `chap` module only needs to know that it handles CHAP, and 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 diff --git a/doc/antora/modules/howto/pages/modules/configuring_modules.adoc b/doc/antora/modules/howto/pages/modules/configuring_modules.adoc index a95c3cb8e2..1969367466 100644 --- a/doc/antora/modules/howto/pages/modules/configuring_modules.adoc +++ b/doc/antora/modules/howto/pages/modules/configuring_modules.adoc @@ -26,14 +26,14 @@ and all errors before proceeding to the next step. It is a good idea 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. @@ -51,7 +51,7 @@ This process leaves the original `mods-available/MODULE` configuration 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: diff --git a/doc/antora/modules/howto/pages/modules/eap/index.adoc b/doc/antora/modules/howto/pages/modules/eap/index.adoc index dc52dc8e98..ecbbc0ff70 100644 --- a/doc/antora/modules/howto/pages/modules/eap/index.adoc +++ b/doc/antora/modules/howto/pages/modules/eap/index.adoc @@ -1,10 +1,8 @@ -= 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 @@ -84,7 +82,7 @@ The Implementation of EAP over RADIUS is based on the following RFCs 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 @@ -133,10 +131,13 @@ modules { } ---- -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 @@ -181,7 +182,7 @@ The attributes are: NOTE: `EAP-SIM` will send WEP attributes to the resquestor. -== EAP Sub-Types +== EAP sub-types === LEAP @@ -247,7 +248,10 @@ Even though Microsoft (along with RSA and Cisco) co-invented the PEAP standard, 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. @@ -267,7 +271,7 @@ EAP-FAST is defined in IETF RFC 4851. Note that this is an Informational RFC. *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/ @@ -277,7 +281,7 @@ An Open Source audit tool is available at: https://github.com/ANSSI-FR/audit-radius -== FAQ and Examples +== FAQ and examples How do i use it? @@ -329,7 +333,7 @@ In radiusd.conf ... } - # ldap gets the Configured password. + # ldap gets the configured password. # eap sets the authenticate type as EAP recv Access-Request { ... diff --git a/doc/antora/modules/howto/pages/modules/krb5/index.adoc b/doc/antora/modules/howto/pages/modules/krb5/index.adoc index 46f28de6c9..fbb4e44fe9 100644 --- a/doc/antora/modules/howto/pages/modules/krb5/index.adoc +++ b/doc/antora/modules/howto/pages/modules/krb5/index.adoc @@ -1,4 +1,4 @@ -= Kerberos 5 (krb5) += KRB5 The `rlm_krb5` FreeRADIUS module enables the use of Kerberos 5 for authentication. diff --git a/doc/antora/modules/howto/pages/modules/ldap/accounting.adoc b/doc/antora/modules/howto/pages/modules/ldap/accounting.adoc index 1ca8d50024..45b8cd09b3 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/accounting.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/accounting.adoc @@ -1,4 +1,4 @@ -= 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. diff --git a/doc/antora/modules/howto/pages/modules/ldap/authentication.adoc b/doc/antora/modules/howto/pages/modules/ldap/authentication.adoc index 702cfb3acf..f3f94f8f60 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authentication.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authentication.adoc @@ -1,4 +1,4 @@ -= Configuring Authentication += Configure Authentication == Testing diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization/groups.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization/groups.adoc index 2b2b6e72a2..675fd02e7e 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization/groups.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization/groups.adoc @@ -15,9 +15,9 @@ referencing: - _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] ---- @@ -42,7 +42,7 @@ ldap { <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] ---- @@ -67,7 +67,7 @@ ldap { <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] ---- @@ -92,7 +92,7 @@ ldap { <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] ---- diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization/index.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization/index.adoc index 940243c91a..6c65683f48 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization/index.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization/index.adoc @@ -1,4 +1,4 @@ -= Configuring Authorization += Configure Authorization The `authorize` method of the LDAP module is responsible for locating the authenticating user's LDAP object. @@ -10,7 +10,7 @@ You should complete the xref:modules/ldap/base_configuration/index.adoc[base con 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 @@ -19,7 +19,7 @@ user in the directory. 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. @@ -30,7 +30,7 @@ the LDAP module will reject the authentication attempt. 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. diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization/locating_the_user.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization/locating_the_user.adoc index 2fda20bd54..88fe796e85 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization/locating_the_user.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization/locating_the_user.adoc @@ -10,7 +10,7 @@ explaining how the different configuration items are used. See 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] ---- diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization/user_account_controls.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization/user_account_controls.adoc index 1aefda1f6e..c6a21371f0 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization/user_account_controls.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization/user_account_controls.adoc @@ -1,4 +1,4 @@ -= Controlling user accounts += Control User Accounts In some instances it may be useful to "lock out" user accounts. @@ -35,7 +35,7 @@ is enabled, or disabled, depending on the value of `user.access_positive`. 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] ---- @@ -52,7 +52,7 @@ ldap { 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] ---- diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization/user_disambiguation.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization/user_disambiguation.adoc index 568e058104..b36edf40a3 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization/user_disambiguation.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization/user_disambiguation.adoc @@ -1,4 +1,4 @@ -= Disambiguating user objects += Disambiguate User Objects In some instances a user may have objects located in multiple areas of the LDAP directory. @@ -29,7 +29,7 @@ As the error message states, there are multiple ways to resolve this issue: 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]. @@ -44,7 +44,7 @@ Without SSS which object is used by the LDAP module will be essentially random. [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. @@ -60,7 +60,7 @@ EOF ---- ==== -== Editing mods-available/ldap to enable Server Side Sorting +== Edit mods-available/ldap to enable Server Side Sorting [source,config] ---- diff --git a/doc/antora/modules/howto/pages/modules/ldap/base_configuration/index.adoc b/doc/antora/modules/howto/pages/modules/ldap/base_configuration/index.adoc index 60b0be32ab..4e7cc41fd4 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/base_configuration/index.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/base_configuration/index.adoc @@ -1,4 +1,4 @@ -= 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] @@ -9,7 +9,7 @@ describes the configuration parameters accepted by the module, and what they do. 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 @@ -67,7 +67,7 @@ We do _not_ recommend immediately configuring TLS unless you are testing against 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. @@ -77,7 +77,7 @@ The `ldap` module is enabled by creating a soft link from the 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. @@ -168,7 +168,7 @@ server default { 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[] diff --git a/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/docker.adoc b/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/docker.adoc index d17e20a3b9..ea59d0c78a 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/docker.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/docker.adoc @@ -1,4 +1,6 @@ -= Using OpenLDAP in a docker container += Docker + +This page explains how to configure using OpenLDAP in a docker container. == Bootstrap @@ -81,7 +83,7 @@ In order to make the LDAP database persistent, see the 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. diff --git a/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/index.adoc b/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/index.adoc index ff4a0c1450..5192cc89c0 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/index.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/index.adoc @@ -1,4 +1,4 @@ -= Installing and Configuring OpenLDAP += Install and Configure OpenLDAP This section of the howto describes two methods of creating an OpenLDAP instance for testing purposes. diff --git a/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/packages.adoc b/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/packages.adoc index 1932ba215c..bc286a1654 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/packages.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap/packages.adoc @@ -1,4 +1,4 @@ -= Installing OpenLDAP from packages += Install OpenLDAP from packages == Switch to privileged user diff --git a/doc/antora/modules/howto/pages/modules/ldap/index.adoc b/doc/antora/modules/howto/pages/modules/ldap/index.adoc index 545bc361ae..77173b6480 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/index.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/index.adoc @@ -1,31 +1,25 @@ = 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. @@ -35,51 +29,35 @@ alternatively, if you're using a Debian or RHEL based distribution, using the 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. diff --git a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/before_starting.adoc b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/before_starting.adoc index 0e81cabdd6..a01d4952c0 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/before_starting.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/before_starting.adoc @@ -1,4 +1,4 @@ -= Before starting += Prerequisites Try to determine answers to the following questions: diff --git a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/connection_parameters.adoc b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/connection_parameters.adoc index 696aeef713..330ed0f92a 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/connection_parameters.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/connection_parameters.adoc @@ -1,4 +1,4 @@ -= 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. @@ -29,7 +29,7 @@ you will need to provide the following arguments: - `-H ` - The LDAP server to connect to. - `-b ` - A point in the LDAP tree to start the search from. -.Performing an anonymous search +.Perform an anonymous search ==== [source,shell] ---- @@ -54,7 +54,7 @@ continue indefinitely) when there is _no_ firewall blocking. ** `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] ---- @@ -76,7 +76,7 @@ result: 32 No such object <>). 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) @@ -95,7 +95,7 @@ server: - `-D ` - The bind DN. A unique identifier for the user being bound. - `-w ` - The bind password. -.Performing a search with a bound user +.Perform a search with a bound user ==== [source,shell] ---- @@ -107,7 +107,7 @@ ldapsearch -z 1 -x \ ---- ==== -== 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. @@ -204,6 +204,7 @@ The `openssl` invocation is different depending on whether StartTLS or LDAPS 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 @@ -222,6 +223,7 @@ MIIHDjCCBPagAwIBAgIJANAO5znieeLNMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYD .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) @@ -235,13 +237,16 @@ Certificate chain 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. diff --git a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/index.adoc b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/index.adoc index cd14267dd8..b8e56345a6 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/index.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/index.adoc @@ -1,4 +1,4 @@ -= 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. @@ -12,21 +12,21 @@ issues is that a firewall is preventing network access from the RADIUS server to 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. diff --git a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/locating_objects.adoc b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/locating_objects.adoc index ca9255017e..f8656d9de7 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/locating_objects.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/locating_objects.adoc @@ -1,4 +1,4 @@ -= 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 diff --git a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc index a40ba943ba..99650f694b 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch/translating_to_the_ldap_module.adoc @@ -1,4 +1,4 @@ -= Translating ldapsearch arguments to LDAP configuration items += Generate LDAP Configuration Items [width="100%",cols="30%,20%,50%",options="header",] |=== @@ -31,7 +31,7 @@ ```access_positive = 'yes'``` |=== -== Groups - Common +== Groups - common [width="100%",cols="30%,70%",options="header",] |=== diff --git a/doc/antora/modules/howto/pages/modules/mschap/index.adoc b/doc/antora/modules/howto/pages/modules/mschap/index.adoc index 69f37eacee..35a4eb0066 100644 --- a/doc/antora/modules/howto/pages/modules/mschap/index.adoc +++ b/doc/antora/modules/howto/pages/modules/mschap/index.adoc @@ -1,4 +1,4 @@ -= rlm_mschap += MS-CHAP include::ROOT:partial$v3_warning.adoc[] @@ -21,9 +21,7 @@ controller. 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 @@ -50,7 +48,7 @@ i.e. user@domain 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:: @@ -180,13 +178,16 @@ Or: 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. diff --git a/doc/antora/modules/howto/pages/modules/pam/index.adoc b/doc/antora/modules/howto/pages/modules/pam/index.adoc index 5ed6880dd7..00100e20da 100644 --- a/doc/antora/modules/howto/pages/modules/pam/index.adoc +++ b/doc/antora/modules/howto/pages/modules/pam/index.adoc @@ -1,4 +1,4 @@ -= 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’ diff --git a/doc/antora/modules/howto/pages/modules/passwd/index.adoc b/doc/antora/modules/howto/pages/modules/passwd/index.adoc index d49e027517..6efcd2acaf 100644 --- a/doc/antora/modules/howto/pages/modules/passwd/index.adoc +++ b/doc/antora/modules/howto/pages/modules/passwd/index.adoc @@ -1,4 +1,4 @@ -= rlm_passwd += PASSWD Passwd-like files authorization module. diff --git a/doc/antora/modules/howto/pages/modules/python/index.adoc b/doc/antora/modules/howto/pages/modules/python/index.adoc index e09276cd12..79b2acc739 100644 --- a/doc/antora/modules/howto/pages/modules/python/index.adoc +++ b/doc/antora/modules/howto/pages/modules/python/index.adoc @@ -1,7 +1,5 @@ = 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. @@ -100,7 +98,7 @@ return freeradius.RLM_MODULE_UPDATED 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`. diff --git a/doc/antora/modules/howto/pages/modules/rest/bootstrap_nginx.adoc b/doc/antora/modules/howto/pages/modules/rest/bootstrap_nginx.adoc index b0716250b2..e005f2fc5a 100644 --- a/doc/antora/modules/howto/pages/modules/rest/bootstrap_nginx.adoc +++ b/doc/antora/modules/howto/pages/modules/rest/bootstrap_nginx.adoc @@ -1,4 +1,4 @@ -= Bootstrap NGINX += Install and Configure NGINX NGINX itself should be installed from packages provided with your OS. diff --git a/doc/antora/modules/howto/pages/modules/rest/configuration.adoc b/doc/antora/modules/howto/pages/modules/rest/configuration.adoc index 19432443dc..06445531a2 100644 --- a/doc/antora/modules/howto/pages/modules/rest/configuration.adoc +++ b/doc/antora/modules/howto/pages/modules/rest/configuration.adoc @@ -2,7 +2,7 @@ include::howto:partial$pre_test.adoc[] -== Editing mods-available/rest +== Edit mods-available/rest [source,config] ---- @@ -15,7 +15,7 @@ rest { <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. diff --git a/doc/antora/modules/howto/pages/modules/rest/index.adoc b/doc/antora/modules/howto/pages/modules/rest/index.adoc index c193098be1..adf405bda5 100644 --- a/doc/antora/modules/howto/pages/modules/rest/index.adoc +++ b/doc/antora/modules/howto/pages/modules/rest/index.adoc @@ -1,5 +1,4 @@ = REST -== Introduction FreeRADIUS can be used to communicate with REST APIs. @@ -29,5 +28,11 @@ which allows mapping elements of a JSON response to FreeRADIUS. 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. diff --git a/doc/antora/modules/howto/pages/modules/sql/data-usage-reporting.adoc b/doc/antora/modules/howto/pages/modules/sql/data-usage-reporting.adoc index 46e98f0a80..99017f6bc0 100644 --- a/doc/antora/modules/howto/pages/modules/sql/data-usage-reporting.adoc +++ b/doc/antora/modules/howto/pages/modules/sql/data-usage-reporting.adoc @@ -1,4 +1,4 @@ -= Periodic Data Usage Reporting += Data Usage Reporting == Introduction @@ -20,7 +20,9 @@ updated in real time with optimal performance. However, this format has the 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 @@ -28,11 +30,11 @@ reconnected session aligns with the start of the desired reporting interval and 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 @@ -46,7 +48,9 @@ already provide interim-update packets then it can normally be configured to do 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 @@ -57,7 +61,7 @@ resources since disconnected devices will likely be trying to reauthenticate while other are still being disconnected. Either approach to terminating existing sessions will of course result in an interruption of connectivity for users. - +==== == Solution @@ -85,11 +89,14 @@ The update process appends a number of rows to the `data_usage_by_period` table 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 @@ -111,9 +118,12 @@ procedure that updates this table: 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: @@ -169,11 +179,14 @@ with intervals that begin at the start of the day. Doing this allows accurate 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: @@ -225,16 +238,24 @@ To extract the aggregated data usage of a user bucketed in monthly periods the | 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 diff --git a/doc/antora/modules/howto/pages/modules/sql/index.adoc b/doc/antora/modules/howto/pages/modules/sql/index.adoc index a9e3651a2f..c744f36f70 100644 --- a/doc/antora/modules/howto/pages/modules/sql/index.adoc +++ b/doc/antora/modules/howto/pages/modules/sql/index.adoc @@ -1,7 +1,5 @@ = 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.) @@ -73,7 +71,7 @@ The above is exactly the same as in the `users` file. === 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 @@ -132,15 +130,12 @@ Framed-IP-Address := 1.2.3.4 ^ 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? @@ -149,7 +144,6 @@ Without the operator, the server simply doesn’t know, so always put a 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 diff --git a/doc/antora/modules/howto/pages/modules/sql/odbc.adoc b/doc/antora/modules/howto/pages/modules/sql/odbc.adoc index e5dfc96082..70a12e29a2 100644 --- a/doc/antora/modules/howto/pages/modules/sql/odbc.adoc +++ b/doc/antora/modules/howto/pages/modules/sql/odbc.adoc @@ -1,12 +1,15 @@ -= 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 @@ -29,27 +32,32 @@ here. Each entry in `odbc.ini` will normally have a reference in its `Driver` 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 @@ -74,12 +82,9 @@ which include the `rlm_unixodbc` module. If your operating system provides 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: @@ -120,7 +125,7 @@ reachability, firewalling, credentials, database permissions, etc. .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 @@ -143,9 +148,11 @@ sqlcmd -S tcp:192.0.2.1,1433 -U radius -P radPass_123 -d radius -e \ ================================================================================================ -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 @@ -156,7 +163,6 @@ Install the package for Microsoft ODBC Driver for SQL Server: dnf install msodbcsql17 unixodbc ---- - === Register the driver The Microsoft ODBC Driver for SQL Server package will normally register itself @@ -187,9 +193,12 @@ $ ldd /opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.5.so.2.1 ... ---- -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: @@ -220,10 +229,13 @@ Replace the values for `Server` and `Database` with your own. The config must 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 @@ -252,9 +264,11 @@ additional entry to odbcinst.ini, as follows: ================================================================================================ -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 @@ -350,8 +364,11 @@ Finally, attempt an authentication: ================================================================================================ -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. diff --git a/doc/antora/modules/howto/pages/modules/sqlcounter/index.adoc b/doc/antora/modules/howto/pages/modules/sqlcounter/index.adoc index ba8aa4b4c0..3e18e68b4d 100644 --- a/doc/antora/modules/howto/pages/modules/sqlcounter/index.adoc +++ b/doc/antora/modules/howto/pages/modules/sqlcounter/index.adoc @@ -1,4 +1,4 @@ -= SQL counter module += SQL-Counter == Introduction diff --git a/doc/antora/modules/howto/pages/modules/sqlippool/index.adoc b/doc/antora/modules/howto/pages/modules/sqlippool/index.adoc index 327c1b9cf1..2a5a9e359f 100644 --- a/doc/antora/modules/howto/pages/modules/sqlippool/index.adoc +++ b/doc/antora/modules/howto/pages/modules/sqlippool/index.adoc @@ -1,7 +1,5 @@ = 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. diff --git a/doc/antora/modules/howto/pages/modules/sqlippool/populating.adoc b/doc/antora/modules/howto/pages/modules/sqlippool/populating.adoc index 1d6374dd58..2d643f10e4 100644 --- a/doc/antora/modules/howto/pages/modules/sqlippool/populating.adoc +++ b/doc/antora/modules/howto/pages/modules/sqlippool/populating.adoc @@ -18,7 +18,7 @@ that make changes to the datastore. For example: 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 diff --git a/doc/antora/modules/howto/pages/modules/sqlippool/testing.adoc b/doc/antora/modules/howto/pages/modules/sqlippool/testing.adoc index 1b0c3f01fb..fbbb2ae31a 100644 --- a/doc/antora/modules/howto/pages/modules/sqlippool/testing.adoc +++ b/doc/antora/modules/howto/pages/modules/sqlippool/testing.adoc @@ -1,4 +1,4 @@ -= 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. diff --git a/doc/antora/modules/howto/pages/optimization/index.adoc b/doc/antora/modules/howto/pages/optimization/index.adoc index 5ba492fe1a..8fc5959c91 100644 --- a/doc/antora/modules/howto/pages/optimization/index.adoc +++ b/doc/antora/modules/howto/pages/optimization/index.adoc @@ -1,10 +1,10 @@ -= 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. @@ -20,26 +20,26 @@ Optimizing resources and configurations helps maintain a stable and robust RADIU 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. diff --git a/doc/antora/modules/howto/pages/os/letsencrypt.adoc b/doc/antora/modules/howto/pages/os/letsencrypt.adoc index 5be328b7c4..23133b46b4 100644 --- a/doc/antora/modules/howto/pages/os/letsencrypt.adoc +++ b/doc/antora/modules/howto/pages/os/letsencrypt.adoc @@ -62,7 +62,7 @@ We will be setting up the following components: - 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 diff --git a/doc/antora/modules/howto/pages/protocols/radius/radsec_client.adoc b/doc/antora/modules/howto/pages/protocols/radius/radsec_client.adoc index 8773f18f97..be33d0366d 100644 --- a/doc/antora/modules/howto/pages/protocols/radius/radsec_client.adoc +++ b/doc/antora/modules/howto/pages/protocols/radius/radsec_client.adoc @@ -1,4 +1,4 @@ -== 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 diff --git a/doc/antora/modules/howto/pages/protocols/radius/tls.adoc b/doc/antora/modules/howto/pages/protocols/radius/tls.adoc index b95d0027eb..585ad74c6b 100644 --- a/doc/antora/modules/howto/pages/protocols/radius/tls.adoc +++ b/doc/antora/modules/howto/pages/protocols/radius/tls.adoc @@ -120,7 +120,7 @@ distraction if used for by guide. 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] diff --git a/doc/antora/modules/howto/pages/radsniff.adoc b/doc/antora/modules/howto/pages/radsniff.adoc index f6bf069440..1e25887f2f 100644 --- a/doc/antora/modules/howto/pages/radsniff.adoc +++ b/doc/antora/modules/howto/pages/radsniff.adoc @@ -27,7 +27,7 @@ sudo apt-get install libpcap-dev libcollectdclient-dev 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. @@ -114,9 +114,9 @@ You'll also need to add the type definitions from [here](https://raw.githubuserc ```text -l 0 --vertical-label "PPS" -DEF:received=/var/lib/collectd/rrd//-exchanged/radius_count-.rrd:received:AVERAGE -DEF:linked=/var/lib/collectd/rrd//-exchanged/radius_count-.rrd:linked:AVERAGE -DEF:unlinked=/var/lib/collectd/rrd//-exchanged/radius_count-.rrd:unlinked:AVERAGE +DEF:received=/var/lib/collectd/rrd//-exchanged/radius_count-.rrd:received:AVERAGE +DEF:linked=/var/lib/collectd/rrd//-exchanged/radius_count-.rrd:linked:AVERAGE +DEF:unlinked=/var/lib/collectd/rrd//-exchanged/radius_count-.rrd:unlinked:AVERAGE DEF:reused=/var/lib/collectd/rrd//exchanged/radius_count-.rrd:reused:AVERAGE AREA:received#DD44CC:received AREA:linked#66BBCC:linked @@ -144,13 +144,13 @@ LINE:trend86400#946A00:avg_day ```text -l 0 --vertical-label "Requests completed per second" -DEF:none=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:none:AVERAGE -DEF:1=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:1:AVERAGE -DEF:2=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:2:AVERAGE +DEF:none=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:none:AVERAGE +DEF:1=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:1:AVERAGE +DEF:2=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:2:AVERAGE DEF:3=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:3:AVERAGE DEF:4=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:4:AVERAGE DEF:more=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:more:AVERAGE -DEF:lost=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:lost:AVERAGE +DEF:lost=/var/lib/collectd/rrd//-exchanged/radius_rtx-.rrd:lost:AVERAGE AREA:none#2AD400:none STACK:1#4DB000:1 STACK:2#718D00:2 @@ -196,7 +196,7 @@ Then restart munin-node. 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 ```` 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 diff --git a/doc/antora/modules/howto/pages/twitter.adoc b/doc/antora/modules/howto/pages/twitter.adoc index 97e281bda6..33c9e346c9 100644 --- a/doc/antora/modules/howto/pages/twitter.adoc +++ b/doc/antora/modules/howto/pages/twitter.adoc @@ -52,7 +52,7 @@ And add this to policy.d/twitter # 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. diff --git a/doc/antora/modules/howto/pages/vendors/cisco.adoc b/doc/antora/modules/howto/pages/vendors/cisco.adoc index e78e03069a..d46b323a77 100644 --- a/doc/antora/modules/howto/pages/vendors/cisco.adoc +++ b/doc/antora/modules/howto/pages/vendors/cisco.adoc @@ -18,7 +18,7 @@ To use RADIUS to authenticate your inbound shell (telnet and ssh) connections yo 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 diff --git a/doc/antora/modules/howto/pages/vendors/hp.adoc b/doc/antora/modules/howto/pages/vendors/hp.adoc index 91354c162a..effaf99091 100644 --- a/doc/antora/modules/howto/pages/vendors/hp.adoc +++ b/doc/antora/modules/howto/pages/vendors/hp.adoc @@ -360,12 +360,12 @@ conf 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)._ @@ -408,9 +408,9 @@ All CoA/DM requests must contain at least one NAS-Identification attribute (NAS- |NAS-IP-Address |1 |Source IP for RADIUS requests (sent from the switch) |- |```` |=== -### 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 diff --git a/doc/antora/modules/howto/pages/vendors/huawei.doc b/doc/antora/modules/howto/pages/vendors/huawei.doc index da3d4f72c7..173e1d08a3 100644 --- a/doc/antora/modules/howto/pages/vendors/huawei.doc +++ b/doc/antora/modules/howto/pages/vendors/huawei.doc @@ -26,7 +26,7 @@ aaa ! ``` -Freeradius server-side is set up normally like: +Freeradius server-side is set up normally like: **Server-side setup:** ```text client { diff --git a/doc/antora/modules/installation/nav.adoc b/doc/antora/modules/installation/nav.adoc index f932f45657..679ed7544c 100644 --- a/doc/antora/modules/installation/nav.adoc +++ b/doc/antora/modules/installation/nav.adoc @@ -1,11 +1,11 @@ -* 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] diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index b82ae9c4d7..fb1ba2d0ad 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -141,7 +141,7 @@ *** 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]