add more documentation

doc/antora/modules/howto/nav.adoc

@@ -1,5 +1,6 @@
 * xref:index.adoc[Howto Guides]
 ** xref:modules/index.adoc[Modules]
+*** xref:modules/configuring_modules.adoc[Configuring Modules]
 *** xref:modules/RADIUS-LDAP-eDirectory.adoc[RADIUS-LDAP-eDirectory]
 *** xref:modules/eap.adoc[EAP]
 *** xref:modules/expiration.adoc[Expiration]

doc/antora/modules/howto/pages/modules/configuring_modules.adoc

@@ -0,0 +1,117 @@
+= Configuring a Module
+
+The configuration files in
+xref:raddb:mods-available/index.adoc[mods-available/] file describe
+the configuration parameters accepted by each module, and what they
+do.  This document explains how to perform generic testing with any
+module.
+
+The default server configuration should be tested via the following command:
+
+[source,shell]
+----
+radiusd -XC
+----
+
+If the configuration is correct, then the server will print the
+following message:
+
+[source,log]
+----
+Configuration appears to be OK
+----
+
+If that message does not appear, then it is necessary to correct any
+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
+
+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
+
+A module is enabled by creating a soft link from the `mods-enabled/`
+directory to the `mods-available/` directory.
+
+[source,shell]
+----
+cd raddb/mods-enabled && ln -s ../mods-available/MODULE
+----
+
+Where `MODULE` is the name of the module that is being enabled.
+
+It is also possible to copy the `mods-available/MODULE` default
+configuration file to `mods-enabled/MODULE`, and then edit that file.
+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
+
+The configuration of the server can be tested for syntactical
+correctness via the following command:
+
+[source,shell]
+----
+radiusd -XC
+----
+
+When the configuration is correct, then the server will print the
+following message:
+
+[source,log]
+----
+Configuration appears to be OK
+----
+
+Note that this test checks only that the configuration files can be
+parsed.  It does not check that the LDAP server can be reached.
+
+When the configuration is correct, FreeRADIUS can then be started in debugging mode:
+
+[source,shell]
+----
+radiusd -X
+----
+
+If the `ldap` module has been configured correctly, the final (or
+almost final) message will be
+
+[source,log]
+----
+Ready to process requests
+----
+
+This message should be in bold on the console.  Depending on which
+other modules are enabled, there may be a small number messages after
+this one.
+
+If the server starts, then the next step is then to perform
+module-specific tests.  Please see the individual module "howto" page
+for more information.
+
+=== Errors
+
+If the 'Ready to process requests` message does not appear, then the
+debug output will contain error messages clearly describing what went
+wrong.  These error message *must* be read in order to gain insight as
+to the source of the problem.
+
+Otherwise, look for messages containing `ERROR` or `WARNING`, or for
+the module name.  While the server can produce a large volume of
+messages, most of those can be ignored when debugging a particular
+problem.  Simply search for a few key strings based on the files you
+changed, and the solution to the problem should be clear.
+
+We recommend running the `radiusd -XC` test was performed before
+making any module changes for other reasons.  If previous
+configuration worked, and the only change was to a particular module,
+then the source of the error is simple.  There is no need to go
+searching through other configuration files or third-party web sites.
+Instead, change and test the module configuration until the server
+works.

doc/antora/modules/howto/pages/modules/ldap.adoc

@@ -165,6 +165,7 @@ On the FreeRADIUS debug terminal side, you should see something like:
 
 [source,log]
 ----
+...
 (0)    ldap - Reserved connection (0)
 (0)    ldap - EXPAND (uid=%{%{Stripped-User-Name}:-%{User-Name}})
 (0)    ldap - --> (uid=john)
@@ -175,8 +176,7 @@ On the FreeRADIUS debug terminal side, you should see something like:
 (0)    ldap -   &control:Password-With-Header += password
 (0)    ldap - Released connection (0)
 (0)    ldap (updated)
