rearrange mods-available nav

and add short summaries of the various modules

Author: alandekok

doc/antora/modules/reference/nav.adoc

@@ -136,37 +136,49 @@
 **** xref:raddb/mods-available/eap_inner.adoc[EAP/Inner]
 **** xref:raddb/mods-available/imap.adoc[IMAP]
 **** xref:raddb/mods-available/krb5.adoc[Kerberos]
+**** xref:raddb/mods-available/ldap.adoc[LDAP]
 **** xref:raddb/mods-available/mschap.adoc[Microsoft CHAP]
 **** xref:raddb/mods-available/ntlm_auth.adoc[NTLM Auth]
 **** xref:raddb/mods-available/pam.adoc[Pluggable Authentication]
 **** xref:raddb/mods-available/pap.adoc[PAP]
+xref:raddb/mods-available/rest.adoc[REST]
 **** xref:raddb/mods-available/totp.adoc[TOTP]
 **** xref:raddb/mods-available/winbind.adoc[Winbind]
 **** xref:raddb/mods-available/yubikey.adoc[Yubikey]
 
 *** xref:raddb/mods-available/doc/datastore.adoc[Datastore]
 **** xref:raddb/mods-available/cache.adoc[Cache]
-**** xref:raddb/mods-available/cache_eap.adoc[Cache EAP]
-**** xref:raddb/mods-available/cache_tls.adoc[Cache TLS Session]
+***** xref:raddb/mods-available/cache_eap.adoc[Cache EAP]
+***** xref:raddb/mods-available/cache_tls.adoc[Cache TLS Session]
 **** xref:raddb/mods-available/client.adoc[Client]
 **** xref:raddb/mods-available/csv.adoc[CSV]
-**** xref:raddb/mods-available/couchbase.adoc[Couchbase]
 **** xref:raddb/mods-available/etc_group.adoc[etc_group]
 **** xref:raddb/mods-available/files.adoc[Files]
 ***** xref:raddb/mods-config/files/users.adoc[File Format]
 **** xref:raddb/mods-available/ldap.adoc[LDAP]
 **** xref:raddb/mods-available/opendirectory.adoc[OpenDirectory]
 **** xref:raddb/mods-available/passwd.adoc[Passwd]
+***** xref:raddb/mods-available/mac2ip.adoc[Mac2IP]
+***** xref:raddb/mods-available/mac2vlan.adoc[Mac2Vlan]
+***** xref:raddb/mods-available/smbpasswd.adoc[SMBPasswd]
 **** xref:raddb/mods-available/redis.adoc[REDIS]
 ***** xref:raddb/mods-available/redis_ippool.adoc[IP Pool]
 ***** xref:raddb/mods-available/rediswho.adoc[User tracking]
 **** xref:raddb/mods-available/rest.adoc[Rest]
-**** xref:raddb/mods-available/smbpasswd.adoc[SMBPasswd]
 **** xref:raddb/mods-available/sql.adoc[SQL]
+***** xref:raddb/mods-available/sqlcounter.adoc[Counter]
 ***** xref:raddb/mods-available/sqlippool.adoc[IP-Pool]
-**&** xref:raddb/mods-available/redundant_sql.adoc[Redundant]
+***** xref:raddb/mods-available/redundant_sql.adoc[Redundant]
 **** xref:raddb/mods-available/unix.adoc[Unix]
 
+*** xref:raddb/mods-available/doc/format.adoc[Formatting and Conversion]
+**** xref:raddb/mods-available/cipher.adoc[Cipher]
+**** xref:raddb/mods-available/date.adoc[Date]
+**** xref:raddb/mods-available/escape.adoc[Escape]
+**** xref:raddb/mods-available/json.adoc[JSON]
+**** xref:raddb/mods-available/unpack.adoc[Unpack]
+**** xref:raddb/mods-available/utf8.adoc[UTF-8]
+
 *** xref:raddb/mods-available/doc/language.adoc[Language]
 **** xref:raddb/mods-available/exec.adoc[Exec]
 ***** xref:raddb/mods-available/echo.adoc[Echo Example]
@@ -185,16 +197,8 @@
 *** xref:raddb/mods-available/doc/policy.adoc[Policy]
 **** xref:raddb/mods-available/always.adoc[Always]
 **** xref:raddb/mods-available/attr_filter.adoc[Attr_filter]
