FAQ rework (33 questions) & troubleshooting guide (1st draft).

Build error fix - Concepts index xref resolved.

Updated faq, troubleshooting, added pages. Updated top-level nav file to include new entries.

doc/antora/modules/ROOT/nav.adoc

@@ -3,6 +3,13 @@
 *** xref:radiusd_x.adoc[Debugging]
 *** xref:gethelp.adoc[Getting Help]
 ** xref:faq.adoc[FAQ]
+** xref:trouble-shooting/index.adoc[Troubleshooting]
+*** xref:trouble-shooting/user.adoc[User Management]
+*** xref:trouble-shooting/server.adoc[Server Configuration]
+*** xref:trouble-shooting/client.adoc[Client Configuration]
+*** xref:trouble-shooting/connect_nas.adoc[Connectivity-NAS]
+*** xref:trouble-shooting/datastore.adoc[Datastores]
+
 
 // Copyright (C) 2025 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // This documentation was developed by Network RADIUS SAS.

doc/antora/modules/ROOT/pages/gethelp.adoc

@@ -2,24 +2,21 @@
 
 ## Official Documentation
 
-A lot of information can be found online for FreeRADIUS, but most of this information is out-of-date or
-incorrect. Avoid third party documentation refer to the documentation created by FreeRADIUS and InkBridge Networks
-as outlined below:
+A lot of information can be found online for FreeRADIUS, but most of this information is out-of-date or incorrect. Avoid third party documentation refer to the documentation created by FreeRADIUS and InkBridge Networks as follows:
 
-* https://www.freeradius.org[FreeRADIUS]
-* https://www.inkbridgenetworks.com[InkBridge Networks]
+* *https://www.freeradius.org[FreeRADIUS]*
+* *https://www.inkbridgenetworks.com[InkBridge Networks]*
 
 ## What Email list do I use?
 
-There are several mailing lists associated with the FreeRADIUS server project. The lists are on
-the http://freeradius.org/list/[freeRADIUS] website. The current lists are:
+There are several mailing lists associated with the FreeRADIUS server project. The lists are on the http://freeradius.org/list/[freeRADIUS] website. The current lists are:
 
 * *mailto:freeradius-users@lists.freeradius.org[freeradius-users]*
 This list is for all users of FreeRADIUS and deals with general questions related to FreeRADIUS
 * *mailto:freeradius-devel@lists.freeradius.org[freeradius-devel]*
 This list is for developers who are writing code for FreeRADIUS.The content is highly technical and is
 not suited to the average user.
-* *mailto:freeradius-announce@lists.freeradius.org[reeradius-announce]*
+* *mailto:freeradius-announce@lists.freeradius.org[freeradius-announce]*
 This list is for all users of FreeRADIUS. Announcements about FreeRADIUS, including new versions
 and security issues, are made here.
 
@@ -43,8 +40,7 @@ smoothly. InkBridge Networks are experts at designing a customized RADIUS soluti
 the appropriate number of RADIUS and database servers for your particular business needs. We install the RADIUS server and database and generate
 the necessary tables, schemas, queries, and replication.
 
-We can configure multiple forms of authorization on the same system simultaneously. The system can
-include:
+We can configure multiple forms of authorization on the same system simultaneously. The system can include:
 
 * 802.1x
 * PEAP
@@ -54,9 +50,7 @@ include:
 * MAC authentication
 * MAC auth bypass (MAB)
 
-Existing systems can be migrated to our product or we can configure our product to work with your
-databases. The final result is a system that is robust, high performance, and easy to maintain. Contact us
-at sales@networkradius.com for more information.
+Existing systems can be migrated to our product or we can configure our product to work with your databases. The final result is a system that is robust, high performance, and easy to maintain. Contact us at sales@networkradius.com for more information.
 
 // Copyright (C) 2025 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // This documentation was developed by Network RADIUS SAS.

doc/antora/modules/ROOT/pages/index.adoc

@@ -1,5 +1,8 @@
 = Introduction
 
+This is the FreeRADIUS version 4 documentation that is available under
+the Creative Commons Non-Commercial xref:LICENSE[license].
+
 [WARNING]
 ====
 *VERSION 4 IS IN DEVELOPMENT AND HAS NOT BEEN OFFICIALLY
