From: nolade Date: Fri, 9 May 2025 18:06:38 +0000 (-0400) Subject: docs: updated miscelleneous functions X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=65d232940b2d3c0a4efc089dd593bb13f3586ae4;p=thirdparty%2Ffreeradius-server.git docs: updated miscelleneous functions --- diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index b9ffe7a43ac..91271e77b9e 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -91,14 +91,19 @@ *** xref:xlat/str/index.adoc[String Handling] **** xref:xlat/str/concat.adoc[Concatenation] **** xref:xlat/str/split.adoc[Split Strings] -**** xref:xlat/builtin.adoc#length[Length] +**** xref:xlat/misc/misc.adoc#length[Length] **** xref:xlat/str/lpad.adoc[Left Pad] **** xref:xlat/str/rpad.adoc[Right Pad] **** xref:xlat/str/rand.adoc[Random Strings] **** xref:xlat/str/lower.adoc[Convert to Lowercase] **** xref:xlat/str/upper.adoc[Convert to Uppercase] -*** xref:xlat/builtin.adoc[Built-in Expansions] +*** xref:xlat/misc/index.adoc[Miscellaneous Functions] +**** xref:xlat/misc/config.adoc[Server Configuration] +**** xref:xlat/misc/length.adoc[length] +**** xref:xlat/misc/misc.adoc[Miscellaneous] +**** xref:xlat/misc/rand.adoc[rand] + *** xref:xlat/character.adoc[Single Letter Expansions] *** xref:xlat/attribute.adoc[Attribute References] diff --git a/doc/antora/modules/reference/pages/index.adoc b/doc/antora/modules/reference/pages/index.adoc index ac62dc2fa3d..c1376da109a 100644 --- a/doc/antora/modules/reference/pages/index.adoc +++ b/doc/antora/modules/reference/pages/index.adoc @@ -27,7 +27,7 @@ language. Policies allow the server to read information in databases, perform if / then / else checks, add content to replies, along with many other actions. -When processing packets, it is possible to call functions or do string +When processing packets, it's possible to call functions or do string manipulation with attribute contents. The xref:xlat/index.adoc[dynamic expansion] documentation describes how this is done. diff --git a/doc/antora/modules/reference/pages/type/cast.adoc b/doc/antora/modules/reference/pages/type/cast.adoc index 668282a88a7..1a4ab573ff6 100644 --- a/doc/antora/modules/reference/pages/type/cast.adoc +++ b/doc/antora/modules/reference/pages/type/cast.adoc @@ -159,7 +159,7 @@ causes the values to be merged together, The resulting string is `"19216801"`. If you need to add text in between each list entry, see the -`%str.concat()` function in the xref:xlat/builtin.adoc[built-in +`%str.concat()` function in the xref:xlat/builtin/index.adoc[built-in expansions] list. .Example Creating multiple Attributes diff --git a/doc/antora/modules/reference/pages/unlang/condition/regex.adoc b/doc/antora/modules/reference/pages/unlang/condition/regex.adoc index d172a3e21c0..23c528e61ce 100644 --- a/doc/antora/modules/reference/pages/unlang/condition/regex.adoc +++ b/doc/antora/modules/reference/pages/unlang/condition/regex.adoc @@ -113,7 +113,7 @@ library the server was built with. Multiple flags may be specified per When the `=~` or `!~` operators are used, then parentheses in the regular expression will sub capture groups, which contain part of the subject string. -The xref:xlat/builtin.adoc#_regex_match[%regex.match()] function expands to the portion of the subject tha +The xref:xlat/builtin/miscellaneous/misc.adoc#_regex_match[%regex.match()] function expands to the portion of the subject tha matched. The expansions + `%regex.match(1)`..`%regex.match(32)` expand to the contents of any subcapture groups. @@ -121,7 +121,7 @@ When using libpcre[2], named capture groups may also be accessed using the built-in expansion + `%regex.match()`. -Please see the xref:xlat/builtin.adoc#_0_32[xlat documentation] for +Please see the xref:xlat/builtin/index.adoc#_0_32[xlat documentation] for more information on regular expression matching. .Extracting the 'user' portion of a realm qualified string diff --git a/doc/antora/modules/reference/pages/xlat/character.adoc b/doc/antora/modules/reference/pages/xlat/character.adoc index d43d1806502..d4be7b53e0c 100644 --- a/doc/antora/modules/reference/pages/xlat/character.adoc +++ b/doc/antora/modules/reference/pages/xlat/character.adoc @@ -2,7 +2,7 @@ The following are single letter expansions. -The xref:xlat/builtin.adoc[builtin] `%time(...)` expansion and the +The xref:xlat/builtin/miscellaneous/misc.adoc[builtin] `%time(...)` expansion and the xref:reference:raddb/mods-available/date.adoc[date] module should be used instead of these expansions. @@ -34,7 +34,7 @@ unsigned decimal number, and returns an integer number of seconds since the Unix epoch. This expansion is only useful where the time resolution is in seconds. -If more resolution is needed, the xref:xlat/builtin.adoc[builtin] +If more resolution is needed, the xref:xlat/builtin/index.adoc[builtin] `%time(...)` expansion should be used instead. `%Y()`:: diff --git a/doc/antora/modules/reference/pages/xlat/function.adoc b/doc/antora/modules/reference/pages/xlat/function.adoc index 6cf8342eab0..ec175c81fe9 100644 --- a/doc/antora/modules/reference/pages/xlat/function.adoc +++ b/doc/antora/modules/reference/pages/xlat/function.adoc @@ -8,7 +8,7 @@ .Description Functions allow for complex expansions at run time. There are many -xref:xlat/builtin.adoc[built-in expansions]. Many modules also define +xref:xlat/builtin/index.adoc[built-in expansions]. Many modules also define their own expansions. The module-specific expansions are documented in each module. function:: The name of the function. e.g. `md5` or `sql`, etc. diff --git a/doc/antora/modules/reference/pages/xlat/index.adoc b/doc/antora/modules/reference/pages/xlat/index.adoc index f9efc4aaa6a..1c136b59c03 100644 --- a/doc/antora/modules/reference/pages/xlat/index.adoc +++ b/doc/antora/modules/reference/pages/xlat/index.adoc @@ -24,7 +24,7 @@ references, function calls, etc. The table below gives more examples of expansi | xref:xlat/character.adoc[single character] | Single character expansions. | xref:xlat/function.adoc[functions] | Function call syntax. | xref:xlat/alternation.adoc[condition] | Conditionally expand a string. -| xref:xlat/builtin.adoc[built-in expansions] | Functions as string length, tolower, etc... +| xref:xlat/builtin/index.adoc[built-in expansions] | Functions as string length, tolower, etc... |===== Expansions are used inside of diff --git a/doc/antora/modules/reference/pages/xlat/misc/config.adoc b/doc/antora/modules/reference/pages/xlat/misc/config.adoc new file mode 100644 index 00000000000..3fa375ce921 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/misc/config.adoc @@ -0,0 +1,23 @@ += Server Configuration + +== %config() + +Refers to a variable in the configuration file. See the documentation +on configuration file references. + +.Return: _string_ + +.Example + +[source,unlang] +---- +"Server installed in %config('prefix')" +"Module rlm_exec.shell_escape = %config('modules.exec.shell_escape')" +---- + +.Output + +``` +Server installed in /opt/freeradius +Module rlm_exec.shell_escape = yes +``` diff --git a/doc/antora/modules/reference/pages/xlat/misc/index.adoc b/doc/antora/modules/reference/pages/xlat/misc/index.adoc new file mode 100644 index 00000000000..3502fc3fc97 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/misc/index.adoc @@ -0,0 +1,18 @@ += Miscellanous functions + +In addition to storing attribute references, the server has a number +of built-in expansions. These expansions act largely as functions +which operate on inputs, and produce an output. + +.Builtin Functions +[options="headers, autowidth] +|=== +| *Function* | *Description* +| xref:xlat/misc/config.adoc[Server Configuration] | Examine configuration items +| xref:xlat/misc/length.adoc[length] | Get the length of data +| xref:xlat/misc/misc.adoc[Miscellaneous] | Functions to execute regular expression search on string, using pattern. +| xref:xlat/misc/rand.adoc[rand] | random integers +|=== + +// 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/xlat/misc/length.adoc b/doc/antora/modules/reference/pages/xlat/misc/length.adoc new file mode 100644 index 00000000000..5a47435e758 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/misc/length.adoc @@ -0,0 +1,33 @@ += %length( ... ) + +The `length` function returns the size of the input as an integer. +When the input is a string, then the output is identical to the +`strlen` expansion. + +When the input is an attribute reference, the output is the size of +the attributes data as encoded "on the wire". + +.Return: _size_ + +.Determining the length of fixed and variable length attributes +==== +[source,unlang] +---- +Tmp-String-0 := "Caipirinha" +Framed-IP-Address := 192.0.2.1 + +reply += { + Reply-Message = "The length of %{control.Tmp-String-0} is %length(control.Tmp-String-0)" + Reply-Message = "The length of %{control.Framed-IP-Address} is %length(control.Framed-IP-Address)" +} +---- + +.Output +.... +The length of Caipirinha is 10 +The length of 192.168.0.2 is 4 +.... +==== + +// 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/xlat/builtin.adoc b/doc/antora/modules/reference/pages/xlat/misc/misc.adoc similarity index 78% rename from doc/antora/modules/reference/pages/xlat/builtin.adoc rename to doc/antora/modules/reference/pages/xlat/misc/misc.adoc index f0da97d120d..b129b94ef42 100644 --- a/doc/antora/modules/reference/pages/xlat/builtin.adoc +++ b/doc/antora/modules/reference/pages/xlat/misc/misc.adoc @@ -1,87 +1,4 @@ -= Built-In Expansions - -In addition to storing attribute references, the server has a number -of built-in expansions. These expansions act largely as functions -which operate on inputs, and produce an output. - -== Attribute Manipulation - -=== %length( ... ) - -The `length` expansion returns the size of the input as an integer. -When the input is a string, then the output is identical to the -`strlen` expansion. - -When the input is an attribute reference, the output is the size of -the attributes data as encoded "on the wire". - -.Return: _size_ - -.Determining the length of fixed and variable length attributes -==== -[source,unlang] ----- -Tmp-String-0 := "Caipirinha" -Framed-IP-Address := 192.0.2.1 - -reply += { - Reply-Message = "The length of %{control.Tmp-String-0} is %length(control.Tmp-String-0)" - Reply-Message = "The length of %{control.Framed-IP-Address} is %length(control.Framed-IP-Address)" -} ----- - -.Output -.... -The length of Caipirinha is 10 -The length of 192.168.0.2 is 4 -.... -==== - -=== %rand() - -Generate random number from `0` to `-1`. - -.Return: _uint64_ - -.Generating a random number between 0 and 511 -==== -[source,unlang] ----- -reply.Reply-Message := "The random number is %rand(512}" ----- - -.Output - -``` -The random number is 347 -``` -==== - -== Server Configuration - -=== %config() - -Refers to a variable in the configuration file. See the documentation -on configuration file references. - -.Return: _string_ - -.Example - -[source,unlang] ----- -"Server installed in %config('prefix')" -"Module rlm_exec.shell_escape = %config('modules.exec.shell_escape')" ----- - -.Output - -``` -Server installed in /opt/freeradius -Module rlm_exec.shell_escape = yes -``` - -== Miscellaneous Expansions += Miscellaneous Expansions == %regex.search(pattern, string) @@ -94,7 +11,7 @@ matches in `%regex.match()`. This function is the same as using `%{string =~ /pattern/}`. However, this function is included for completeness. -=== %regex.match(0)+..+%regex.match(32) +== %regex.match(0)+..+%regex.match(32) `%regex.match(0)` expands to the portion of the subject that matched the last regular expression evaluated. `%regex.match(1)`..`%regex.match(32)` expand to the contents of any capture @@ -103,13 +20,13 @@ groups in the pattern. Every time a regular expression is evaluated, whether it matches or not, the numbered capture group values will be cleared. -=== +%regex.match(}+ +== +%regex.match(}+ Return named subcapture value from the last regular expression evaluated. Results of named capture groups are available using the `%regex.match(}` expansion. They will also be accessible using the numbered expansions -described xref:xlat/builtin.adoc#_0_32[above]. +described xref:xlat/builtin/miscellaneous/misc.adoc#_0_32[above]. Every time a regular expression is evaluated, whether it matches or not, the named capture group values will be cleared. @@ -131,7 +48,7 @@ Debug : pcre2 : 10.33 (2019-04-16) - retrieved at build tim .... ==== -=== +%eval()+ +== +%eval()+ Evaluates the string as an expansion, and returns the result. The main difference between using this expansion and just using `%{...}` is that the string being evaluated can be dynamically changed. @@ -183,30 +100,30 @@ reply.Reply-Message := "You should wait for %time.next(1h)s" You should wait for 2520s ``` -=== %time.now() +== %time.now() Return the current time. This time should be used for actions which involve the file system, or for actions which happen after the request has been received. -=== %time.request() +== %time.request() Return the time when the request was received. This time should be used as the basis any actions which involve the "start time of the request". -=== %time.offset() +== %time.offset() Return a `time_delta` of the current offset from UTC. This offset can change while the server is running, due to daylight savings updates. -=== %time.is_dst() +== %time.is_dst() Return a `bool` indicating whether or not the system is currently operating in daylight savings. -=== %str.subst(, , ) +== %str.subst(, , ) Substitute text. @@ -226,7 +143,7 @@ reply.Reply-Message := "%sub(%{control.Tmp-String-0}, / /, ',')" Caipirinha,is,a,light,and,refreshing,drink! ``` -### %time() +== %time() Return the current time. @@ -349,5 +266,6 @@ This kind of math works well for "tomorrow", but it is less useful for "next week Monday", or "start of next month". The `%time.next(...)` expansion above should be used for those time operations. -// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. + +// 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/xlat/misc/rand.adoc b/doc/antora/modules/reference/pages/xlat/misc/rand.adoc new file mode 100644 index 00000000000..a3d8e0fa503 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/misc/rand.adoc @@ -0,0 +1,23 @@ += %rand() + +Generate random number from `0` to `-1`. + +.Return: _uint64_ + +.Generating a random number between 0 and 511 +==== +[source,unlang] +---- +reply.Reply-Message := "The random number is %rand(512)" +---- + +.Output + +``` +The random number is 347 +``` +==== + + +// 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/xlat/str/index.adoc b/doc/antora/modules/reference/pages/xlat/str/index.adoc index 95babc0d2d4..cf24d160fa2 100644 --- a/doc/antora/modules/reference/pages/xlat/str/index.adoc +++ b/doc/antora/modules/reference/pages/xlat/str/index.adoc @@ -9,7 +9,7 @@ The following functions perform string manipulation. | Function | Description | xref:xlat/str/concat.adoc[concat] | Concatenate strings with delimiters | xref:xlat/str/split.adoc[split] | Split a string based on delimiters -| xref:xlat/builtin.adoc#length[Length] | Returns the size of the string (strlen) +| xref:xlat/misc/misc.adoc#length[length] | Returns the size of the string (strlen) | xref:xlat/str/lpad.adoc[lpad] | Left pad a string | xref:xlat/str/rpad.adoc[rpad] | Right pad a string | xref:xlat/str/rand.adoc[rand] | Return a random string based on input format @@ -19,4 +19,3 @@ The following functions perform string manipulation. // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. -