-**** xref:raddb/mods-available/cipher.adoc[Cipher]
-**** xref:raddb/mods-available/date.adoc[Date]
-**** xref:raddb/mods-available/delay.adoc[Delay]
-**** xref:raddb/mods-available/escape.adoc[Escape]
 **** xref:raddb/mods-available/idn.adoc[IDN]
-**** xref:raddb/mods-available/json.adoc[JSON]
 **** xref:raddb/mods-available/sometimes.adoc[Sometimes]
-**** xref:raddb/mods-available/sqlcounter.adoc[SQL Counter]
-**** xref:raddb/mods-available/unpack.adoc[Unpack]
-**** xref:raddb/mods-available/utf8.adoc[UTF-8]
 
 *** xref:raddb/mods-available/doc/protocol.adoc[Protocol]
 **** xref:raddb/mods-available/dhcpv4.adoc[DHCPv4]
@@ -205,8 +209,6 @@
 
 *** xref:raddb/mods-available/doc/utility.adoc[Utility]
 **** xref:raddb/mods-available/dict.adoc[Dict]
-**** xref:raddb/mods-available/mac2ip.adoc[Mac2IP]
-**** xref:raddb/mods-available/mac2vlan.adoc[Mac2Vlan]
 **** xref:raddb/mods-available/smtp.adoc[SMTP]
 **** xref:raddb/mods-available/stats.adoc[Stats]
 **** xref:raddb/mods-available/unbound.adoc[Unbound]

doc/antora/modules/reference/pages/raddb/mods-available/doc/authentication.adoc

@@ -1,31 +1,54 @@
 = Authentication Modules
 
-The authentication modules manages the verification processes by validating a set of credentials.  These modules are available for different types and methods of authentication. For example, RADIUS supports PAP, CHAP, or EAP protocols and multiple datastores like LDAP or local password file to verify a user's identity.
+The authentication modules verify user credentials.  They can do this
+by checking them against an external system, or by implementing an
+authentication protocol such as EAP.
+
+There are many different types and methods of authentication. For
+example, RADIUS supports PAP, CHAP, or EAP.  In many cases, datastores
+such as LDAP can be used to check a users name and password.
+
+In most cases, we recommend using a
+xref:raddb/mods-available/doc/datastore.adoc[datastore]
+(i.e. database) to store user credentials.  The server can then obtain
+the credentials from the datastore, and run the authentication method
+itself.
+
+In rare cases, the datastore will not return the users credentials to
+the server.  In that case, the server must send the users name and
+password to the datastore, where it authenticates the user and returns
+a "pass" or "fail" result.  This process almost always requires the
+user to supply the server with a clear-text password.  Other
+authentication methods such as CHAP or EAP will pretty much never work.
 
 The Authentication modules available are:
 
-xref:raddb/mods-available/chap.adoc[CHAP module]
+* xref:raddb/mods-available/chap.adoc[CHAP module] - CHAP authentication
 
-xref:raddb/mods-available/digest.adoc[Digest]
+* xref:raddb/mods-available/digest.adoc[Digest] - HTTP Digest Authentication
 
-xref:raddb/mods-available/eap.adoc[EAP]
+* xref:raddb/mods-available/eap.adoc[EAP] - EAP-MD5, EAP-MSCHAPv2, TTLS, PEAP, FAST, TEAP, etc.
 
-xref:raddb/mods-available/eap_inner.adoc[EAP/Inner]
+** xref:raddb/mods-available/eap_inner.adoc[EAP/Inner] - limit EAP methods to ones which can be used in an "inner tunnel".
 
-xref:raddb/mods-available/imap.adoc[IMAP]
+* xref:raddb/mods-available/imap.adoc[IMAP] - check user credentials against an IMAP server
 
-xref:raddb/mods-available/krb5.adoc[Kerberos]
+* xref:raddb/mods-available/krb5.adoc[Kerberos] - check user credentials against a Kerberos server
 
-xref:raddb/mods-available/mschap.adoc[Microsoft CHAP authentication]
+* xref:raddb/mods-available/ldap.adoc[LDAP] - check user credentials against an LDAP server
 
-xref:raddb/mods-available/pap.adoc[PAP]
+* xref:raddb/mods-available/mschap.adoc[Microsoft CHAP] - MSCHAPv1 and MSCHAPv2 authentication.
 
