From: Alan T. DeKok Date: Mon, 28 Nov 2022 20:05:19 +0000 (-0500) Subject: documentation for local variables X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5896a280d64d7b69e7955b5d6c0ca6849d9409dd;p=thirdparty%2Ffreeradius-server.git documentation for local variables --- diff --git a/doc/antora/modules/installation/pages/upgrade.adoc b/doc/antora/modules/installation/pages/upgrade.adoc index 1a776aa0665..ad976a485ae 100644 --- a/doc/antora/modules/installation/pages/upgrade.adoc +++ b/doc/antora/modules/installation/pages/upgrade.adoc @@ -70,15 +70,15 @@ and are nested by definition. For v4, the `Cisco-AVPair` attribute is called `AVPair`, and it lives inside of the `Cisco` namespace, which in turn lives inside of the -`Vendor-Specific` namespace. So the new name for `Cisco-AVPair` is -`Vendor-Specific.Cisco.AVPair`. +`Vendor-Specific` namespace. So the old `Cisco-AVPair` attribute is +now named `Vendor-Specific.Cisco.AVPair`. -This process continues for many thousands of vendor-specific +This renaming process continues for many thousands of vendor-specific attributes. Happily, it is possible to (mostly) use the old names with v4. There are limitations, but it will mostly work. The main reason -for enabling the old names is to try out v4 with a database that is +for enabling the old names is to try out v4 with a database which is also used by v3. This lets you test that v4 works, without going through a complex "upgrade everything" process. @@ -101,11 +101,11 @@ there are situations where the aliases do not behave correctly. We recognize that this process is a bit of work. However, we wish to encourage everyone using v4 to upgrade to using the new v4 features. Our experience shows that if we automatically enable "compatibility -functions", then those compatiblity functions will be used for a -decade. So we need to find a balance between upgrades and ongoing -support. Easy upgrades will mean complex ongoing support. Complex -upgrades make ongoing support easier, but also make it less likely -that people will upgrade. +features", then those compatiblity features will be used for a decade, +and no one will upgrade to use the new features. So we need to find a +balance between upgrades and ongoing support. Easy upgrades will mean +complex ongoing support. Complex upgrades make ongoing support +easier, but also make it less likely that people will upgrade. == radiusd.conf diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index 3380bc91c85..b4b98ec3a01 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -18,6 +18,7 @@ **** xref:unlang/group.adoc[group] **** xref:unlang/if.adoc[if] **** xref:unlang/load-balance.adoc[load-balance] +**** xref:unlang/local.adoc[local variables] **** xref:unlang/limit.adoc[limit] **** xref:unlang/map.adoc[map] **** xref:unlang/parallel.adoc[parallel] diff --git a/doc/antora/modules/reference/pages/unlang/edit.adoc b/doc/antora/modules/reference/pages/unlang/edit.adoc index 1fb85fa3148..8cd14ee67d2 100644 --- a/doc/antora/modules/reference/pages/unlang/edit.adoc +++ b/doc/antora/modules/reference/pages/unlang/edit.adoc @@ -74,6 +74,8 @@ processing as normal. In short, failed edit operations are effectively a "noop" operation, and do not result in any changes. +=== Grouping Edits + Multiple attributes may be grouped into a set by using the `group` keyword. When changes are done in a `group`, then either all of the changes are applied, or none of them are applied. This functionality diff --git a/doc/antora/modules/reference/pages/unlang/group.adoc b/doc/antora/modules/reference/pages/unlang/group.adoc index aa0e40f6b8d..80c9fa4296b 100644 --- a/doc/antora/modules/reference/pages/unlang/group.adoc +++ b/doc/antora/modules/reference/pages/unlang/group.adoc @@ -37,5 +37,12 @@ group { The last entry in a `group` section can also be an xref:unlang/actions.adoc[actions] subsection. +== Grouping Edits + +The `group` keyword can also be used to group multiple +xref:unlang/edit.adoc[edit] instructions. When edit instructions are +grouped, then the edits are "atomic". That is, either all of the +edits succeed, or none of them do. + // Copyright (C) 2021 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // Development of this documentation was sponsored by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/unlang/index.adoc b/doc/antora/modules/reference/pages/unlang/index.adoc index 7d31ab33ed5..8acb47e5a4f 100644 --- a/doc/antora/modules/reference/pages/unlang/index.adoc +++ b/doc/antora/modules/reference/pages/unlang/index.adoc @@ -69,11 +69,14 @@ if ((&User-Name == "bob") && (&Calling-Station-Id == "00:01:03:04:05")) { == Editing Attributes and lists. -xref:unlang/edit.adoc[attribute editing] statements are used to edit +xref:unlang/edit.adoc[Attribute editing] statements are used to edit attributes and lists of attributes. The old-style xref:unlang/update.adoc[update] sections are deprecated, and no longer supported. +xref:unlang/local.adoc[Local variables] can be defined, so that the +local `dictionary` file no longer needs to be modified. + Most request packets will result in reply packets that contain additional information for the requestor. Attribute editing allows policies to add attributes to requests, replies, or to other places. diff --git a/doc/antora/modules/reference/pages/unlang/local.adoc b/doc/antora/modules/reference/pages/unlang/local.adoc new file mode 100644 index 00000000000..acef2a41275 --- /dev/null +++ b/doc/antora/modules/reference/pages/unlang/local.adoc @@ -0,0 +1,70 @@ += Local Variables + +Local variables can be defined and used inside of any `unlang` +processing section. A local variable is used any time a "temporary" +variable is needed. Local variables exist only within a particular +section (i.e. scope), and cannot be sent in a packet over the network. + +.Syntax +[source,unlang] +---- + { + + ... + + [ statements ] +} +---- + +:: One of xref:unlang/case.adoc[case], xref:unlang/else.adoc[else], xref:unlang/elsif.adoc[elsif], xref:unlang/foreach.adoc[foreach], xref:unlang/group.adoc[group], xref:unlang/if.adoc[if] ,xref:unlang/limit.adoc[limit], or xref:unlang/timeout.adoc[timeout]. Local variables are forbidden in all other locations. + +:: A "leaf" xref:type/all_types.adoc[data type]. Structural types such as `group`, `struct`, `tlv`, etc. are not allowed. + +:: A unique name for the local variable. This name cannot be the same as any previously-defined local variable in the same scope, and it cannot be the same as any attribute defined in the current protocol dictionary. + +Multiple local variables may be defined. All definitions must be at the top of a section. + +[ statements ]:: The `unlang` commands which will be executed. The local variable can be used, edited, modified, etc. within these statements. + +Local variables cannot be deleted. Multiple local variables of the same name cannot be used. The local variables exist in their own list, and cannot be added to the normal lists `request`, `reply`, `control`, etc. + +Local variables are _not_ automatically created. + +When the current scope exits, the local variable is deleted and is no longer accessible. + +.Example +[source,unlang] +---- +if (&User-Name == "bob") { + uint32 len + + &len := %(length:%{User-Name}) + + &Reply-Message := "Length of %{User-Name} is %{len}" +} +---- + +In v3 the default dictionaries included a series of `Tmp-*` +attributes. These are no longer necessary, and should not be used. + +.Local variables exist on only if they have been created +[source,unlang] +---- +if (&User-Name == "bob") { + # declare "len" as ALLOWED to be used + uint32 len + + # this test ALWAYS fails + if (&len) { + ... + } + + # "len" is created, and can now be used + &len := %(length:%{User-Name}) + + &Reply-Message := "Length of %{User-Name} is %{len}" +} +---- + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// Development of this documentation was sponsored by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/index.adoc b/doc/antora/modules/reference/pages/xlat/index.adoc index 74b742ff639..9a990efb472 100644 --- a/doc/antora/modules/reference/pages/xlat/index.adoc +++ b/doc/antora/modules/reference/pages/xlat/index.adoc @@ -31,14 +31,6 @@ Expansions are used inside of xref:type/string/double.adoc[double-quoted strings] and for the xref:type/string/backticks.adoc[back-tick quoted strings] -== Caveats - -Unlike other languages, there is no way to define new variables. All -of the expansions must refer to attributes that already exist, or to -pre-defined functions which take arguments, and return values. - -New variables are defined in the xref:raddb:dictionary.adoc[site-local dictionaries]. - == Character Escaping Some characters need to be escaped within a dynamically expanded @@ -54,7 +46,10 @@ information. .Example -`Reply-Message := "%{User-Name} with a literal %%` +[source,unlang] +---- +Reply-Message := "%{User-Name} with a literal %%" +---- // Copyright (C) 2021 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // Development of this documentation was sponsored by Network RADIUS SAS. diff --git a/raddb/dictionary b/raddb/dictionary index 3f9305d667d..76ce4fa3d90 100644 --- a/raddb/dictionary +++ b/raddb/dictionary @@ -1,8 +1,23 @@ -# -*- text -*- +># -*- text -*- # # # $Id$ +####################################################################### +# +# 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. +# +# 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. +# +# 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. +# ####################################################################### # # = Local dictionary definitions