From: Matthew Newton Date: Tue, 30 Jan 2024 17:34:40 +0000 (+0000) Subject: doc: fix some antora issues X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=18205f841ac83a0e4cd1bc5df84b00609af72b20;p=thirdparty%2Ffreeradius-server.git doc: fix some antora issues --- diff --git a/doc/antora/modules/developers/pages/index.adoc b/doc/antora/modules/developers/pages/index.adoc index b2bb4cb95dd..fb916bb1ca2 100644 --- a/doc/antora/modules/developers/pages/index.adoc +++ b/doc/antora/modules/developers/pages/index.adoc @@ -20,7 +20,6 @@ https://doc.freeradius.org/[Doxygen] site. ** xref:sbuff.adoc[String buffers] (`sbuff` s) ** xref:sbuff-parsing.adoc[Parsing with string buffers] ** xref:sbuff-ng.adoc[Sbuff issues] -* xref:todo.adoc[TODO] Also see the xref:installation:dependencies.adoc[build dependencies] page. diff --git a/doc/antora/modules/raddb/pages/dictionary.adoc b/doc/antora/modules/raddb/pages/dictionary.adoc index 6c343ca9fd9..a755d036146 100644 --- a/doc/antora/modules/raddb/pages/dictionary.adoc +++ b/doc/antora/modules/raddb/pages/dictionary.adoc @@ -2,25 +2,31 @@ -We recommend using local variables inside of "unlang" sections -instead of defining attributes in this fine. See the reference documentation -for more information on local variables. +# Local dictionary definitions + +This is the local dictionary file which can be +edited by local administrators. It will be loaded + *after* the main dictionary files are loaded. -This file exists for two purposes: -1) defining local attributes in order to simplify the process of migrating - from version 3 to version 4. We recommend removing these attributes, - and using local variables instead. +NOTE: We recommend using local variables inside of "unlang" + sections instead of defining attributes in this file. See + the xref:reference:index.adoc[reference documentation] + for more information on + xref:reference:unlang/local.adoc[local variables]. -2) Including alias dictionaries in order to simplify the process of migrating - from version 3 to version 4. We recommend using the new names where possible. +This file exists for two purposes: -= Local dictionary definitions +1) defining local attributes in order to simplify the process + of migrating from version 3 to version 4. We recommend + removing these attributes, and using local variables instead. -This is the local dictionary file which can be -edited by local administrators. It will be loaded - *after* the main dictionary files are loaded. +2) Including alias dictionaries in order to simplify the + process of migrating from version 3 to version 4. We + recommend using the new names where possible. + +## Dictionary loading order FreeRADIUS will automatically load the main dictionary files from: @@ -59,7 +65,7 @@ Any attribute `DEFINE`d here will not go into a packet. If you do want attributes to go into a RADIUS packet, you will need to use VSAs. This means requesting allocation -of a Private Enterprise Code from http://iana.org/. We +of a Private Enterprise Code from https://www.iana.org/. We strongly suggest doing that *only* if you are a vendor of RADIUS equipment. diff --git a/doc/antora/modules/raddb/pages/radiusd.conf.adoc b/doc/antora/modules/raddb/pages/radiusd.conf.adoc index 2ffd1dc48d5..e6e759f259a 100644 --- a/doc/antora/modules/raddb/pages/radiusd.conf.adoc +++ b/doc/antora/modules/raddb/pages/radiusd.conf.adoc @@ -2,7 +2,7 @@ -= FreeRADIUS server configuration file - @RADIUSD_VERSION_STRING@ += FreeRADIUS server configuration file - 4.0 Read `man radiusd` before editing this file. See the section titled DEBUGGING. It outlines a method where you can quickly @@ -277,7 +277,7 @@ Suppress "secret" values when printing them in debug mode. Setting this to "yes" means that the server prints a series of dots: -....... + ....... instead of the value, for attributes which contain secret information. e.g. User-Name, Tunnel-Password, etc. diff --git a/doc/antora/modules/raddb/pages/sites-available/ldap_sync.adoc b/doc/antora/modules/raddb/pages/sites-available/ldap_sync.adoc index 84d3e330fc5..06d2e0c04e9 100644 --- a/doc/antora/modules/raddb/pages/sites-available/ldap_sync.adoc +++ b/doc/antora/modules/raddb/pages/sites-available/ldap_sync.adoc @@ -19,8 +19,9 @@ information or act on it. Note: Each of the three implementations of LDAP synchronisation behave differently: -https://tools.ietf.org/html/rfc4533[RFC 4533] --------- + +== https://tools.ietf.org/html/rfc4533[RFC 4533] + This provides a robust mechanism to allow clients to maintain a cached copy of a fragment of a directory by the use of cookies which can be returned to the server indicating the last successfully processed @@ -30,8 +31,9 @@ However, when an object is deleted from the directory, the entry which is received only contains the DN, or, if the deletion is reported as part of the initial refresh phase it may only be the UUID. -Active Directory ---------------- + +== Active Directory + Active Directory will only provide updates from the time the query started; there is no mechanism to catch up on changes which occurred while the client was not connected. In addition it is not possible to apply a @@ -42,7 +44,7 @@ has to be enabled on Active Directory and a query must be running which includes the Deleted Objects container. Active Directory will only perform persistent searches if the filter is -(objectClass=*). To overcome this limitation, FreeRADIUS allows other +`(objectClass=*)`. To overcome this limitation, FreeRADIUS allows other LDAP filters to be specified which are applied in FreeRADIUS before passing packets to the relevant processing sections. @@ -50,7 +52,7 @@ This implementation of LDAP filters is not intended to be complete, but covers the most likely to be required. One key limitation, due to not having the LDAP schema to interpret attribute -types, is that >=, <= and bitwise filters are assumed to be on integer values. +types, is that `>=`, `<=` and bitwise filters are assumed to be on integer values. If your Active Directory tree contains multiple domains, you will need a query for each domain that is of interest; running a query at the base @@ -61,8 +63,9 @@ Depending on the attributes of interest, the number of notifications of changes received can be reduced by running the LDAP query against the Global Catalog rather than the normal AD LDAP server. -Persistent Search ------------------ + +== Persistent Search + Servers implementing Persistent Search have the option to return the full directory contents, or simply start reporting changes from the point when the query was run. @@ -71,20 +74,20 @@ The draft says that servers SHOULD include a changeNumber when reporting changes to keep track of progress - however this has not been observed in any testing. If this is implemented, then it can behave in a similar manner to the cookie defined in https://tools.ietf.org/html/rfc4533[RFC 4533]; a search against the change log -with a filter of (changeNumber>=n) could be used to read changes since +with a filter of `(changeNumber>=n)` could be used to read changes since change number 'n'. -Note on user group membership ------------------------------ -Many directories provide a virtual memberOf attribute which lists +== Note on user group membership + +Many directories provide a virtual `memberOf` attribute which lists which groups a user is a member of. With the directories which have been tested, including OpenLDAP and -Active Directory it has been observed that modifying group member lists +Active Directory, it has been observed that modifying group member lists does not result in notification of changes to the users, even though other modifications to the user will result in a notification which -can include the memberOf attribute. +can include the `memberOf` attribute. Instead group membership changes are reported as changes to the group object. @@ -101,6 +104,7 @@ configuration items. + Local attributes which are used to cache results from LDAP diff --git a/doc/antora/modules/unlang/.gitignore b/doc/antora/modules/unlang/.gitignore deleted file mode 100644 index c5722d7c54f..00000000000 --- a/doc/antora/modules/unlang/.gitignore +++ /dev/null @@ -1 +0,0 @@ -!*.adoc diff --git a/raddb/dictionary b/raddb/dictionary index 1d36a709f30..0c984250306 100644 --- a/raddb/dictionary +++ b/raddb/dictionary @@ -5,26 +5,31 @@ ####################################################################### # -# We recommend using local variables inside of "unlang" sections -# instead of defining attributes in this fine. See the reference documentation -# for more information on local variables. +# # Local dictionary definitions # -# This file exists for two purposes: +# This is the local dictionary file which can be +# edited by local administrators. It will be loaded +# *after* the main dictionary files are loaded. # -# 1) defining local attributes in order to simplify the process of migrating -# from version 3 to version 4. We recommend removing these attributes, -# and using local variables instead. # -# 2) Including alias dictionaries in order to simplify the process of migrating -# from version 3 to version 4. We recommend using the new names where possible. +# NOTE: We recommend using local variables inside of "unlang" +# sections instead of defining attributes in this file. See +# the xref:reference:index.adoc[reference documentation] +# for more information on +# xref:reference:unlang/local.adoc[local variables]. # -####################################################################### # -# = Local dictionary definitions +# This file exists for two purposes: # -# This is the local dictionary file which can be -# edited by local administrators. It will be loaded -# *after* the main dictionary files are loaded. +# 1) defining local attributes in order to simplify the process +# of migrating from version 3 to version 4. We recommend +# removing these attributes, and using local variables instead. +# +# 2) Including alias dictionaries in order to simplify the +# process of migrating from version 3 to version 4. We +# recommend using the new names where possible. +# +# ## Dictionary loading order # # FreeRADIUS will automatically load the main dictionary files from: # @@ -63,7 +68,7 @@ # # If you do want attributes to go into a RADIUS packet, you # will need to use VSAs. This means requesting allocation -# of a Private Enterprise Code from http://iana.org/. We +# of a Private Enterprise Code from https://www.iana.org/. We # strongly suggest doing that *only* if you are a vendor of # RADIUS equipment. # diff --git a/raddb/radiusd.conf.in b/raddb/radiusd.conf.in index b03ccfdda82..87cd963cd0a 100644 --- a/raddb/radiusd.conf.in +++ b/raddb/radiusd.conf.in @@ -5,7 +5,7 @@ ####################################################################### # -# = FreeRADIUS server configuration file - @RADIUSD_VERSION_STRING@ +# = FreeRADIUS server configuration file - @RADIUSD_VERSION_MAJOR@.@RADIUSD_VERSION_MINOR@ # # Read `man radiusd` before editing this file. See the section # titled DEBUGGING. It outlines a method where you can quickly @@ -309,7 +309,7 @@ log { # Setting this to "yes" means that the server prints a series # of dots: # - # ....... + # ....... # # instead of the value, for attributes which contain secret # information. e.g. User-Name, Tunnel-Password, etc. @@ -455,8 +455,8 @@ security { # that it should be impossible to break out of the chroot. # # If you are worried about security issues related to this - # use of chdir, then simply ensure that the "raddb" directory - # is inside of the chroot, and be sure to do "cd raddb" + # use of chdir, then simply ensure that the `raddb` directory + # is inside of the chroot, and be sure to do `cd raddb` # BEFORE starting the server. # # If the server is statically linked, then the only files diff --git a/raddb/sites-available/ldap_sync b/raddb/sites-available/ldap_sync index 16dc7f27a8a..030ec651f11 100644 --- a/raddb/sites-available/ldap_sync +++ b/raddb/sites-available/ldap_sync @@ -21,8 +21,9 @@ # Note: Each of the three implementations of LDAP synchronisation behave # differently: # -# RFC 4533 -# -------- +# +# == RFC 4533 +# # This provides a robust mechanism to allow clients to maintain a # cached copy of a fragment of a directory by the use of cookies which # can be returned to the server indicating the last successfully processed @@ -32,8 +33,9 @@ # received only contains the DN, or, if the deletion is reported as part of # the initial refresh phase it may only be the UUID. # -# Active Directory -# --------------- +# +# == Active Directory +# # Active Directory will only provide updates from the time the query started; # there is no mechanism to catch up on changes which occurred while the # client was not connected. In addition it is not possible to apply a @@ -44,7 +46,7 @@ # includes the Deleted Objects container. # # Active Directory will only perform persistent searches if the filter is -# (objectClass=*). To overcome this limitation, FreeRADIUS allows other +# `(objectClass=*)`. To overcome this limitation, FreeRADIUS allows other # LDAP filters to be specified which are applied in FreeRADIUS before passing # packets to the relevant processing sections. # @@ -52,7 +54,7 @@ # covers the most likely to be required. # # One key limitation, due to not having the LDAP schema to interpret attribute -# types, is that >=, <= and bitwise filters are assumed to be on integer values. +# types, is that `>=`, `<=` and bitwise filters are assumed to be on integer values. # # If your Active Directory tree contains multiple domains, you will need a # query for each domain that is of interest; running a query at the base @@ -63,8 +65,9 @@ # changes received can be reduced by running the LDAP query against the # Global Catalog rather than the normal AD LDAP server. # -# Persistent Search -# ----------------- +# +# == Persistent Search +# # Servers implementing Persistent Search have the option to return the full # directory contents, or simply start reporting changes from the point when # the query was run. @@ -73,20 +76,20 @@ # changes to keep track of progress - however this has not been observed in # any testing. If this is implemented, then it can behave in a similar # manner to the cookie defined in RFC 4533; a search against the change log -# with a filter of (changeNumber>=n) could be used to read changes since +# with a filter of `(changeNumber>=n)` could be used to read changes since # change number 'n'. # # -# Note on user group membership -# ----------------------------- -# Many directories provide a virtual memberOf attribute which lists +# == Note on user group membership +# +# Many directories provide a virtual `memberOf` attribute which lists # which groups a user is a member of. # # With the directories which have been tested, including OpenLDAP and -# Active Directory it has been observed that modifying group member lists +# Active Directory, it has been observed that modifying group member lists # does not result in notification of changes to the users, even though # other modifications to the user will result in a notification which -# can include the memberOf attribute. +# can include the `memberOf` attribute. # # Instead group membership changes are reported as changes to the group object. #