-xref:raddb/mods-available/passwd.adoc[Passwd]
+* xref:raddb/mods-available/ntlm_auth.adoc[NTLM Auth] - check user credentials against a Samba / Active Directory server
 
-xref:raddb/mods-available/totp.adoc[TOTP]
+* xref:raddb/mods-available/pam.adoc[Pluggable Authentication] - check user credentials against the Pluggable Authentication Method (PAM)
 
-xref:raddb/mods-available/wimax.adoc[WiMAX]
+* xref:raddb/mods-available/pap.adoc[PAP] - PAP authentication.  Supports all common password hashing / encryption methods.
 
-xref:raddb/mods-available/winbind.adoc[Winbind]
+* xref:raddb/mods-available/rest.adoc[REST] - check user credentials against a REST server
 
-xref:raddb/mods-available/yubikey.adoc[Yubikey]
+* xref:raddb/mods-available/totp.adoc[TOTP] - perform time-based one-time-password (TOTP) checks.
+
+* xref:raddb/mods-available/winbind.adoc[Winbind] - check user credentials against a Samba / Active Directory server
+
+* xref:raddb/mods-available/yubikey.adoc[Yubikey] - check user credentials against a Yubikey server or database.

doc/antora/modules/reference/pages/raddb/mods-available/doc/datastore.adoc

@@ -1,33 +1,59 @@
 = Datastore Modules
 
-Datastore modules are utilized to access and store your network information in a database or remote datastore.
+Datastore modules store data.  In most cases, they are databases.  We
+use the term "datastore" to mean that some of the storage methods are
+not traditional databases, but they do still store data.
+
+For example, the xref:raddb/mods-available/files.adoc[files] module
+implements the widely-used RADIUS
+xref:raddb/mods-config/files/users.adoc[users] file format.  It is not
+a database, but it can store thousands or millions of user
+credentials.
 
 The available Datastore modules are:
 
-xref:raddb/mods-available/cache.adoc[Cache]
+* xref:raddb/mods-available/cache.adoc[Cache] - cache data to local disk, memcached, or redis
+
+** xref:raddb/mods-available/cache_eap.adoc[Cache EAP] - example of caching EAP sessions
+
+** xref:raddb/mods-available/cache_tls.adoc[Cache TLS Session] - example of caching TLS sessions
+
+* xref:raddb/mods-available/client.adoc[Client] - read client definitions dynamically from text files
+
+* xref:raddb/mods-available/csv.adoc[CSV] - read data from a CSV file
+
+* xref:raddb/mods-available/etc_group.adoc[etc_group] - read data from `/etc/group`, or similarly formatted files
+
+* xref:raddb/mods-available/files.adoc[Files] - read data from the `users` file.
+
+* xref:raddb/mods-config/files/users.adoc[Users File Format] - format of the `users` file
+
+* xref:raddb/mods-available/ldap.adoc[LDAP] - connect to an LDAP server
+
+* xref:raddb/mods-available/opendirectory.adoc[OpenDirectory] - connect to an OpenDirectory server
 
-xref:raddb/mods-available/cache_eap.adoc[Cache EAP]
+* xref:raddb/mods-available/passwd.adoc[Passwd] - read data from `/etc/passwd`, or similarly formatted files
 
-xref:raddb/mods-available/cache_tls.adoc[Cache TLS Session]
+** xref:raddb/mods-available/mac2ip.adoc[Mac2IP] - example of using the `passwd` module to lookup up IP address by MAC address
 
-xref:raddb/mods-available/client.adoc[Client]
+** xref:raddb/mods-available/mac2vlan.adoc[Mac2Vlan] - example of using the `passwd` module to lookup up VLAN by MAC address
 
-xref:raddb/mods-available/csv.adoc[CSV]
+** xref:raddb/mods-available/smbpasswd.adoc[SMBPasswd] - read data from `/etc/smbpasswd`
 
-xref:raddb/mods-available/ldap.adoc[LDAP]
+* xref:raddb/mods-available/redis.adoc[Redis] - connect to a Redis server
 
-xref:raddb/mods-available/opendirectory.adoc[OpenDirectory]
+** xref:raddb/mods-available/redis_ippool.adoc[Redis IP Pool] - manages IP pools in Redis
 
-xref:raddb/mods-available/pam.adoc[Pluggable Authentication]
+** xref:raddb/mods-available/rediswho.adoc[REDISWho] - manages online users in Redis
 
