From: Alan T. DeKok <aland@freeradius.org>
Date: Tue, 26 Sep 2023 18:17:16 +0000 (-0400)
Subject: Documentation for things helps rather a lot.
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ad98c8330863418b505d879f079bd7fc98074719;p=thirdparty%2Ffreeradius-server.git

Documentation for things helps rather a lot.
---

diff --git a/doc/antora/modules/raddb/nav.adoc b/doc/antora/modules/raddb/nav.adoc
index 1e7cea64167..664f86c7967 100644
--- a/doc/antora/modules/raddb/nav.adoc
+++ b/doc/antora/modules/raddb/nav.adoc
@@ -3,6 +3,10 @@
 
 ** xref:certs/index.adoc[Certificates]
 
+** xref:global.d/index.adoc[Global Configuration]
+** xref:global.d/ldap.adoc[ldap]
+** xref:global.d/python.adoc[ldap]
+
 ** xref:mods-available/index.adoc[Modules]
 *** xref:mods-available/all_modules.adoc[Module List]
 *** xref:mods-available/abfab_psk_sql.adoc[ADFAB PSK Module]
diff --git a/doc/antora/modules/raddb/pages/global.d/index.adoc b/doc/antora/modules/raddb/pages/global.d/index.adoc
new file mode 100644
index 00000000000..1cdc2fbf9d7
--- /dev/null
+++ b/doc/antora/modules/raddb/pages/global.d/index.adoc
@@ -0,0 +1,21 @@
+= Global Configuration Items
+
+Some modules have configuration which is _global_ to the server.
+
+For example, the xref:mods-available/python.adoc[python] module has
+the Python path set once for the server.  Due to how the underlying
+Python APIs are written, this path cannot be configured on a
+per-module basis.  If the configuration items were instead placed in
+each module, then the settings could conflict, and the server would
+have unpredictable behavior.
+
+As a result, some modules have additional configuration items which
+are in the `global.d` directory.  That way the settings are configured
+once, and not in each module.
+
+[options="header"]
+[cols="20%,80%"]
+|=====
+| Configuration | Description
+| xref:global.d/ldap.adoc[ldap]         | LDAP debugging flags
+| xref:global.d/python.adoc[python]	| Python path variables
diff --git a/doc/antora/modules/raddb/pages/global.d/ldap.adoc b/doc/antora/modules/raddb/pages/global.d/ldap.adoc
new file mode 100644
index 00000000000..b6745e91738
--- /dev/null
+++ b/doc/antora/modules/raddb/pages/global.d/ldap.adoc
@@ -0,0 +1,52 @@
+
+random_file:: Provides random number generator.
+
+
+
+ldap_debug:: Debug flags for libldap (see OpenLDAP documentation).
+Set this to enable debugging output from different code areas within libldap.
+
+NOTE: These debugging options can produce significant amounts of logging output.
+
+[options="header,autowidth"]
+|===
+| Option             | Value
+| LDAP_DEBUG_TRACE   | 0x0001
+| LDAP_DEBUG_PACKETS | 0x0002
+| LDAP_DEBUG_ARGS    | 0x0004
+| LDAP_DEBUG_CONNS   | 0x0008
+| LDAP_DEBUG_BER     | 0x0010
+| LDAP_DEBUG_FILTER  | 0x0020
+| LDAP_DEBUG_CONFIG  | 0x0040
+| LDAP_DEBUG_ACL     | 0x0080
+| LDAP_DEBUG_STATS   | 0x0100
+| LDAP_DEBUG_STATS2  | 0x0200
+| LDAP_DEBUG_SHELL   | 0x0400
+| LDAP_DEBUG_PARSE   | 0x0800
+| LDAP_DEBUG_SYNC    | 0x4000
+| LDAP_DEBUG_NONE    | 0x8000
+| LDAP_DEBUG_ANY     | (-1)
+|===
+
+e.g:
+
+If you want to see the LDAP logs only for `trace` and `parse`,
+facilities you should use:
+
+  (LDAP_DEBUG_TRACE + LDAP_DEBUG_PARSE) = 0x0801
+
+Setting the `ldap_debug` configuration item as follows:
+
+   ldap_debug = 0x0801
+
+Default: 0x0000 (no debugging messages)
+
+
+== Default Configuration
+
+```
+ldap {
+#	random_file = /dev/urandom
+	ldap_debug = 0x0000
+}
+```
diff --git a/doc/antora/modules/raddb/pages/global.d/python.adoc b/doc/antora/modules/raddb/pages/global.d/python.adoc
new file mode 100644
index 00000000000..24c335a81b4
--- /dev/null
+++ b/doc/antora/modules/raddb/pages/global.d/python.adoc
@@ -0,0 +1,22 @@
+
+path::
+
+The search path for Python modules.  It must include the path to your
+Python module.
+
+
+
+path_include_default::
+
+If "yes", retain the default search path.  Any additional search
+path components will be prepended to the the default search path.
+
+
+== Default Configuration
+
+```
+python {
+#	path = ${modconfdir}/${.:name}
+#	path_include_default = "yes"
+}
+```