From: nolade Date: Wed, 11 Jun 2025 14:23:55 +0000 (-0400) Subject: docs: v3-v4 markup with warning HIVE 3608 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=caa2e6745f9ff7bb5393fab35f3f79ec4104fd5d;p=thirdparty%2Ffreeradius-server.git docs: v3-v4 markup with warning HIVE 3608 --- diff --git a/doc/antora/modules/ROOT/nav.adoc b/doc/antora/modules/ROOT/nav.adoc index 46906a3bcce..253deb3c00c 100644 --- a/doc/antora/modules/ROOT/nav.adoc +++ b/doc/antora/modules/ROOT/nav.adoc @@ -1,8 +1,8 @@ * xref:index.adoc[Introduction] ** xref:getstarted.adoc[Getting Started] *** xref:debugging/radiusd_X.adoc[Debugging] -*** xref:debugging/startup.adoc[Startup ] -*** xref:debugging/processing.adoc[Processing Packets] +**** xref:debugging/startup.adoc[Startup Text] +**** xref:debugging/processing.adoc[Processing Packets] *** xref:gethelp.adoc[Getting Help] ** xref:bestpractices.adoc[Best Practices] *** xref:trouble-shooting/eap_certificates.adoc[EAP Certificates] diff --git a/doc/antora/modules/ROOT/pages/debugging/processing.adoc b/doc/antora/modules/ROOT/pages/debugging/processing.adoc index 2f4598a4239..70b36fc4350 100644 --- a/doc/antora/modules/ROOT/pages/debugging/processing.adoc +++ b/doc/antora/modules/ROOT/pages/debugging/processing.adoc @@ -1,4 +1,6 @@ -# Packet Processing +# Processing Packets + +include::ROOT:partial$v3_warning.adoc[] Each line (or most of them) of the packet processing output starts with a request number, e.g. `(0)`. This number lets you track debug messages which are all for one packet. Messages from different packets may be inter-mingled, due to threading or proxying. Prefixing the messages with a number allows the messages to be easily differentiated. diff --git a/doc/antora/modules/ROOT/pages/debugging/startup.adoc b/doc/antora/modules/ROOT/pages/debugging/startup.adoc index 0191bc6c9d9..692fc7420a8 100644 --- a/doc/antora/modules/ROOT/pages/debugging/startup.adoc +++ b/doc/antora/modules/ROOT/pages/debugging/startup.adoc @@ -1,5 +1,7 @@ # Startup text +include::ROOT:partial$v3_warning.adoc[] + We start the server with *`-X`*. This option gives us the best combination of useful output, and readable output. Adding more `-x` gives *more complex output*, not *more useful output*. $ radiusd -X 2>&1 | tee debugfile diff --git a/doc/antora/modules/ROOT/partials/v3_warning.adoc b/doc/antora/modules/ROOT/partials/v3_warning.adoc new file mode 100644 index 00000000000..ca5ce760ca7 --- /dev/null +++ b/doc/antora/modules/ROOT/partials/v3_warning.adoc @@ -0,0 +1,4 @@ +[WARNING] +==== +This section has NOT been updated for v4 and the information may be obsolete. Contact https://www.inkbridgenetworks.com/[InkBridge Networks] for more details. +==== diff --git a/doc/antora/modules/howto/nav.adoc b/doc/antora/modules/howto/nav.adoc index 226236b973f..57f3c3c5209 100644 --- a/doc/antora/modules/howto/nav.adoc +++ b/doc/antora/modules/howto/nav.adoc @@ -1,16 +1,16 @@ * xref:index.adoc[Howto Guides] -** xref:howto:installation/index.adoc[Installing and Upgrading] +** xref:howto:installation/index.adoc[Install and Upgrade] *** xref:howto:installation/dependencies.adoc[Dependencies] *** xref:howto:installation/packages.adoc[Install from Packages] *** xref:howto:installation/source.adoc[Build from Source] **** xref:howto:installation/debian.adoc[Debian and Ubuntu] **** xref:howto:installation/redhat.adoc[RedHat and Rocky] **** xref:howto:installation/osx.adoc[OSX] -*** xref:howto:installation/upgrade.adoc[Upgrading from v3 to v4] +*** xref:howto:installation/upgrade.adoc[Upgrade from v3 to v4] **** xref:howto:installation/attribute_names.adoc[Attribute Name Changes from v3 to v4] -** xref:modules/configuring_modules.adoc[Configuring Modules] +** xref:modules/configuring_modules.adoc[Configure Modules] *** xref:modules/chap/index.adoc[CHAP] *** xref:modules/eap/index.adoc[EAP] *** xref:modules/expiration/index.adoc[Expiration] diff --git a/doc/antora/modules/howto/pages/installation/index.adoc b/doc/antora/modules/howto/pages/installation/index.adoc index c32e9a668a5..0fb5c2073f6 100644 --- a/doc/antora/modules/howto/pages/installation/index.adoc +++ b/doc/antora/modules/howto/pages/installation/index.adoc @@ -98,7 +98,8 @@ include::partial$add_client.adoc[] ## Configure the Server - include::partial$config_server.adoc[] +include::partial$config_server.adoc[] + [WARNING] ==== diff --git a/doc/antora/modules/howto/pages/installation/packages.adoc b/doc/antora/modules/howto/pages/installation/packages.adoc index 8ee3729a1d6..a337678814d 100644 --- a/doc/antora/modules/howto/pages/installation/packages.adoc +++ b/doc/antora/modules/howto/pages/installation/packages.adoc @@ -1,5 +1,7 @@ == Install from packages +include::ROOT:partial$v3_warning.adoc[] + https://www.inkbridgenetworks.com/[InkBridge Networks] provides pre-built binary packages of FreeRADIUS for common Linux distributions. This is the recommended installation method when packages are available for your system. The official https://packages.inkbridgenetworks.com/[InkBridge Networks diff --git a/doc/antora/modules/howto/pages/installation/source.adoc b/doc/antora/modules/howto/pages/installation/source.adoc index 4911f1ebdc7..555f7a6c596 100644 --- a/doc/antora/modules/howto/pages/installation/source.adoc +++ b/doc/antora/modules/howto/pages/installation/source.adoc @@ -1,7 +1,6 @@ -== Building from Source +== Build from Source -We recommend xref:howto:installation/packages.adoc[installing from packages] if -possible. Full instructions on building and installing from source +We recommend that you xref:howto:installation/packages.adoc[install from packages] if possible. Full instructions on building and installing from source code follow. The hard xref:howto:installation/dependencies.adoc[dependencies] @@ -69,8 +68,7 @@ this may cause undesired behavior and failure to operate correctly. The initial output from running in xref:ROOT:debugging/radiusd_X.adoc[debugging mode] will tell you which configuration files are being used. See - xref:howto:installation/upgrade.adoc[upgrading] for information about -upgrading from older versions. There _may_ be changes in the + xref:howto:installation/upgrade.adoc[upgrade from v3 to v4] for more information. There _may_ be changes in the dictionary files which are required for a new version of the software. These files will not be installed over your current configuration, so you *must* verify and install any problem files by @@ -97,7 +95,7 @@ It is generally not possible to reuse configurations between different major versions of the server. For example - version 2 to version 3, or version 3 to version 4. -For details on what has changed between the version, see xref:howto:installation/upgrade.adoc[Upgrading from v3 to v4]. +For details on what has changed between the version, see xref:howto:installation/upgrade.adoc[upgrade from v3 to v4]. We _strongly_ recommend that new major versions be installed in a different location than any existing installations. Any local policies diff --git a/doc/antora/modules/howto/pages/installation/upgrade.adoc b/doc/antora/modules/howto/pages/installation/upgrade.adoc index 5f9842430d9..17c78133025 100644 --- a/doc/antora/modules/howto/pages/installation/upgrade.adoc +++ b/doc/antora/modules/howto/pages/installation/upgrade.adoc @@ -1,4 +1,4 @@ -= Upgrading from v3 to v4 += Upgrade from v3 to v4 The configuration for v4 is _somewhat_ compatible with the v3 configuration. It should be possible to reuse most of a v3 diff --git a/doc/antora/modules/howto/pages/modules/configuring_modules.adoc b/doc/antora/modules/howto/pages/modules/configuring_modules.adoc index b02122b2b23..a95c3cb8e20 100644 --- a/doc/antora/modules/howto/pages/modules/configuring_modules.adoc +++ b/doc/antora/modules/howto/pages/modules/configuring_modules.adoc @@ -1,4 +1,4 @@ -= Configuring a Module += Configure Modules The configuration files in xref:reference:raddb/mods-available/index.adoc[mods-available/] file describe diff --git a/doc/antora/modules/howto/pages/modules/eap/index.adoc b/doc/antora/modules/howto/pages/modules/eap/index.adoc index 4e43d8de5c3..dc52dc8e98a 100644 --- a/doc/antora/modules/howto/pages/modules/eap/index.adoc +++ b/doc/antora/modules/howto/pages/modules/eap/index.adoc @@ -1,5 +1,7 @@ = Extensible Authentication Protocol (EAP) +include::ROOT:partial$v3_warning.adoc[] + == Introduction Extensible Authentication Protocol(EAP), `RFC 3748`, is an authentication diff --git a/doc/antora/modules/howto/pages/modules/mschap/index.adoc b/doc/antora/modules/howto/pages/modules/mschap/index.adoc index cab033bed05..69f37eacee9 100644 --- a/doc/antora/modules/howto/pages/modules/mschap/index.adoc +++ b/doc/antora/modules/howto/pages/modules/mschap/index.adoc @@ -1,5 +1,7 @@ = rlm_mschap +include::ROOT:partial$v3_warning.adoc[] + The mschap module provides support for `MS-CHAPv1` and `MS-CHAPv2`, which is a common authentication mechanisms for Microsoft clients. diff --git a/doc/antora/modules/howto/pages/modules/python/index.adoc b/doc/antora/modules/howto/pages/modules/python/index.adoc index f44b9bf80ee..e09276cd125 100644 --- a/doc/antora/modules/howto/pages/modules/python/index.adoc +++ b/doc/antora/modules/howto/pages/modules/python/index.adoc @@ -1,4 +1,5 @@ = Python + == Introduction FreeRADIUS can call Python scripts in order to utilize third party libraries diff --git a/doc/antora/modules/howto/partials/config_server.adoc b/doc/antora/modules/howto/partials/config_server.adoc index 9650c722e69..adcb4af73e9 100644 --- a/doc/antora/modules/howto/partials/config_server.adoc +++ b/doc/antora/modules/howto/partials/config_server.adoc @@ -1,3 +1,5 @@ +=Configure Server + Changing the server configuration should be done via the following steps: @@ -21,7 +23,7 @@ steps: - read the *entire* debug output, looking for words like `error` or `warning`. These messages usually contain descriptions of what went wrong, and suggestions for how it can be fixed. - See xref:debugging/radiusd_X.adoc[an explanation of the debug output] for more details; + See xref:ROOT:debugging/radiusd_X.adoc[an explanation of the debug output] - try replacing your configuration with a saved copy of a "known working" configuration, and start again. This process can clean up errors caused by temporary edits, or edits that you have diff --git a/doc/antora/modules/tutorials/pages/accounting.adoc b/doc/antora/modules/tutorials/pages/accounting.adoc index 63ba5b3e692..715de870503 100644 --- a/doc/antora/modules/tutorials/pages/accounting.adoc +++ b/doc/antora/modules/tutorials/pages/accounting.adoc @@ -1,5 +1,16 @@ = Accounting Requests +include::ROOT:partial$v3_warning.adoc[] + +[NOTE] +====================================================================== +The `radlast` and `radwho` programs are no longer included with the +server in v4. + +The `radutmp` module is no longer included with the server. +We recommend using sqlite instead of flat-text databases. +====================================================================== + *Goal*: To send the server accounting requests and to have the server log the accounting requests. @@ -11,16 +22,7 @@ log the accounting requests. *Modules:* detail -[NOTE] -====================================================================== -This documentation is out of date for v4, and needs to be fixed. - -The `radlast` and `radwho` programs are no longer included with the -server. -The `radutmp` module is no longer included with the server. -We recommend using sqlite instead of flat-text databases. -====================================================================== In addition to authorization and authentication, one of the primary roles of a diff --git a/doc/antora/modules/tutorials/pages/autz-type.adoc b/doc/antora/modules/tutorials/pages/autz-type.adoc index 33f7ee891c6..12a7df52988 100644 --- a/doc/antora/modules/tutorials/pages/autz-type.adoc +++ b/doc/antora/modules/tutorials/pages/autz-type.adoc @@ -1,5 +1,7 @@ = Using the Autz-Type attribute +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To control which authorization modules are executed for an `Access-Request` diff --git a/doc/antora/modules/tutorials/pages/dictionary.adoc b/doc/antora/modules/tutorials/pages/dictionary.adoc index 0420a026c97..9af78fc39f9 100644 --- a/doc/antora/modules/tutorials/pages/dictionary.adoc +++ b/doc/antora/modules/tutorials/pages/dictionary.adoc @@ -1,5 +1,7 @@ = Custom Dictionaries and Attributes +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To understand how the dictionaries affect the server and to create a new vendor-specific dictionary with a number of custom attributes; also, to test those attributes in the server. diff --git a/doc/antora/modules/tutorials/pages/eap-tls.adoc b/doc/antora/modules/tutorials/pages/eap-tls.adoc index c1dd54e252c..621a8240eed 100644 --- a/doc/antora/modules/tutorials/pages/eap-tls.adoc +++ b/doc/antora/modules/tutorials/pages/eap-tls.adoc @@ -1,5 +1,7 @@ = EAP-TLS: Certificate-based authentication +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To configure the server to use the EAP-TLS authentication protocol and to send and receive test packets. diff --git a/doc/antora/modules/tutorials/pages/eap-ttls.adoc b/doc/antora/modules/tutorials/pages/eap-ttls.adoc index 11f6732a4d8..d4b186936f5 100644 --- a/doc/antora/modules/tutorials/pages/eap-ttls.adoc +++ b/doc/antora/modules/tutorials/pages/eap-ttls.adoc @@ -1,5 +1,7 @@ = EAP-TTLS: Tunneled authentication +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To configure the server to use the EAP-TTLS authentication protocol and to send and receive test packets. diff --git a/doc/antora/modules/tutorials/pages/final_group_project.adoc b/doc/antora/modules/tutorials/pages/final_group_project.adoc index a65852298f6..ab5d5451143 100644 --- a/doc/antora/modules/tutorials/pages/final_group_project.adoc +++ b/doc/antora/modules/tutorials/pages/final_group_project.adoc @@ -1,5 +1,7 @@ = Group Project - Simulating a production service +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To create a simulated, federated, production service *Time:* 2-3 hours diff --git a/doc/antora/modules/tutorials/pages/module_fail_over.adoc b/doc/antora/modules/tutorials/pages/module_fail_over.adoc index 01ce88a7e7d..657a40b4aff 100644 --- a/doc/antora/modules/tutorials/pages/module_fail_over.adoc +++ b/doc/antora/modules/tutorials/pages/module_fail_over.adoc @@ -1,5 +1,7 @@ = Module Fail-Over +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To configure the server to use a "backup" module if a "primary" module fails. diff --git a/doc/antora/modules/tutorials/pages/multiple_modules.adoc b/doc/antora/modules/tutorials/pages/multiple_modules.adoc index b5cc1b49551..f12bd4dbf4b 100644 --- a/doc/antora/modules/tutorials/pages/multiple_modules.adoc +++ b/doc/antora/modules/tutorials/pages/multiple_modules.adoc @@ -1,5 +1,7 @@ = Multiple instances of a module +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To configure the server to have multiple instances of a module. *Time:* 10-20 minutes diff --git a/doc/antora/modules/tutorials/pages/prepaid.adoc b/doc/antora/modules/tutorials/pages/prepaid.adoc index 3e5296f12fb..999e89bbb1b 100644 --- a/doc/antora/modules/tutorials/pages/prepaid.adoc +++ b/doc/antora/modules/tutorials/pages/prepaid.adoc @@ -1,5 +1,8 @@ = A simple pre-paid example +include::ROOT:partial$v3_warning.adoc[] + + *Goal:* To implement a simple "prepaid" functionality in the server. *Time:* 15-25 minutes diff --git a/doc/antora/modules/tutorials/pages/proxy.adoc b/doc/antora/modules/tutorials/pages/proxy.adoc index bbab4502b53..eaaffe31b10 100644 --- a/doc/antora/modules/tutorials/pages/proxy.adoc +++ b/doc/antora/modules/tutorials/pages/proxy.adoc @@ -1,5 +1,7 @@ = Configuring a server to proxy requests +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To configure the server to proxy packets to a remote (home) RADIUS server and to perform test authentications against both the proxy server and the home server. diff --git a/doc/antora/modules/tutorials/pages/proxy_failover.adoc b/doc/antora/modules/tutorials/pages/proxy_failover.adoc index b6bbcac9614..794208aeccf 100644 --- a/doc/antora/modules/tutorials/pages/proxy_failover.adoc +++ b/doc/antora/modules/tutorials/pages/proxy_failover.adoc @@ -1,5 +1,7 @@ = Proxy Fail-over +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To configure a "backup" home server that is used when the "primary" home server fails. diff --git a/doc/antora/modules/tutorials/pages/proxy_load_balance.adoc b/doc/antora/modules/tutorials/pages/proxy_load_balance.adoc index 5cce9aee753..b54ea49e6f4 100644 --- a/doc/antora/modules/tutorials/pages/proxy_load_balance.adoc +++ b/doc/antora/modules/tutorials/pages/proxy_load_balance.adoc @@ -1,5 +1,7 @@ = Proxy Load Balancing +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To configure a server to load-balanceproxied requests across multiple home servers. diff --git a/doc/antora/modules/tutorials/pages/proxy_receive.adoc b/doc/antora/modules/tutorials/pages/proxy_receive.adoc index f0d3b46abf4..d08b074f039 100644 --- a/doc/antora/modules/tutorials/pages/proxy_receive.adoc +++ b/doc/antora/modules/tutorials/pages/proxy_receive.adoc @@ -1,5 +1,7 @@ = Configuring a server to send and receive proxy requests +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To configure the server to proxy packets to a remote (home) RADIUS server and to receive packets from another proxy server. diff --git a/doc/antora/modules/tutorials/pages/sql.adoc b/doc/antora/modules/tutorials/pages/sql.adoc index 5a0ede8f503..149b8f9db92 100644 --- a/doc/antora/modules/tutorials/pages/sql.adoc +++ b/doc/antora/modules/tutorials/pages/sql.adoc @@ -1,5 +1,7 @@ = Communicating with an SQL database +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To configure the server to communicate with an SQL database. *Time:* 25-40 minutes. diff --git a/doc/antora/modules/tutorials/pages/unlang_splitting_strings.adoc b/doc/antora/modules/tutorials/pages/unlang_splitting_strings.adoc index 0a09529d68f..6df59c134ca 100644 --- a/doc/antora/modules/tutorials/pages/unlang_splitting_strings.adoc +++ b/doc/antora/modules/tutorials/pages/unlang_splitting_strings.adoc @@ -1,5 +1,7 @@ = Splitting strings +include::ROOT:partial$v3_warning.adoc[] + *Goal:* Explore uses of regular expressions and subcapture groups *Time:* 10-20 minutes diff --git a/doc/antora/modules/tutorials/pages/unlang_update_blocks_and_conditions.adoc b/doc/antora/modules/tutorials/pages/unlang_update_blocks_and_conditions.adoc index ef569a4e8cf..5f2cf6d9fa2 100644 --- a/doc/antora/modules/tutorials/pages/unlang_update_blocks_and_conditions.adoc +++ b/doc/antora/modules/tutorials/pages/unlang_update_blocks_and_conditions.adoc @@ -1,5 +1,7 @@ = Update blocks and simple conditions +include::ROOT:partial$v3_warning.adoc[] + *Goal:* Explore uses of update blocks in the policy language *Time:* 10-25 minutes diff --git a/doc/antora/modules/tutorials/pages/virtual.adoc b/doc/antora/modules/tutorials/pages/virtual.adoc index 697735299c5..e20975a941d 100644 --- a/doc/antora/modules/tutorials/pages/virtual.adoc +++ b/doc/antora/modules/tutorials/pages/virtual.adoc @@ -1,5 +1,7 @@ = Virtual Servers +include::ROOT:partial$v3_warning.adoc[] + *Goal:* To understand how to create and use a new virtual server. *Time:* 20-30 minutes