clarifications and cleanups

doc/antora/modules/raddb/pages/format.adoc

@@ -62,38 +62,44 @@ be interpreted as being in the correct format.  For example, when a
 configuration variable is documented as taking an IP address, all of
 the following examples result in the same configuration:
 
-.Examples
+.Equivalent Configurations
+====
 ----
 ipaddr = 192.0.2.2
 ipaddr = '192.0.2.2'
 ipaddr = "  192.0.2.2"
 ----
+====
 
 === Unquoted Strings
 
 Unquoted strings delimited by spaces, or by other tokens.  This
 unquoted text is interpreted as a simple string and are generally
 equivalent to placing the string in single quotes.
 
-.Examples
+.Unquoted Strings
+====
 ----
 ipaddr = 192.168.0.2
 delay = 1
 locking = yes
 filename = /path/
 ----
+====
 
 === Single-Quoted Strings
 
 A single-quoted string allow it to contain spaces, among other
 special characters. The single quote character can be placed in such a
 string by escaping it with a backslash.
 
-.Examples
+.Single-Quoted Strings
+====
 ----
 message = 'Hello there'
 filter = 'yes \` is allowed`
 ----
+====
 
 === Double-Quoted Strings
 
@@ -108,6 +114,14 @@ see the <<Variable References>> section for more information.
 The contents of a double-quoted can be interpreted as a string, a
 number, or an IP address, depending on the configuration varible.
 
+.Double-Quoted Strings
+====
+----
+message = "Hello there"
+filter = "yes \" is allowed"
+----
+====
+
 === Escape sequences
 
 Escape sequences in double-quoted strings allow characters which may
@@ -136,6 +150,22 @@ A configuration section begins with a section name, followed on the
 same line by an open bracket `{`.  A section ends with a close bracket
 `}`.
 
+.Syntax
+----
+<name> [<instance>] {
+    [ statements ]
+}
+----
+
+<name>:: The name of this configuration section.  The set of allowed
+names depends on the context.
+
+<instance>:: An optional secton name.
+
+[ statements ]:: Zero or more statements, including comments, variable
+assignments, and other sections.
+
+
 .Configuration Section
 ====
 ----
@@ -191,7 +221,44 @@ This example will set the value of the variable `foo` to `blah blah
 blah`.  Any CR or LF is not turned into a space, but all other
 whitespace is preserved in the final value.
 
-=== Contents of the Configuration Files
+=== Including other files
+
+As noted above, the configuration is logically one global "server
+configuration", but is split up into multiple files on disk.  This
+splitting is done by the use of a `$INCLUDE` statement.
+
+.Syntax
+----
+$INCLUDE <filename>
+-$INCLUDE <filename>
+----
+
+$INCLUDE:: Key word to load the *<filename>*, and to fail if the file does
+not exist, or cannot be parsed
+
+-$INCLUDE:: Key word to load the *<filename>*, and to silently do
+nothing if the file does not exist.  If the file does exist, this
+keyword behaves exactly the same as `$INCLUDE`.
+
+<filename>:: The filename to include
++
+If *<filename>* begins with a `/` character, then it is
+assumed to be a full path to the file, starting at the "root"
+directory of the file system.
++
+If *<filename>* does not begin with a `/` character, then it is
+assumed to be a path relative to the current file being read.
+
+
+.Including other files
+====
+----
+foo = bar
+$INCLUDE other.conf
+----
+====
+
+=== Configuration as a Database
 
 The configuration file parser is independent of the server
 configuration. This means that you can put almost anything into the
@@ -226,9 +293,7 @@ examples.
 ====
 ----
 foo = bar       # set variable 'foo' to value 'bar'
-
 who = ${foo}    # sets variable 'who' to value of variable 'foo'
-
 my = "${foo} a" # sets variable 'my' to "bar a"
 ----
 ====
@@ -241,13 +306,16 @@ Relative references are allowed, by prepending the name with one or
 more periods.
 
 .References in the Current Section
+====
 ----
 foo = bar
 blogs = ${.foo}  # set 'blogs' to 'bar'
 ergo = "${foo}"  # set 'ergo' to 'bar'
 ----