@@ -11,9 +14,6 @@ documentation may change.
 Please wait for an official release before using version 4.
 ====
 
-This is the FreeRADIUS version 4 documentation that is available under
-the Creative Commons Non-Commercial xref:LICENSE[license].
-
 FreeRADIUS is a complex piece of software with many configuration
 options. In most circumstances, the default configuration works with
 minimal effort to install a server.  For more complex requirements,
@@ -36,14 +36,15 @@ task-based results as follows:
 * xref:howto:index.adoc[Howto] guides step you through various tasks and includes xref:howto:installation/index.adoc[Installing] and xref:howto:installation/upgrade.adoc[Upgrade] guide.
 * xref:tutorials:new_user.adoc[Tutorials] task based learning with real-world configurations and debugging exercises.
 * xref:developers:index.adoc[Developers] section outlines coding standards, raising bugs, and contributing with GitHub.
-* xref:ts.adoc[Troubleshooting] section to help you resolve the most common issues with FreeRADIUS installations and configurations.
+* xref:trouble-shooting/index.adoc[Troubleshooting] section to help you resolve the most common issues with FreeRADIUS installations and configurations.
 
 Within each section, the documentation is organized into subsections,
 smaller pages, and relavent cross-links.  This hierarchy ensures that
 you can find information quickly and extract the instructions you
 need.  For example, the Howto guides are split into a series of small
 steps, each of which can be performed quickly.
 
+
 == What's new in FreeRADIUS version 4
 
 FreeRADIUS version 4 is in "alpha" right now.  If version 4 works,
@@ -52,80 +53,74 @@ version 3.
 
 As of the time of this release, FreeRADIUS:
 
-* It's possible to proxy one packet to multiple destinations.
+* Abililty to proxy one packet to multiple destinations.
 * Can capture a `failed` proxy, and fall back to local
   authentication.
 * The server supports multiple clients with different shared
   secrets behind one NAT gateway.
 * DHCP and VMPS are integrated with full functionality and features.
 * The server supports TACACS+.
-* Connections to databases are `asynchronous` to ensure stable access,
+* Connections to databases are `asynchronous` ensuring stable access,
   and prevents server lockups.
-* The Python and Lua modules do not fully support the v4 "nested" attributes.
 * Enums are prefixed with `::`, as in `Service-Type == ::Framed-User`.
   * The server still does not always require (or print) the `::` prefix.  That will change.
-* By implementing `::` for enums, the requirement to use `&` as a prefix for attribute names is not needed.
+  * By implementing `::` for enums, the requirement to use `&` as a prefix for attribute names is not needed.
   * This change may require changes to all of the configuration.  We will try to allow `&` or not, but that may not be possible.
 * Dynamic expansions have changed from `%{md5:foo}` to a more standard syntax of `%md5(foo)`.
-* The new syntax supports multiple comma-separated arguments such as `%function(a, b, c)`.
-* Expansions such as `%{User-Name}`  still work in addition to expressions like `%{1+2}` too.
-* Alternation `%{%{foo}:-%{bar}}` has been replaced by `%{&foo || &bar}`, which is clearer and uses less nesting.
+  * The new syntax supports multiple comma-separated arguments such as `%function(a, b, c)`.
+  * Expansions such as `%{User-Name}`  still work in addition to expressions like `%{1+2}` too.
+  * Alternation `%{%{foo}:-%{bar}}` has been replaced by `%{&foo || &bar}`, which is clearer and uses less nesting.
+* Python and Lua modules *only* partially fully support the v4 "nested" attributes.
 * RADIUS/TLS (RadSec) is not implemented.
 * TEAP and EAP-FAST are not implemented.
 * the "haproxy" and "reverse CoA' features are not implemented.
 
-Administrators who have version 3 and wish to upgrade to version 4
-must read the  xref:howto:installation/upgrade.adoc[Upgrade] guide.
-This guide explains the differences between the two versions, and
+Administrators using version 3 and wish to upgrade to version 4
+must read the  xref:howto:installation/upgrade.adoc[Upgrading] page.
+This section explains the differences between the two versions and
 how an existing configuration can be reproduced in the latest
