From cd5a03697bbcf31e37c2cd1ec3bbffbe433e71a3 Mon Sep 17 00:00:00 2001 From: "Alan T. DeKok" Date: Mon, 25 Sep 2023 08:29:17 -0400 Subject: [PATCH] document new dictionary section --- .../modules/raddb/pages/dictionary.adoc | 49 +++++++++--- .../raddb/pages/sites-available/default.adoc | 74 +++++++++++++++++++ raddb/dictionary | 24 ++++-- raddb/sites-available/default | 66 +++++++++++++++++ 4 files changed, 194 insertions(+), 19 deletions(-) diff --git a/doc/antora/modules/raddb/pages/dictionary.adoc b/doc/antora/modules/raddb/pages/dictionary.adoc index 66aab7b56ec..951af7e997c 100644 --- a/doc/antora/modules/raddb/pages/dictionary.adoc +++ b/doc/antora/modules/raddb/pages/dictionary.adoc @@ -2,6 +2,20 @@ +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 This is the local dictionary file which can be @@ -17,6 +31,14 @@ dictionaries from this file. However, if the `$INCLUDE` line is here, nothing bad will happen. +## Dictionaries per Virtual Server + +v4 also supports a `dictionary { ... }` subsection in a virtual +server. If the attributes are used only in one virtual server, +they shuld be defined there. + + + ## Editing the dictionary Any new/changed attributes *must* be placed in this file. @@ -25,10 +47,15 @@ See `man dictionary` for documentation on how dictionary entries should be formatted. All local attributes and `$INCLUDE` directives should -go into this file. +go into this files. + +The attribute definitions here should use `DEFINE`, not `ATTRIBUTE`. +The `DEFINE` keyword is exactly like `ATTRIBUTE`, except it does not +require an attribute number. + +As a result, there is no need to manually manage numbers. -The numbers you pick should be between 3000 and 4000. -These attributes will *not* go into a RADIUS packet. +Any attribute `DEFINE`d here will not go into a packet. If you do want attributes to go into a RADIUS packet, you will need to use VSAs. This means requesting allocation @@ -80,19 +107,19 @@ for enabling the old names is to try out v4 with a database that is also used by v3. This lets you test that v4 works, without going through a complex "upgrade everything" process. -The old v3 names are in "alias" dictionaries, in the ${dictdir} +The old v3 names are in "alias" dictionaries, in the `${dictdir}` directory. To find out where this directory is on your local system, run "radiusd -h" or "radclient -h". Then look for the "-D" command-line option, and it will tell you where the dictionary files are located. -The v3 names are in ${dictdir}/radius/alias/VENDOR.txt where -VENDOR is the name of the vendor, which is taken from the VENDOR +The v3 names are in `${dictdir}/radius/alias/VENDOR.txt` where +_VENDOR_ is the name of the vendor, which is taken from the `VENDOR` definition in the v3 dictionaries. -You will need to add a $INCLUDE line for each vendor-specific +You will need to add a `$INCLUD`E line for each vendor-specific dictionary which is used by your local system. The default v4 -dictionaries do not enable all of v3 compatibilty names. +dictionaries do not enable all of v3 compatibility names. Yes, 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 @@ -111,9 +138,9 @@ All of the v3 compatibility names are in the RADIUS namespace. == Default Configuration ``` -#ATTRIBUTE My-Local-String 3000 string -#ATTRIBUTE My-Local-IPAddr 3001 ipaddr -#ATTRIBUTE My-Local-Integer 3002 integer +#DEFINE My-Local-String string +#DEFINE My-Local-IPAddr ipaddr +#DEFINE My-Local-Integer integer #BEGIN-PROTOCOL RADIUS #$INCLUDE ${dictdir}/radius/alias/cisco.txt #END-PROTOCOL RADIUS diff --git a/doc/antora/modules/raddb/pages/sites-available/default.adoc b/doc/antora/modules/raddb/pages/sites-available/default.adoc index 38f225fb46a..c7c5168e9a6 100644 --- a/doc/antora/modules/raddb/pages/sites-available/default.adoc +++ b/doc/antora/modules/raddb/pages/sites-available/default.adoc @@ -177,6 +177,60 @@ There is currently no configuration for other packet types. +### Local Dictionaries + +It is now possible to have dictionaries which are local to a virtual +server. The attributes defined here can be used in policies in this +virtual server. + +Any attribute defined in this section can only be used in policies in +this virtual server. The attributes are "internal", and cannot go +into a packet which is sent on the network. + +When a request is proxied internally to another virtual server, these +attributes are still sent with the proxied request. However, as the +definitions do not exist in the other virtual server, they cannot be +used in policies. + +The other virtual server can even define attributes of the same name. +That virtual server will use those definitions for its policies, and +will never match the proxied attributes. + +In all other aspects, the attributes defined here are just the same +as if they had been assigned in a dictionary file. + + +The syntax is __ followed by __. + +The __ MUST be a leaf type or a `group`. i.e. not +`struct`, `vsa`, or `vendor`. + +The __ MUST NOT exist in the `namespace` dictionary. + + + +tlv:: Define a TLV variable using _tlv { ...}_. + +The contents of the `tlv` subsection are more variable +definitions, including child `tlv`s. + + + +values:: Define a set of values for attribute __. + +The contents of the `values` section are a list of names and +values. + + +__ = __ + +The __ must be unique. + +The __ is parsed according to the data type of +the attribute. + + + ### The listen section The `listen` sections in v4 are very different from the @@ -571,6 +625,9 @@ filter_username policy. + + + Some broken equipment sends passwords with embedded zeros, i.e. the debug output will show: @@ -1244,6 +1301,17 @@ server default { } } } + dictionary { +# uint32 foo +# tlv bar { +# uint32 baz +# string arg +# } + values foo { + bar = 1 + baz = 2 + } + } listen { type = Access-Request type = Status-Server @@ -1306,6 +1374,12 @@ server default { } recv Access-Request { filter_username + &foo := bar + if (&foo == 1) { + &control.Password.Cleartext := "bob" + } + &bar.baz = 6809 + &reply.Reply-Message := "Hello from %{bar.baz}" # filter_password # operator-name # if (&User-Name =~ /@example\.com$/) { diff --git a/raddb/dictionary b/raddb/dictionary index 7878e308015..b5455ffbaa4 100644 --- a/raddb/dictionary +++ b/raddb/dictionary @@ -34,6 +34,14 @@ # dictionaries from this file. However, if the `$INCLUDE` line is # here, nothing bad will happen. +# +# ## Dictionaries per Virtual Server +# +# v4 also supports a `dictionary { ... }` subsection in a virtual +# server. If the attributes are used only in one virtual server, +# they shuld be defined there. +# + # # ## Editing the dictionary # @@ -45,13 +53,13 @@ # All local attributes and `$INCLUDE` directives should # go into this files. # -# The attribute definitions here should use DEFINE, not ATTRIBUTE. -# The DEFINE keyword is exactly like ATTRIBUTE, except it does not +# The attribute definitions here should use `DEFINE`, not `ATTRIBUTE`. +# The `DEFINE` keyword is exactly like `ATTRIBUTE`, except it does not # require an attribute number. # # As a result, there is no need to manually manage numbers. # -# Any attribute DEFINEd here will not go into a packet. +# Any attribute `DEFINE`d here will not go into a packet. # # If you do want attributes to go into a RADIUS packet, you # will need to use VSAs. This means requesting allocation @@ -106,19 +114,19 @@ # also used by v3. This lets you test that v4 works, without going # through a complex "upgrade everything" process. # -# The old v3 names are in "alias" dictionaries, in the ${dictdir} +# The old v3 names are in "alias" dictionaries, in the `${dictdir}` # directory. To find out where this directory is on your local # system, run "radiusd -h" or "radclient -h". Then look for the "-D" # command-line option, and it will tell you where the dictionary # files are located. # -# The v3 names are in ${dictdir}/radius/alias/VENDOR.txt where -# VENDOR is the name of the vendor, which is taken from the VENDOR +# The v3 names are in `${dictdir}/radius/alias/VENDOR.txt` where +# _VENDOR_ is the name of the vendor, which is taken from the `VENDOR` # definition in the v3 dictionaries. # -# You will need to add a $INCLUDE line for each vendor-specific +# You will need to add a `$INCLUD`E line for each vendor-specific # dictionary which is used by your local system. The default v4 -# dictionaries do not enable all of v3 compatibilty names. +# dictionaries do not enable all of v3 compatibility names. # # Yes, 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 diff --git a/raddb/sites-available/default b/raddb/sites-available/default index 94004144d5f..126c5134c80 100644 --- a/raddb/sites-available/default +++ b/raddb/sites-available/default @@ -198,6 +198,72 @@ server default { # } + # + # ### Local Dictionaries + # + # It is now possible to have dictionaries which are local to a virtual + # server. The attributes defined here can be used in policies in this + # virtual server. + # + # Any attribute defined in this section can only be used in policies in + # this virtual server. The attributes are "internal", and cannot go + # into a packet which is sent on the network. + # + # When a request is proxied internally to another virtual server, these + # attributes are still sent with the proxied request. However, as the + # definitions do not exist in the other virtual server, they cannot be + # used in policies. + # + # The other virtual server can even define attributes of the same name. + # That virtual server will use those definitions for its policies, and + # will never match the proxied attributes. + # + # In all other aspects, the attributes defined here are just the same + # as if they had been assigned in a dictionary file. + # + dictionary { + # + # The syntax is __ followed by __. + # + # The __ MUST be a leaf type or a `group`. i.e. not + # `struct`, `vsa`, or `vendor`. + # + # The __ MUST NOT exist in the `namespace` dictionary. + # +# uint32 foo + + # + # tlv:: Define a TLV variable using _tlv { ...}_. + # + # The contents of the `tlv` subsection are more variable + # definitions, including child `tlv`s. + # +# tlv bar { +# uint32 baz +# string arg +# } + + # + # values:: Define a set of values for attribute __. + # + # The contents of the `values` section are a list of names and + # values. + # + values foo { + # + # __ = __ + # + # The __ must be unique. + # + # The __ is parsed according to the data type of + # the attribute. + # + bar = 1 + baz = 2 + } + } + + # # ### The listen section # -- 2.47.3