+====
 
 .Parent References
+====
 ----
 group {
     foo = bar
@@ -256,15 +324,18 @@ group {
     }
 }
 ----
+====
 
 Will set variable `blogs` to the value `bar`.  That value is taken
 from the variable `foo`, which is contained in the a parent section
 of the section containing `blogs`
 
 .References to Other Sections
+====
 ----
 blogs = ${modules.detail.filename}
 ----
+====
 
 Will set variable `blogs` to the value of variable `filename`, of the
 `detail` module, which is in the `modules` section of the
@@ -275,37 +346,43 @@ using a `:` after the section reference.  Currently `:name` and `:instance`
 are supported.
 
 .References to the Name of a Section
+====
 ----
 modules {
     example foo {
         file = ${.:name}
     }
 }
 ----
+====
 
 Will set variable `file` to the name of the containing section, in
 this case, `example`.
 
 .References to the Instance of a Section
+====
 ----
 modules {
     example foo {
         file = ${.:instance}
     }
 }
 ----
+====
 
 Will set variable `file` to the instance name of the containing
 section, in this case `foo`.
 
 .Combining References
+====
 ----
 modules {
     example foo {
         file = ${..:name}
     }
 }
 ----
+====
 
 Will set variable `file` to the name of the parent of the containing
 section, in this case `modules`.
@@ -314,11 +391,12 @@ A string can contain multiple references, which will all be
 expanded.
 
 .Multiple References
+====
 ----
 foo = bar
 baz = bug
 blogs = "this ${foo} is ${baz}"
 ----
+====
 
 Will set variable `blogs` to the string `this bar is bug`.
-x

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

@@ -1,56 +1,39 @@
-= Welcome to Version 4.0 of FreeRADIUS
+= Configuration Files
 
 This section documents the format and content of the configuration
 files.
 
-== Configuring the server
+== Format and Layout
 
-When configuring the server, please start with the default
-configuration. It is intended to work in the widest possible
-circumstances, with minimal site-local changes. Most sites can just
-configure a few modules such as `ldap` and `sql`, and the server
-will do everything you need. More complex configurations require more
-effort, of course.
-
-For more complex configurations, the best approach is to make a series
-of small changes. Start the server after every change via
-`radiusd -XC` to see if the configuration is OK. Use `radclient` to
-send the server test packets. Read the debug output (`radiusd -X`) to
-verify that the server is doing what you expect.
+The configuration files are in a simple text-based
+xref:format.adoc[format].  They are loaded once when the server
+starts, and then are static for the duration of the server.  Changes
+to the configuration file are picked up only when the server restarts.
 
-For complex policies, it is best to write down what you want in plain
-English. Be specific. Write down what the server receives in a packet,
-which databases are used, and what the database should return. The more
-detailed these explanations, the easier it will be to create a working
-configuration.
+The configuration files are organized into groups, generally by
+directory, as discussed below.
 
-Take your time. It is better to make small incrementatal progress, than
-to make massive changes, and then to spend weeks debugging it.
-
-== Organization
+=== radiusd.conf
 
-The files in this directory are organized into logical groups, as
-follows.
+The xref:radiusd.conf.adoc[radiusd.conf] file is the main server
+configuration file.  When the server starts, it reads this file.  This
+file then loads all of the other configuration files.
 
-* `mods-available/`  - <<mods-available/README.adoc#,Available modules>>, with example configuration.
-* `mods-enabled/`    - Enabled modules that are being used by FreeRADIUS.
-* `sites-available/` - xref:raddb:sites-available/index.adoc[Available virtual servers], with example configuration.
-* `sites-enabled/`   - Enabled virtual servers that are being used by FreeRADIUS.
-* `policy.d/`        - example and live policies which implement standard rules and checks.
-* `certs/`           - Certificiates for EAP and for RADIUS over TLS.
+=== dictionary
 
-The directories are descrived in more detail below.
+Site-local dictionary entries are placed in the
+xref:dictionary.adoc[dictionary] file.
 
 === `mods-available/`
 
