FreeRADIUS · nolade · Jan 28, 2025
diff --git a/doc/antora/antora.yml b/doc/antora/antora.yml
@@ -10,9 +10,9 @@ prerelease: Devel
 start_page: ROOT:index.adoc
 nav:
 - modules/ROOT/nav.adoc
-- modules/reference/nav.adoc
-- modules/installation/nav.adoc
 - modules/concepts/nav.adoc
+- modules/reference/nav.adoc
 - modules/howto/nav.adoc
+- modules/installation/nav.adoc
 - modules/tutorials/nav.adoc
 - modules/developers/nav.adoc
diff --git a/doc/antora/modules/ROOT/pages/faq.adoc b/doc/antora/modules/ROOT/pages/faq.adoc
@@ -98,7 +98,7 @@ Then the server will always respond with the correct address.
 Yes, you can. Assuming you already have daemontools installed, configured and running in your system (see http://cr.yp.to/daemontools.html), you will have to make two decisions:
 1. The log account and group name (_log.log_ is used in this example). Logging programs run under this _account.group_. If this _account.group pair_ does not exist yet, create it now.
 
-2. The radiusd local service directory (_/etc/radiusd_ is used in this example). This is where radiusd will store logs and a few configuration files.
+//2. The radiusd local service directory (_/etc/radiusd_ is used in this example). This is where radiusd will store logs and a few configuration files.
 
 Then perform these steps:
 
@@ -454,20 +454,20 @@ If you're REALLY interested in knowing how to debug the RADIUS server yourself,
         Ready to process requests.
     * If it doesn't, then it should print out an error message. Read it.
     * If it takes a long time to start up, and THEN prints out the message, then your DNS is broken.
-8. Ensure that you have localhost in your _raddb/clients_ file. FreeRADIUS comes configured this way, so it should be there.
-9. Ensure you have a valid user in your _raddb/users_ file. If everything else fails, go to the top of the file and add the following entry:
+6. Ensure that you have localhost in your _raddb/clients_ file. FreeRADIUS comes configured this way, so it should be there.
+7. Ensure you have a valid user in your _raddb/users_ file. If everything else fails, go to the top of the file and add the following entry:
         bob Cleartext-Password := "bob"
         Reply-Message = "Hello, bob"
-12. Run the radtest program from the LOCAL machine, in another window. This will tell you if the server is alive and is answering requests.
+8. Run the radtest program from the LOCAL machine, in another window. This will tell you if the server is alive and is answering requests.
         radtest bob bob localhost 0 testing123
-14. Ensure that you see the Reply-Message above and that you do NOT see an "Access denied" message. If you get an Access-Accept message, this means that the server is running properly.
-15. Configure another machine as a RADIUS client and run radtest from that machine too. You SHOULD see the server receive the request and send a reply.
+9. Ensure that you see the Reply-Message above and that you do NOT see an "Access denied" message. If you get an Access-Accept message, this means that the server is running properly.
+10. Configure another machine as a RADIUS client and run radtest from that machine too. You SHOULD see the server receive the request and send a reply.
     * If the server does NOT receive the request then the ports are confused. RADIUS historically uses 1645/UDP, where RFC 2138 and many new systems use the proper value of 1812/UDP. See _/etc/services_ or use the -p option to specify a different port.
     * Run tcpdump in another window on the RADIUS client machine. Use the command:
     * `tcpdump udp`
     * Look CAREFULLY at the packets coming from the RADIUS server. Which address are they coming from? Which port?
-16. If authentication works from a different machine then you have the server set up correctly.
-17. Now you should use a more complicated configuration to see if the server receives and replies with the attributes you want. There is little information that can be offered here in the FAQ as your individual systems configuration can not be predicted.  However, a few hints can help:
+11. If authentication works from a different machine then you have the server set up correctly.
+12. Now you should use a more complicated configuration to see if the server receives and replies with the attributes you want. There is little information that can be offered here in the FAQ as your individual systems configuration can not be predicted.  However, a few hints can help:
     * ALWAYS test your configurations running the server in debugging mode if you want to debug a problem. If you do not do so then DO NOT expect anyone else to be able to help you.
     * `radiusd -X`
     * Read RFC 2138 to see what the RADIUS attributes are and how they work
@@ -769,13 +769,13 @@ Which gives : (tcpdump output)
 
 The whole netmask business is a complicated one. An IP interface has an IP address and usually a netmask associated with it. Netmasks on point-to-point interfaces like a PPP link are generally not used.
 
-If you set the Framed-IP-Netmask attribute in a radius profile, you are setting the netmask of the interface on the side of the [[NAS]].  The Framed-IP-Netmask attribute is NOT something you can set to influence the netmask on the side of the dialin user. And usually, that makes no sense anyway even if you could set it.
+If you set the Framed-IP-Netmask attribute in a radius profile, you are setting the netmask of the interface on the side of the NAS.  The Framed-IP-Netmask attribute is NOT something you can set to influence the netmask on the side of the dialin user. And usually, that makes no sense anyway even if you could set it.
 
 The result of this on most NAS is that they start to route a subnet (the subnet that contains the assigned IP address and that is as big as the netmask indicates) to that PPP interface and thus to the user. If that is exactly what you want, then that's fine, but if you do not intend to route a whole subnet to the user, then by all means do NOT use the Framed-IP-Netmask attribute.
 
-Many [[NAS]] interpret a left-out [[Framed-IP-Netmask]] as if it were set to 255.255.255.255, but to be certain you should set the Framed-IP-Netmask to 255.255.255.255.
+Many NAS interpret a left-out Framed-IP-Netmask as if it were set to 255.255.255.255, but to be certain you should set the Framed-IP-Netmask to 255.255.255.255.
 
-For example, the following entries do almost the same on most [[NAS]]:
+For example, the following entries do almost the same on most NAS:
 
 	user Cleartext-Password := "blegh"
 		Service-Type = Framed-User,
@@ -789,7 +789,7 @@ For example, the following entries do almost the same on most [[NAS]]:
 		Framed-IP-Address = 192.168.5.78,
 		Framed-Route = "192.168.5.64/28 0.0.0.0 1"
 
-The result is that the end user gets IP address 192.168.5.78 and that the whole network with IP addresses 192.168.5.64 - 195.64.5.79 is	routed over the PPP link to the user (see the [[RADIUS]] [[RFC]]s for the exact syntax of the Framed-Route attribute).
+The result is that the end user gets IP address 192.168.5.78 and that the whole network with IP addresses 192.168.5.64 - 195.64.5.79 is	routed over the PPP link to the user (see the RADIUS RFCs for the exact syntax of the Framed-Route attribute).
 
 ### How do I make CHAP work with LDAP?
 

diff --git a/doc/antora/modules/ROOT/pages/index.adoc b/doc/antora/modules/ROOT/pages/index.adoc
@@ -40,7 +40,7 @@ desired outcome. At a high level, the subject areas describe:
 * The xref:reference:raddb/index.adoc[configuration files] located in `/etc/raddb/`, or `/etc/freeradius/`
 * The syntax of the xref:reference:unlang/index.adoc[unlang] processing language
 * Various xref:howto:index.adoc[how-to] guides
-* xref:howto:installation/index.adoc[Installing] and xref:howto:installation/upgrade.adoc[upgrading] FreeRADIUS
+* xref:installation:index.adoc[Installing] and xref:installation:upgrade.adoc[upgrading] FreeRADIUS
 * xref:developers:index.adoc[Developer documentation]
 
 This organization means that for example, the `ldap` module will have

diff --git a/doc/antora/modules/concepts/pages/modules/ldap_authentication.adoc b/doc/antora/modules/concepts/pages/modules/ldap_authentication.adoc
@@ -40,7 +40,7 @@ involves giving the FreeRADIUS "read-only" user permission to read the
 `userPassword` field.
 
 Again, the best method is to test authentication is with the
-xref:modules/ldap_search.adoc[ldapsearch] tool.  These tests *must* be
+ldap search tool. These tests *must* be
 run prior to configuring FreeRADIUS.  We strongly recommend having the
 LDAP database return the `userPassword` field to FreeRADIUS, so that
 FreeRADIUS can authenticate the user.
@@ -67,15 +67,15 @@ formats.  There is sufficient information in the password values to
 determine what format it is in (base64, binary, or text), and what
 password "encryption" mechanism has been used (crypt, MD5, SHA, SSHA2,
 SHA3, etc).  All that is necessary is that the
-xref:raddb:mods-available/ldap.adoc[ldap module] be configured to map
+xref:reference:raddb/mods-available/ldap.adoc[ldap module] be configured to map
 the `userPassword` LDAP field to the `&control:Password-With-Header`
 attribute in FreeRADIUS.  FreeRADIUS will then "do the right thing" to
 authenticate the user.
 
 This mapping is done in the default module configuration.  There are
 no additional changes required for FreeRADIUS to correctly read and
 decode the `userPassword` field from LDAP.  Please see the
-xref:raddb:mods-available/pap.adoc[pap module] for a full list of
+xref:reference:raddb/mods-available/pap.adoc[pap module] for a full list of
 supported password "encryption" formats.
 
 == Additional Considerations

diff --git a/doc/antora/modules/developers/pages/index.adoc b/doc/antora/modules/developers/pages/index.adoc
@@ -5,7 +5,7 @@ List with some usual howtos for FreeRADIUS.
 Programming reference documentation can be found at the
 https://doc.freeradius.org/[Doxygen] site.
 
-# Instructions for Developers
+## Instructions for Developers
 
 As the name suggests, FreeRADIUS is developed under the GNU
 General Public License, Version 2 (GPLv2).

diff --git a/doc/antora/modules/developers/pages/rfc_compliance.adoc b/doc/antora/modules/developers/pages/rfc_compliance.adoc
@@ -1,7 +1,7 @@
 
 = RFC Compliance
 
-=== RADIUS Related
+== RADIUS Related
 
 * RFC 2865 Remote Authentication Dial In User Service (RADIUS) (obsoletes RFC 2138 and RFC 2058)
 * RFC 2866 RADIUS Accounting (obsoletes RFC 2139 and RFC 2059)
@@ -10,15 +10,15 @@
 * RFC 2869 RADIUS Extensions
 * RFC 2548 Microsoft Vendor-Specific RADIUS Attributes
 
-=== Authentication Related
+== Authentication Related
 
 * RFC 1994 PPP Challenge Handshake Authentication Protocol (CHAP)
 * RFC 2284 PPP Extensible Authentication Protocol (EAP)
 * RFC 2716 PPP EAP TLS Authentication Protocol
 * RFC 2759 Microsoft PPP CHAP Extensions, Version 2
 * RFC 3748 Extensible Authentication Protocol (EAP)
 
-=== SNMP Related
+== SNMP Related
 
 * RFC 1227 SNMP MUX Protocol and MIB
 * RFC 2619 RADIUS Authentication Server MIB

diff --git a/doc/antora/modules/howto/nav.adoc b/doc/antora/modules/howto/nav.adoc
@@ -44,7 +44,7 @@
 
 *** xref:modules/sqlcounter/index.adoc[SQL-Counter]
 *** xref:modules/sqlippool/index.adoc[SQL-IP-Pool]
-**** xref:modules/sqlippool/generating.adoc[Generating IPs]
+**** xref:modules/sqlippool/populating.adoc[Generating IPs]
 **** xref:modules/sqlippool/insert.adoc[Inserting IPs into SQL]
 
 ** xref:protocols/index.adoc[Protocols]

diff --git a/doc/antora/modules/howto/pages/git.adoc b/doc/antora/modules/howto/pages/git.adoc
@@ -2,7 +2,7 @@
 
 As well as being an excellent SCM (Source control management) tool, git is also very useful for tracking changes to configuration files, and even for performing remote administration of servers.
 
-=== The basics
+== The basics
 
 For basic configuration management one only has to:
 
@@ -30,7 +30,7 @@ And if it's all gone horribly wrong:
 
 There are many many tutorials available if you want to learn more generic git administration, this one is extra pretty: http://gitimmersion.com.
 
-==== Remote administration
+=== Remote administration
 
 The basic functionality of git is useful on its own, but one of the features that really makes git shine among the SCMs is its support for commit hooks. Hooks don't require anything special to function (like gitosis or the git-daemon), they work just as well over straight SSH.
 

diff --git a/doc/antora/modules/howto/pages/modules/rest/index.adoc b/doc/antora/modules/howto/pages/modules/rest/index.adoc
@@ -8,7 +8,7 @@ FreeRADIUS can be used to communicate with REST APIs.
 This section describes the basic configuration needed to configure the REST
 module to communicate with a REST service.
 
-== xref:modules/rest/fixed_data.adoc[Calling REST endpoints with fixed data formats]
+//== xref:modules/rest/fixed_data.adoc[Calling REST endpoints with fixed data formats]
 
 The REST module was developed to allow business logic to be separated out into a
 separate discrete service.  This reduces the role of FreeRADIUS to a translation
@@ -20,10 +20,10 @@ If you will be developing a new REST API to implement business logic for a AAA
 service, you should follow the guide in this section, and accept and return
 data in that format the REST module expected.
 
-== xref:modules/rest/custom_data.adoc[Calling REST endpoints with a custom data format]
+//== xref:modules/rest/custom_data.adoc[Calling REST endpoints with a custom data format]
 
 The REST module can also communicate with arbitrary REST endpoints,
-and versions ≥ v4.0.x include a JSON module xref:mods-available/json.adoc[JSON]
+and versions ≥ v4.0.x include a JSON module xref:reference:raddb/mods-available/json.adoc[JSON]
 which allows mapping elements of a JSON response to FreeRADIUS.
 
 If you're attempting to integrate an existing REST API, this section will provide

diff --git a/doc/antora/modules/howto/pages/modules/sqlippool/index.adoc b/doc/antora/modules/howto/pages/modules/sqlippool/index.adoc
@@ -491,7 +491,7 @@ Framed-IPv6-Prefix RADIUS attribute then you can put the IPv6 prefixes into the
 
 Populate the pool either manually using a text editor or database tool, or via a script.
 
-See xref:modules/sqlippool/generating.adoc[Generating IPs for the
+See xref:modules/sqlippool/populating.adoc[Generating IPs for the
 pools] for instructions on how to create lists of IPs for a pool.  And
 then xref:modules/sqlippool/insert.adoc[Inserting IPs into SQL]
 

diff --git a/doc/antora/modules/howto/pages/modules/sqlippool/insert.adoc b/doc/antora/modules/howto/pages/modules/sqlippool/insert.adoc
@@ -34,7 +34,7 @@ follows:
 psql radius -qtAc 'SELECT framedipaddress FROM radippool' > existing_ips.txt
 ----
 
-See the xref:modules/sqlippool/generating.adoc[Generating IPs for the
+See the xref:modules/sqlippool/populating.adoc[Generating IPs for the
 pools] page for instructions on how to generate the list of IPs to
 modify.
 

diff --git a/doc/antora/modules/howto/pages/twitter.adoc b/doc/antora/modules/howto/pages/twitter.adoc
@@ -1,6 +1,6 @@
 Note: The required functionality to do basic twitter operations is only available in FreeRADIUS >= v3.0.4
 
-# Overview
+## Overview
 
 The difficult part in twitter integration is signing the requests. If a single character
 is incorrect, the signature won't match, and the Twitter API will return an authentication

diff --git a/doc/antora/modules/howto/pages/vendors/hp.adoc b/doc/antora/modules/howto/pages/vendors/hp.adoc
@@ -14,7 +14,7 @@ Note: A hashed version of the SRC address is also inserted into the CHAP-Passwor
 
 In normal operation the switch will attempt to authenticate the client every _quiet-period_ (a configurable period measured in seconds). That is, when the client connects and either: The RADIUS server returns an Access-Reject, or the RADIUS server is Unreachable, the switch will retry authentication after _quiet-period_ seconds.
 
-##### Beware using guest VLANs with mac-based authentication and dynamic VLAN assignment
+#### Beware using guest VLANs with mac-based authentication and dynamic VLAN assignment
 
 The quiet-period timer will not fire if an _unauth-vid_ is configured and the client transitions into the 'guest' state. The ASG manual for some products suggests that if the client falls into the 'guest' state because of RADIUS server timeout then they will be re-authenticated, but this was not implemented in software!
 Beware using the _unauth-vid_ where switches rely on RADIUS servers for VLAN assignment. A RADIUS server failure or power outage could place all clients into the 'guest' state where they will not be able to recover without manual intervention.
@@ -64,7 +64,7 @@ Client based mode is a HP proprietary extension to the 802.1X standard, and is u
 In client based mode a filtering table is maintained for each authenticated port. Only devices which have successfully completed 802.1X authentication have their Mac-Addresses added to the filtering table, so only packets from authenticated devices are allowed to ingress into the network.
 Multiple authentication sessions for different devices may run concurrently, and accounting information will be provided for each individual session.
 
-###### In earlier firmware, Reply-Messages were encapsulated as EAP-Notification packets.
+##### In earlier firmware, Reply-Messages were encapsulated as EAP-Notification packets.
 In firmware (< H.10.74 or equivalent) the switch encapsulates the contents of the RADIUS Reply-Message attribute in an EAP-Notification packet, which it sends after the EAP-Success/Failure packet.
 Most supplicants deal with this ok (despite it breaking RFC 3579), but it causes WPA_Supplicant to restart authentication. If you're using 802.1X with older firmware, be sure to filter out the Reply-Message attribute in any Access-Accept packets containing an EAP-Message.
 
@@ -109,7 +109,7 @@ When multiple port-access mechanisms are used, 802.1X based authentication alway
 
 If an 802.1X authenticated client sends an EAPOL-Logoff packet, the 802.1X session is terminated and the client will be re-authenticated using Web/Mac based authentication.
 
-###### Setting the _unauth-vid_ for both 802.1X and Mac/Web authenticators will result in unexpected behaviour
+#### Setting the _unauth-vid_ for both 802.1X and Mac/Web authenticators will result in unexpected behaviour
 This usually results in the client being assigned the port-access authenticator _unauth-vid_ after completing Mac/Web authentication. When you need to configure an _unauth-vid_ with multiple authentication mechanisms, set the _unauth-vid_ for the Mac/Web authenticator, not the 802.1X authenticator.
 
 Note: Setting unath-vid for 802.1X when concurrent 802.1X/MAC authentication is enabled, is now prohibited in software versions >= H.10.79 or equivalent
@@ -171,7 +171,7 @@ The value of Egress-VLANID is a bit string, the first 8 bits specify whether the
 
 Note: It is not possible to specify the ingress untagged VLAN with RFC 4675 attributes, so RFC 3580 attributes must be used instead.
 
-###### Ingress-Filters VSA is ignored by all HP ProCurve switches 
+##### Ingress-Filters VSA is ignored by all HP ProCurve switches 
 
 The default switching 'philosophy' of ProCurve switches is to filter ingress packets based on the egress VLAN membership of a port, this goes against the 802.1Q standard, which requires that frames be allowed to ingress, even if their tag does not match a VLAN the port is a member of.
 Supporting this attribute (i.e. allowing promiscuous ingress) would break the ProCurve switching philosophy, and so this attribute is ignored.
@@ -264,7 +264,7 @@ conf
 exit
 ```
 
-###### Default edge port GVRP settings are insecure, and may allow circumvention of network policy.
+#### Default edge port GVRP settings are insecure, and may allow circumvention of network policy.
 
 The default setting for the interface _unknown-vlan_ option is _learn_, this allows GVRP enabled clients to gain access to additional tagged VLANs once the port is in an open state. This is often undesirable from a security standpoint, so the _unknown-vlan_ option should be set to _disable_ on all port-access authenticated edge ports.
 

diff --git a/doc/antora/modules/installation/pages/debian.adoc b/doc/antora/modules/installation/pages/debian.adoc
@@ -3,7 +3,7 @@
 * Installing from repositories 
 * Installing from source 
 
-== Installing from repositories :
+== Installing from repositories 
 
 This is usually the easiest solution, but at the moment of writing (2016-06) both Ubuntu 16.04 and Ubuntu 14.04.4 contain packages which are EOL and which are not the latest in their own main version. So building from source is recommended as it will contain the latest version, which probably got most of the bugs sorted.
 
@@ -64,8 +64,6 @@ cd /usr/share/doc/freeradius
 
 Installing from source can be daunting for people who never did it but as long as you read the output of the building process, it should tell you what went wrong or what is missing.
 
-On GitHub select the branch you wish to install and press clone or download.
-=======
 Your first step is to download the source files which can be found on one of the following sites:
 
     1. http://freeradius.org/download.html[Freeradius.org] - Choose the latest release by selecting the relevant button.
@@ -169,7 +167,7 @@ The install might show errors. Read the error !! Ask questions on freeradius lis
 
 
 
-= Building on Debian or Ubuntu
+== Building on Debian or Ubuntu
 
 Building Debian packages (including Ubuntu) of FreeRADIUS from source is kept as simple as possible.