-release. Do *not* use version 3 configuration files
-with version 4. These configuration files are *not* compatible on a
-major version upgrade.
+release. Do *not* use version 3 configuration files with version 4. These configuration files are *not* compatible on a major version upgrade.
 
 [WARNING]
 ====
-Do not open bug reports about those features being missing.
+Do not open bug reports about the previously listed features as missing.
 All such bug reports will be closed without comment.
 
-We do not recommend that operating systems or Linux distributions
-create their own packages for 4.0.0-alpha.  Our experience has been
-that packaging "alpha" releases results in confused and upset users.
-People _will_ install it due to the belief that "it's stable because
-it is packaged".  They will then run into issues, and will blame us.
-
-Such behavior is antisocial and is strongly discouraged.
+*Don't* create 4.0.0-alpha packages for your operating systems or Linux distributions. Our experience has been that creating "alpha" packages results in upset users that install that package. The users believed that the package is stable and then they will run into issues.
 ====
 
-== Network Requireements
+
+== Network Requirements
+blah blah
+
 
 === Operating Systems
 
 The FreeRADIUS protocol works on all Unix based systems.  It does not
 run natively under Windows.
 
+
 === CPU/RAM/disk space requirements
 
-A FreeRADIUS server has minimal requirements. A basic FreeRADIUS
-installation uses 8 megabytes of RAM, under one hundred megabytes of
-disk space, and minimal CPU power. An Internet Service Provider with
-10,000 or fewer users will not have any problems with any commodity
-system available at the time of this printing. If the ISP has more
-than 10,000 users, the overall system design becomes much more
-important than the specifications of an individual server.
+A FreeRADIUS server has minimal requirements. A basic FreeRADIUS installation uses 8 megabytes of RAM, under one hundred megabytes of disk space, and minimal CPU power. An Internet Service Provider with 10,000 or fewer users will not have any problems with any commodity system available at the time of this printing. If the ISP has more than 10,000 users, the overall system design becomes much more important than the specifications of an individual server.
 
 If the ISP has more than 10,000 users, the overall system design
 becomes much more important than the specifications of an individual
-server. Windows does not currently support FreeRADIUS.
+server.
+
 
 === Datastores
 
+The server can read or write to any database and both LDAP and SQL can be used in the same configuration simotaneously. The database queries are customizable and can adapt to any custom schema used at a customers site. The server supports fail-over and load balancing across multiple databases. There are no pre-set limits to the number, or type, of databases used.
+
 == Debugging
 
 If you have ANY issues with your server, then restart the server
 in xref:radiusd_x.adoc[Debugging] mode. Review the logs to determine what
 the root problem is and make changes accordingly. Do only *ONE* change
 at a time and restart your server.
 
+
 == More Information
 
 Many resources, https://www.inkbridge.io/[experts], and documentation sets are available to help you with your RADIUS server. Refer to xref:gethelp.adoc[Getting Help] for more details.

doc/antora/modules/ROOT/pages/trouble-shooting/client.adoc

@@ -0,0 +1,23 @@
+= Client Configuration
+
+
+== Why doesn't PEAP or EAP-TLS work on a Windows machine?
+
+The most common problem with PEAP is that the client sends a series of Access-Request messages, the server sends an series of Access-Challenge responses, and then nothing happens.  After a little wait, the process starts again.
+
+If you see this happening STOP!
+
+The RADIUS server certificate has to have special OID's in it, or else the Microsoft clients will silently fail.  See the "scripts/xpextensions" file in the server "tar" file for examples, and the relevant Microsoft http://support.microsoft.com/kb/814394/en-us[KB814394] and http://support.microsoft.com/kb/885453/en-us[KB885453] pages.
+
+You *must* follow the instructions on the first page, and install the hot fix from the second page for PEAP or EAP-TLS to work with a Windows machine.
+
+
+== How do I make Windows XP clients use only PAP (Not CHAP)
+
+* Go to Network Connections an open Properties for this connection.
+* Select Security tab.
+* Click on Advanced radio button, and then on Settings button.
+* Leave only PAP ticked.
+* Click OK, OK to set it.
+
+If you have control over NAS, then set it to accept only PAP authentication. If you do that, all clients will "listen" and use only PAP. In that case there is no need to configure anything on the client(s).

doc/antora/modules/ROOT/pages/trouble-shooting/connect_nas.adoc

@@ -0,0 +1,115 @@
+= Connectivity-NAS
+
+
+== How do I tell the user what to use for an IP netmask?
+
+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.
+
+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.
+
+The following entries do almost the same on most NAS:
+.Entries Example
+[%collapsible]
+====
+	user Cleartext-Password := "blegh"
+		Service-Type = Framed-User,
+		Framed-Protocol = PPP,
+		Framed-IP-Address = 192.168.5.78,
+		Framed-IP-Netmask = 255.255.255.240
+
+	user Cleartext-Password := "blegh"
+		Service-Type = Framed-User,
+		Framed-Protocol = PPP,
+		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 RFCs for the exact syntax of the Framed-Route attribute).
+
+
+== 3Com/USR HiPerArc doesn't work
+
+I'm using a 3Com/USR HiPerArc and I keep getting this message on radius.log:
+
+	`Mon Jul 26 15:18:54 1999: Error: Accounting: logout: entry for NAS tc-if5 port 1 has wrong ID`
+
+If you're using HiPer ARC 4.1.11, you need to contact the vendor? Version 4.1.11 has a problem reporting NAS-port numbers to Radius. Upgrade the firmware from http://totalservice.usr.com to at least 4.1.59. If you are in Europe you can telephone to 3Com Global Response Center (phone number: 800 879489), and tell them that you have bought it in the last 90 days. They will help you, step by step, to do the upgrade.
+
+== 3Com/USR HiPerArc Simultaneous-Use doesn't work
+
+by Robert Dalton support at accesswest dot com
+
+Verify if you are using HiPerArc software version V4.2.32 release date 09/09/99
+
+In order for simultaneous logins to be prevented reported port density must be set to 256 using the command :
+
+	set pbus reported_port_density 256
+
+Otherwise it changes the calculations of the SNMP object ID's.
+
+There is a bug in effected versions of checkrad namely the line under the subroutine "sub_usrhiper". The line that should be commented out is:
+
+	($login) = /^.*\"([^"]+)".*$/;
+
+== Cisco Simultaneous-Use doesn't work
+
+Q: I am getting the following in radius.log file:
+
+	Thu Oct 21 10:59:01 1999: Error: Check-TS: timeout waiting for checkrad
+
+What's wrong?
+
+A: Verify if you have SNMP enabled on your CISCO router, check the existence of the following line:
+
+	snmp-server community public RO 97
+
+where 97 is the access-list that specifies who gets access to the SNMP info. You should also have a line like this:
+	access-list 97 permit A.B.C.D
+
+where A.B.C.D is the ip address of the host running the radius server.
+
+== Ascend MAX 4048 Simultaneous-Use doesn't work
+
+Q: I am getting the following in radius.log file:
+
+Thu Oct 21 10:59:01 1999: Error: Check-TS: timeout waiting for checkrad
+
+What's wrong?
+
+A: Verify that you have the MAX 4048 setup in your naslist as max40xx and that you have Finger turned on.
+
+	Ethernet->Mod Config->Finger=Yes
+
+
+== The server is complaining about invalid user route-bps-asc1-1, along with lots of others
+
+Ascend decided to have the 4000 series NAS boxes retrieve much of their configuration from the RADIUS server. To disable this "feature", set:
+
+	Ethernet->Mod Config->Auth->Allow Auth Config Rqsts = No
+
+
+== Why do Acct-Input-Octets and Acct-Output-Octets wrap at 4 GB?
+
+There are two possible causes of this problem:
+
+* Gigawords not enabled on NAS
+
+Some NAS do not send "Gigawords" attributes by default. Read your NAS documentation and configure it to send the attributes Acct-Input-Gigawords and Acct-Output-Gigawords.
+
+* Cisco IOS needs to set the flag for gigawords. Enter the following command on the NAS:
+
+	`aaa accounting gigawords`
+
+[NOTE]
+====
+This command requires a reload of the device on certain IOS version.
+====
+
+
+=== How do I enable logging of 64 bit counters, a.k.a. `Acct-{Input|Output}-Gigawords?`
+
+Refer to <<Why do Acct-Input-Octets and Acct-Output-Octets wrap at 4 GB?>>