-xref:raddb/mods-available/redis.adoc[REDIS]
+* xref:raddb/mods-available/rest.adoc[Rest] - connect to a REST server
 
-xref:raddb/mods-available/redis_ippool.adoc[Redis IP Pool]
+* xref:raddb/mods-available/sql.adoc[SQL] - connect to an SQL server
 
-xref:raddb/mods-available/rediswho.adoc[REDISWho]
+** xref:raddb/mods-available/sqlcounter.adoc[Counter] - track user activity (time / bandwidth) in SQL
 
-xref:raddb/mods-available/sql.adoc[SQL]
+** xref:raddb/mods-available/sqlippool.adoc[IP-Pool] - manages IP pools in SQL
 
-xref:raddb/mods-available/sqlippool.adoc[SQL-IP-Pool]
+** xref:raddb/mods-available/redundant_sql.adoc[Redundant] - example of using redundant connections to an SQL sercer
 
-xref:raddb/mods-available/unix.adoc[Unix]
+* xref:raddb/mods-available/unix.adoc[Unix] - read passwords from `getpwent()`

doc/antora/modules/reference/pages/raddb/mods-available/doc/format.adoc

@@ -0,0 +1,14 @@
+= Formatting and Conversion Modules
+
+The formatting and conversion modules allow the server to read and
+write data in different formats.
+
+* xref:raddb/mods-available/cipher.adoc[Cipher] - encrypt or decrypt data
+
+* xref:raddb/mods-available/date.adoc[Date] - parse or print dates in specific formats
+
+* xref:raddb/mods-available/escape.adoc[Escape] - escape or un-escape strings
+
+* xref:raddb/mods-available/unpack.adoc[Unpack] - decode binary data from octet strings
+
+* xref:raddb/mods-available/utf8.adoc[UTF-8] - check and enforce UTF8 encoding for strings

doc/antora/modules/reference/pages/raddb/mods-available/doc/language.adoc

@@ -1,15 +1,29 @@
 = Language Modules
 
-Language modules are embedded with the RADIUS server to allow an administrator to extend the capabilities of with extra progamming languages.
+Language modules allow an administrator to use different languages within the server.
+
+If the policies require basic if / then / else checks, or they require
+simple attribute editing, we recommend using the
+xref:unlang/index.adoc[Unlang Policy Language].  It is good enough for
+nearly all common use-cases, and it is much faster than any of the
+language modules.
+
+The _only_ reason to use one of these language modules is when you
+need to connect to an external API, and the API connector is a library
+which is only available as a language-specific library.  In every
+other case, xref:unlang/index.adoc[Unlang] will be simpler, and
+faster.
 
 The available Language modules are:
 
-* xref:raddb/mods-available/exec.adoc[Exec]
+* xref:raddb/mods-available/exec.adoc[Exec]- run external programs or shell scripts
+
+** xref:raddb/mods-available/echo.adoc[Echo] - example of using `echo`
 
-* xref:raddb/mods-available/lua.adoc[Lua]
+* xref:raddb/mods-available/lua.adoc[Lua] - run Lua programs
 
-* xref:raddb/mods-available/perl.adoc[Perl]
+* xref:raddb/mods-available/perl.adoc[Perl] - run Perl programs
 
-* xref:raddb/mods-available/python.adoc[Python]
+* xref:raddb/mods-available/python.adoc[Python] - run Python programs
 
-* xref:raddb/mods-available/mruby.adoc[Ruby]
+* xref:raddb/mods-available/mruby.adoc[Ruby] - run Ruby programs

doc/antora/modules/reference/pages/raddb/mods-available/doc/logging.adoc

@@ -1,17 +1,15 @@
-= IO Modules
+= Logging Modules
 
-The IO modules are used to help configure and transmit data.
+The logging modules write data to external destinations such as files, syslog, etc.
 
-The available IO modules are:
+The available Logging modules are:
 
