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.
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
**** 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]
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
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.
== 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.
--- /dev/null
+= 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]
+----
+<keyword> {
+ <data-type> <name>
+ ...
+
+ [ statements ]
+}
+----
+
+<keyword>:: 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.
+
+<data-type>:: A "leaf" xref:type/all_types.adoc[data type]. Structural types such as `group`, `struct`, `tlv`, etc. are not allowed.
+
+<name>:: 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.
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
.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.
-# -*- 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
projects / thirdparty / freeradius-server.git / commitdiff