-The `mods-available/` directory contains configuration for all of the
-available modules. Each module configuration is different. Each file
-contains documentation that describes what the module is, and how it
-works.
+The xref:mods-available/index.adoc[mods-available/] directory contains
+configuration for all of the available modules. Each module
+configuration is different. Each file contains documentation that
+describes what the module is, and how it works.
 
-The directory contains almost 100 modules. Most configurations will only
-use a few modules. The rest exist in order to serve as documentation and
-worked examples.
+The directory contains almost 100 modules. Most configurations will
+only use a few modules. The remaining module configurations exist in
+order to serve as documentation and worked examples.
 
 === `mods-enabled/`
 
@@ -94,14 +77,18 @@ policies are loaded by the server, and unused ones are ignored.
 === `sites-available/`
 
 The `sites-available/` directory contains virtual servers which
-process packets. They are similar to the virtual servers used by Apache
-or Nginx.
+process packets. They are similar in concept to the virtual servers
+used by Apache and Nginx.
 
-Each virtual server will begin with a `server` declaration, along with it’s name. e.g. `server default { ...`. The declaration is then followed by a `namespace =` 
-parameter, which describes which application protocol is being used in that virtual server.
+Each virtual server will begin with a `server` declaration, along with
+it’s name. e.g. `server default { ...`. The declaration is then
+followed by a `namespace =` parameter, which describes which
+application protocol is being used in that virtual server.
 e.g. `namespace = radius`.
 
-The virtual server will then contain zero or more `listen` subsections. Each `listen` subsection defines a network socket which is used to receive packets.
+The virtual server will then contain zero or more `listen`
+subsections. Each `listen` subsection defines a network socket which
+is used to receive packets.
 
 The virtual server will then contain multiple `recv { ... }` and `send { ... }`
 subsections. These subsections are used to process packets.
@@ -135,16 +122,40 @@ The standard installation of FreeRADIUS enables only a few virtual servers.
 
 === `certs/`
 
-This directory contains certificates and configuration for EAP and RADIUS over TLS (i.e. RadSec).
+This directory contains certificates and configuration for EAP and
+RADIUS over TLS (i.e. RadSec).
+
+== Additional Configuration Files
+
+* xref:clients.conf.adoc[clients.conf]
+* xref:debug.conf.adoc[debug.conf]
+* xref:experimental.conf.adoc[experimental.conf]
+* xref:panic.gdb.adoc[panic.gdb]
+* xref:radrelay.conf.adoc[radrelay.conf]
+* xref:templates.conf.adoc[templates.conf]
+* xref:trigger.conf.adoc[trigger.conf]
 
-== List of config files
+== Changing the Configuration
+
+When configuring the server, please start with the default
+configuration. It is intended to work in the widest possible
+circumstances, with minimal site-local changes. Most sites can just
+configure a few modules such as `ldap` and `sql`, and the server
+will do everything you need. More complex configurations require more
+effort, of course.
+
+For more complex configurations, the best approach is to make a series
+of small changes. Start the server after every change via
+`radiusd -XC` to see if the configuration is OK. Use `radclient` to
+send the server test packets. Read the debug output (`radiusd -X`) to
+verify that the server is doing what you expect.
+
+For complex policies, it is best to write down what you want in plain
+English. Be specific. Write down what the server receives in a packet,
+which databases are used, and what the database should return. The more
+detailed these explanations, the easier it will be to create a working
+configuration.
+
+Take your time. It is better to make small incrementatal progress, than
+to make massive changes, and then to spend weeks debugging it.
 
-* xref:raddb:clients.conf.adoc[clients.conf]
-* xref:raddb:debug.conf.adoc[debug.conf]
-* xref:raddb:dictionary.adoc[dictionary]
-* xref:raddb:experimental.conf.adoc[experimental.conf]
-* xref:raddb:panic.gdb.adoc[panic.gdb]
-* xref:raddb:radiusd.conf.adoc[radiusd.conf]
-* xref:raddb:radrelay.conf.adoc[radrelay.conf]
-* xref:raddb:templates.conf.adoc[templates.conf]
-* xref:raddb:trigger.conf.adoc[trigger.conf]