From: Alan T. DeKok Date: Thu, 26 Jun 2025 11:56:01 +0000 (-0400) Subject: add documentation on @policy, and TBD for other policies X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d9b5fc06cfec87cd8372575e02f9b3e6e048ce7f;p=thirdparty%2Ffreeradius-server.git add documentation on @policy, and TBD for other policies --- diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index 6375279c7d9..7d7f8e97f4b 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -140,7 +140,7 @@ *** xref:dictionary/begin-vendor.adoc[BEGIN-VENDOR] *** xref:dictionary/end-vendor.adoc[END-VENDOR] -** xref:policy/index.adoc[Policies] +** xref:policy/index.adoc[Writing Policy Rules] *** xref:policy/different.adoc[Why FreeRADIUS is different] ** xref:man/index.adoc["man" pages] @@ -245,6 +245,10 @@ **** xref:raddb/mods-available/stats.adoc[Stats] **** xref:raddb/mods-available/unbound.adoc[Unbound] +** xref:raddb/policy.d/index.adoc[Policies] +*** xref:raddb/policy.d/at_reference.adoc[@policy] +*** xref:raddb/policy.d/method.adoc[Method Override] + ** xref:raddb/sites-available/index.adoc[Virtual Servers] *** xref:raddb/sites-available/arp.adoc[ARP] *** xref:raddb/sites-available/bfd.adoc[BFD] diff --git a/doc/antora/modules/reference/pages/raddb/mods-available/index.adoc b/doc/antora/modules/reference/pages/raddb/mods-available/index.adoc index be4294dd418..5a21ea73e6b 100644 --- a/doc/antora/modules/reference/pages/raddb/mods-available/index.adoc +++ b/doc/antora/modules/reference/pages/raddb/mods-available/index.adoc @@ -115,5 +115,29 @@ interpretation of those files is documented there. These files are often in a custom, module-specific format, instead of using the standard configuration file format. +== Module-Specific Overrides + +Most modules have section-specific functionality. For example, the +`sql` module does different things when it is doing authentication +versus accounting. The xref:unlang/module_method.adoc[method +override] functionality lets you call a particular "method" of a +module when running a different section. + +== Policy Overrides + +The server can also replace a module call with a policy. For example, +a virtual server can contain a reference to the `radius` module. In +most cases, this reference will (of course) call the `radius` module. + +In some cases, it is necessary to have module-specific policies. The +xref:unlang/policy.d/policy_method.adoc[policy override] syntax allows +for policies to be added around a module, or to override a module +method. + +In addition, the xref:unlang/policy.d/at_reference.adoc[@policy] references +allow for policies to be placed in the module configuration file, +which helps to better organize module-specific configurations and +policies. + // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/raddb/policy.d/at_reference.adoc b/doc/antora/modules/reference/pages/raddb/policy.d/at_reference.adoc new file mode 100644 index 00000000000..dc2b8f15056 --- /dev/null +++ b/doc/antora/modules/reference/pages/raddb/policy.d/at_reference.adoc @@ -0,0 +1,137 @@ += @policy Statements + +The `@policy` syntax is used to simplify the location and management +of policies. It allows for module-specific policies to be placed in a +module configuration file. + +[NOTE] +=== +There is no functional difference between an `@policy`, and a policy +located in the `policy.d/` directory. The only difference is their +location in the file system. +=== + +The `@policy` functionality is used when it is necessary to "wrap" a +module in a policy not just once, but every time the module is called. + +=== Module Method Overrides + +Thge `@policy` syntax be used in conjunction with the +xref:unlang/policy.d/method.adoc[method override] syntax to +override a module, but only when it is called from a specific +processing section. + +The combination of the `@policy`, `unlang` and +xref:unlang/policy.d/method.adoc[override] allows for +extremely complex policies to be created in a very simple manner. + +== Worked Example + +An example of this functionality is with the following set of +requirements: + +* There is an `sql` module configured, which writes accounting data to + an SQL database, + +* The `sql` module is used in multiple virtual servers, + +* The SQL database is supposed to be fast, and we wish to enforce a + xref:unlang/timeout.adoc[timeout] when the `sql` module is called. + +One possible configuration is to use the +xref:unlang/timeout.adoc[timeout] keyword to "wrap" each call to the +`sql` module, as in the following configuration file example: + +.Timeout in a Virtual Server +[source,unlang] +---- +server one { + ... + recv Accounting-Request { + ... + timeout 1s { + sql + } + ... + } + ... +} +---- + +This configuration can then be repeated for each virtual server. +While this works, it can be awkward and hard to read. Even worse, any +change to the timeout value requires changing that value in multiple +places. It is easy to miss making one change, which means that the +various configurations behave differently. + +It is better instead to use the `@policy` syntax along with the +xref:unlang/policy.d/method.adoc[method override] syntax, to +"wrap" the `sql` module in a xref:unlang/timeout.adoc[timeout] +section. Even better, this `@policy` can be listed in the `sql` +module configuration file, and does not need to be in the `policy.d/` +directory. + +The following example shows how this configuration can be made. The +following example can be placed into the `sql` module configuration +file. It first contains the `sql` module configuration. It is then +followed by an `@policy`, which overrides the `sql` module +functionality, to ensure that every call to `sql` has a one second +timeout. + +.Timeout in a Module Configuration file +[source,unlang] +---- +sql { + dialect = "mysql" + server = localhost + ... +} + +@policy sql { + timeout 1s { + sql + } +} +---- + +Any virtual server which needs to use the `sql` module can then just +refer to `sql`. It does not need to use a +xref:unlang/timeout.adoc[timeout] in the virtual server. + +.Virtual Server With a Policy-Based Timeout +[source,unlang] +---- +server one { + ... + recv Accounting-Request { + ... + sql + ... + } + ... +} +---- + +== Pros and Cons + +Like any set of functionality, there are trade-offs when using it. +The benefit of the `@policy` syntax is that it allows both +module-specific policy overrides, and ensures that those overrides are +associated with the module configuration instead of being in some +other file. + +The downside to this syntax is that when you see that a virtual server +calls the `sql` module, it may not be clear that there are additional +things going on. However, it is easy to double-check what's +happening: + +* look in `mods-enabled/sql` to see if there is an `@policy` override + +* run the server in xref:ROOT:debugging/radiusd_X.adoc[debug mode], + and see what happens when that part of the virtual server is + reached. + +In general, the benefits of this solution outweigh the downsides. + +// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/raddb/policy.d/index.adoc b/doc/antora/modules/reference/pages/raddb/policy.d/index.adoc new file mode 100644 index 00000000000..edc4417594c --- /dev/null +++ b/doc/antora/modules/reference/pages/raddb/policy.d/index.adoc @@ -0,0 +1,3 @@ +# Policies + +TBD diff --git a/doc/antora/modules/reference/pages/raddb/policy.d/method.adoc b/doc/antora/modules/reference/pages/raddb/policy.d/method.adoc new file mode 100644 index 00000000000..a930ca53b32 --- /dev/null +++ b/doc/antora/modules/reference/pages/raddb/policy.d/method.adoc @@ -0,0 +1,3 @@ += Override a Method in a Policy + +TBD