-* xref:raddb/mods-available/dict.adoc[Dict]
-* xref:raddb/mods-available/files.adoc[Files]
-* xref:raddb/mods-available/linelog.adoc[Linelog]
-* xref:raddb/mods-available/logtee.adoc[Logtee]
-* xref:raddb/mods-available/detail.adoc[Detail]
-** xref:raddb/mods-available/detail.example.com.adoc[Detail Sample]
-** xref:raddb/mods-available/detail.log.adoc[Detail Log Sample]
-* xref:raddb/mods-available/radius.adoc[Radius]
-* xref:raddb/mods-available/rest.adoc[Rest]
-* xref:raddb/mods-available/stats.adoc[Stats]
-* xref:raddb/mods-available/unbound.adoc[Unbound]
+* xref:raddb/mods-available/linelog.adoc[Linelog] - log single lines to syslog, UDP, TCP, etc.
+
+** xref:raddb/mods-available/logtee.adoc[Logtee] - log to multiple destinations
+
+* xref:raddb/mods-available/detail.adoc[Detail] - log packets in the RADIUS "detail" file format
+
+** xref:raddb/mods-available/detail.example.com.adoc[Detail Sample] - example of writing detail files by date
+
+** xref:raddb/mods-available/detail.log.adoc[Detail Log Sample] - example of logging different packets to different files

doc/antora/modules/reference/pages/raddb/mods-available/doc/policy.adoc

@@ -1,29 +1,15 @@
 = Policy Modules
 
-These modules are used to implement different policies to manage data transmission, storage, server configs and behaviors.
+These modules are used to implement different policies to manage data
+transmission, storage, server configs and behaviors.
 
 The available Policy modules are:
 
-* xref:raddb/mods-available/always.adoc[Always]
+* xref:raddb/mods-available/always.adoc[Always] - always return a value (can be programattically changed!)
 
-* xref:raddb/mods-available/attr_filter.adoc[Attr_filter]
+* xref:raddb/mods-available/attr_filter.adoc[Attribute filter] - filter replies so that they contain only limited data
 
-* xref:raddb/mods-available/cipher.adoc[Cipher]
+* xref:raddb/mods-available/idn.adoc[IDN] - convert internationalized strings to DNS "punycode" encoding.
 
-* xref:raddb/mods-available/date.adoc[Date]
+* xref:raddb/mods-available/sometimes.adoc[Sometimes] - randomly succeed or fail.  Mostly used for testing.
 
-* xref:raddb/mods-available/delay.adoc[Delay]
-
-* xref:raddb/mods-available/escape.adoc[Escape]
-
-* xref:raddb/mods-available/idn.adoc[IDN]
-
-* xref:raddb/mods-available/json.adoc[JSON]
-
-* xref:raddb/mods-available/sometimes.adoc[Sometimes]
-
-* xref:raddb/mods-available/sqlcounter.adoc[SQL Counter]
-
-* xref:raddb/mods-available/unpack.adoc[Unpack]
-
-* xref:raddb/mods-available/utf8.adoc[UTF-8]

doc/antora/modules/reference/pages/raddb/mods-available/doc/protocol.adoc

@@ -1,7 +1,15 @@
 = Protocol Modules
 
+The protocol modules implement protocol-specific functionality.
+
 The available protocol modules are:
 
-* xref:raddb/mods-available/dhcpv4.adoc[DHCPv4]
+* xref:raddb/mods-available/dhcpv4.adoc[DHCPv4] - send DHCPv4 packets as a relay
+
+* xref:raddb/mods-available/isc_dhcp.adoc[ISC DHCP] - Read ISC DHCP configuration files
+
+* xref:raddb/mods-available/radius.adoc[Radius] - Proxy RADIUS packets
+
+** xref:raddb/mods-available/cui.adoc[CUI] - Manage Chargeable-User-Identifier
 
-* xref:raddb/mods-available/isc_dhcp.adoc[ISC DHCP]
+** xref:raddb/mods-available/wimax.adoc[WiMAX] - Fix WiMAX issues

doc/antora/modules/reference/pages/raddb/mods-available/doc/utility.adoc

@@ -1,5 +1,17 @@
 = Utility Modules
 
-The available utility modules are:
+The utility modules implement a wide range of functionality which
+cannot be placed into one of the other categories.
+
+* xref:raddb/mods-available/delay.adoc[Delay] - add a controlled delay to responses
+
+* xref:raddb/mods-available/dict.adoc[Dict] - look up dictionary entries by name
+
+* xref:raddb/mods-available/smtp.adoc[SMTP] - send email
+
+* xref:raddb/mods-available/stats.adoc[Stats] - gather internal server statistics
+
+* xref:raddb/mods-available/unbound.adoc[Unbound] - do asynchronous DNS lookips
+
+
 
-* xref:raddb/mods-available/smtp.adoc[SMTP]