-(0)    expiration (noop)
-(0)    logintime (noop)
+...
 (0)    pap - No {...} in &Password-With-Header, re-writing to Cleartext-Password
 (0)    pap - Normalized &control:Password-With-Header -> &control:Cleartext-Password
 (0)    pap - Removing &control:Password-With-Header
@@ -191,6 +191,7 @@ On the FreeRADIUS debug terminal side, you should see something like:
 (0)    pap (ok)
 (0)  } # authenticate pap (ok)
 (0)  Running 'send Access-Accept' from file /usr/local/etc/raddb/sites-enabled/default
+...
 ----
 
 Here FreeRADIUS is describing what it did:

doc/antora/modules/howto/pages/modules/ldap_configuration.adoc

@@ -1,56 +1,167 @@
 = Configuring the LDAP module
 
-As with all FreeRADIUS configuration files, when starting off you
-should try to change at little as possible.  The (business logic)
-defaults are usually what you want, and all you need to do is amend
-where FreeRADIUS should look for data.
+The xref:raddb:mods-available/ldap.adoc[ldap module] configuration
+file describes the configuration parameters accepted by the module,
+and what they do.  This document explains how to perform testing with
+the LDAP module.
 
-Before configuring the LDAP module, the LDAP queries should be
-validated via the xref:modules/ldap_search.adoc[`ldapsearch`]
+Before configuring the LDAP module, the LDAP parameters should first
+be validated via the xref:modules/ldap_search.adoc[`ldapsearch`]
 command-line tool.
 
-== Stuff
-
- . start with the default `raddb` configuration
- ** it is really difficult for the mailing list to provide assistance if you do not start with the defaults!
- . edit the `ldap { ... }` section in `/usr/local/etc/raddb/mods-available/ldap` with your findings from the pre-flight section
- ** *server:* use the URI form (for example `ldap://192.0.2.1`) to describe where your LDAP server is
- ** *identity:* use the (preferably non-admin read only) account DN here (eg. `cn=readonly,dc=example,cn=com`)
- ** *password:* use the password associated with the identity account
- ** *base_dn:* provide the base of your LDAP database here (eg. `dc=example,dc=com`)
- ** in the `user { ... }` section
- *** check that `filter` can match your users when searched for
- ** in the `group { ... }` section
- *** check that `filter` can match your groups when searched for
- **** for Active Directory you may need to use `(objectClass=group)` instead
- *** referring to your notes above on how your LDAP server handles authorization, if it uses the LDAP attribute in:
- **** *a dedicated group object (ie. `member`):* uncomment `membership_filter` and possibility amend the value
- **** *the user object (ie. `memberOf`):* check `membership_attribute` is set apprioately
- . enabled the LDAP module
+The default server configuration should also be tested via the following command:
+
+[source,shell]
+----
+radiusd -XC
+----
+
+If the configuration is correct, then the server will print the
+following message:
+
+[source,log]
+----
+Configuration appears to be OK
+----
+
+If that message does not appear, then it is necessary to correct any
+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/ldap
+
+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.
+
+If the xref:modules/ldap_search.adoc[`ldapsearch`] tests above pass,
+then the LDAP module configuration can be copied directly from the
+command-line options to that tool:
+
+[source,shell]
+----
+ldapsearch -D ${identity} -w ${password} -h ${server} -b 'CN=user,${base_dn}' '${filter}' '*'
+----
+
+Where we have the following configuration paramters:
+
+`${identity}`::
+The information going into the `identity` configuration item of the LDAP module.
++
+This identity should be a read-only, non-administrator account.
+
+`${password}`::
+The information going into the `password` configuration item of the LDAP module.
+
+`${server}`::
+The information going into the `server` configuration item of the LDAP module.
 +
+This information could also be taken from the URI in the `-H`
+command-line option.  We generally recommend using the URI form
+instead of a bare hostname.
+
+`${base_dn}`::
+The information going into the `base_dn` configuration item of the LDAP module.
++
+This is ususally something like `dc=example,dc=com`
+
+`${filter}`::
+The information going into the `filter` configuration item of the LDAP module.
++
+The `filter` configuration item is located inside of the `user { ... }` section/
+
+We do _not_ recommend immediately configuring TLS.  The best approach
+is to test one piece in isolation, before proceeding on to the next
+piece.
+
+
+== Enabling mods-available/ldap
+
+The `ldap` module is enabled by creating a soft link from the
+`mods-enabled/` directory to the `mods-available/` directory.
+
 [source,shell]
 ----
 cd raddb/mods-enabled && ln -s ../mods-available/ldap
 ----
- . start FreeRADIUS, initially in debugging mode
-+
+
+It is also possible to copy the `mods-available/ldap` default
+configuration file to `mods-enabled/ldap`, and then edit that file.
+This process leaves the original `mods-available/ldap` 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
+
+The configuration of the server can be tested for syntactical
+correctness via the following command:
+
+[source,shell]
+----
+radiusd -XC
+----
+
+When the configuration is correct, then the server will print the
+following message:
+
+[source,log]
+----
+Configuration appears to be OK
+----
+
+Note that this test checks only that the configuration files can be
+parsed.  It does not check that the LDAP server can be reached.
+
+When the configuration is correct, FreeRADIUS can then be started in debugging mode:
+
 [source,shell]
 ----
 radiusd -X
 ----
 
-If the configurtion is correct, then FreeRADIUS will start up with the
-message `Ready to process requests`.  Further tests
-(e.g. authentication) should only be done if this message appears.
+If the `ldap` module has been configured correctly, the final (or
+almost final) message will be
+
+[source,log]
+----
+Ready to process requests
+----
+
+This message should be in bold on the console.  Depending on which
+other modules are enabled, there may be a small number messages after
+this one.
+
+If the server starts, then the next step is then to test LDAP module
+with the xref:modules/ldap_authentication.adoc[authentication]
+process.
+
+=== Errors
 
 If the 'Ready to process requests` message does not appear, then the
 debug output will contain error messages clearly describing what went
-wrong.  These error message *must* be read in order to gain insight
-about the problem.
+wrong.  These error message *must* be read in order to gain insight as
+to the source of the problem.
 
 For example, the message `Can't contact LDAP server` means that there
 is a connection issue between the RADIUS server and the LDAP
 database. or that the LDAP module configuration is incorrect.  The
-xref:modules/ldap_search.adoc[`ldapsearch`] validation tests should
-then be performed in order to verify both the connection, and the
+xref:modules/ldap_search.adoc[`ldapsearch`] validation tests must then
+be performed in order to verify both the connection, and the
 configuration parameters.
+
+Otherwise, look for messages containing `ERROR` or `WARNING` or
+`ldap`.  While the server can produce a large volume of messages, most
+of those can be ignored when debugging a particular problem.  Simply
+search for a few key strings based on the files you changed, and the
+solution to the problem should be clear.
+
+We recommend running the `radiusd -XC` test was performed before
+making any `ldap` module changes for other reasons.  If previous
+configuration worked, and the only change was to the `ldap` module,
+then the source of the error is simple.  There is no need to go
+searching through other configuration files or third-party web sites.
+Instead, change and test the module configuration until the server
+works.
+

doc/antora/modules/howto/pages/modules/ldap_search.adoc

@@ -9,7 +9,7 @@ on a third machine will not show any firewall issues.
 
 [source,shell]
 ----
-ldapsearch -H ldaps://ldap.example.com:686 -x -D cn=freeradius,dc=example,dc=com -w mypassword -b ou=people,dc=example,dc=com -z 10 '(objectClass=inetOrgPerson)' '*'
+ldapsearch -H ldaps://ldap.example.com:686 -x -D "cn=freeradius,dc=example,dc=com" -w mypassword -b "ou=people,dc=example,dc=com" -z 10 '(objectClass=inetOrgPerson)' '*'
 ----
 
 Where you replace the following as appropriately: