From: Alan T. DeKok <aland@freeradius.org>
Date: Fri, 17 Feb 2023 02:43:06 +0000 (-0500)
Subject: more updates for dictionaries.
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e934deecfa0cb042153d8e311b458dc12d0306fe;p=thirdparty%2Ffreeradius-server.git

more updates for dictionaries.

For now, BEGIN-FOO and END-FOO are not (yet) documented.
---

diff --git a/doc/antora/modules/reference/pages/dictionary/flags.adoc b/doc/antora/modules/reference/pages/dictionary/flags.adoc
new file mode 100644
index 00000000000..499d20b27ad
--- /dev/null
+++ b/doc/antora/modules/reference/pages/dictionary/flags.adoc
@@ -0,0 +1,25 @@
+= The FLAG keyword
+
+.Syntax
+----
+FLAG <value>
+----
+
+.Description
+The `FLAG` keyword defines a "default" set of flags which are used for
+processing the rest of the current dictionary file.
+
+The main purpose of the `FLAG` keyword is to avoid having an extra
+field for every `ATTRIBUTE` definition.
+
+<value>:: The flag value.
++
+For now, only `internal` is supported.
+
+.Examples
+----
+FLAG internal
+----
+
+// 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/dictionary/index.adoc b/doc/antora/modules/reference/pages/dictionary/index.adoc
index 8d1d0eebd6f..e3efc82329c 100644
--- a/doc/antora/modules/reference/pages/dictionary/index.adoc
+++ b/doc/antora/modules/reference/pages/dictionary/index.adoc
@@ -90,6 +90,16 @@ If there is still a need to use the old names, the
 xref:dictionary/alias.adoc[ALIAS] keyword can help.  See
 `raddb/dictionary` for additional documentation.
 
+=== Names matter, not definitions
+
+Names occur in many places, such as in
+xref:dictionary/attribute.adoc[ATTRIBUTE] definitions,
+xref:dictionary/define.adoc[DEFINE],
+xref:dictionary/member.adoc[MEMBER],
+xref:dictionary/struct.adoc[STRUCT], etc.  We generally refer to all
+of these entities as being 'attributes', no matter how the name was
+defined.
+
 == Files and Location
 
 The dictionaries are placed into a `share` directory, which is usually
@@ -127,12 +137,12 @@ xref:dictionary/attribute.adoc[ATTRIBUTE] and xref:dictionary/value.adoc[VALUE].
 | xref:dictionary/alias.adoc[ALIAS]          | Define a name which references an `ATTRIBUTE`
 | xref:dictionary/attribute.adoc[ATTRIBUTE]  | Define a name, number, and data type mapping
 | xref:dictionary/define.adoc[DEFINE]        | Define a name and data type mapping
-| xref:dictionary/enum.adoc[ENUM]            | Define a named enumeration of values for use with multiple `ATTRIBUTE`s
+| xref:dictionary/enum.adoc[ENUM]            | Define a named enumeration of values for use with multiple ``ATTRIBUTE``s
 | xref:dictionary/flags.adoc[FLAGS]          | Set flags for subsequent definitions
 | xref:dictionary/include.adoc[$INCLUDE]     | Include another dictionary file
 | xref:dictionary/member.adoc[MEMBER]        | Define a member of a `STRUCT`
 | xref:dictionary/protocol.adoc[PROTOCOL]    | Define a protocol like `RADIUS` or `DHCPv4`
-| xref:dictionary/struct.adoc[STRUCT]        | Define a structure which can contain `MEMBER`s
+| xref:dictionary/struct.adoc[STRUCT]        | Define a structure which can contain ``MEMBER``s
 | xref:dictionary/value.adoc[VALUE]          | Define a name for a particular value of an `ATTRIBUTE`
 | xref:dictionary/vendor.adoc[VENDOR]        | Define a name and number for a vendor
 |=====
diff --git a/doc/antora/modules/reference/pages/dictionary/member.adoc b/doc/antora/modules/reference/pages/dictionary/member.adoc
index bd202cde419..6e97bda1f92 100644
--- a/doc/antora/modules/reference/pages/dictionary/member.adoc
+++ b/doc/antora/modules/reference/pages/dictionary/member.adoc
@@ -33,6 +33,8 @@ flags.
 Please see the protocol dictionaries for examples of these flags.
 Only the flags which are used in a protocol dictionary are valid,
 and those flags are only valid for that protocol dictionary.
++
+The `key` flag can only be used for ``MEMBER``s where the data type is `uint8`, `uint16`, or `uint32`.
 
 Common flags and meanings
 [options="header"]
@@ -41,6 +43,7 @@ Common flags and meanings
 | Name         | Description
 | `array`      | For fixed-size types, declare that the contents of the packet can have an array of this value.
 | `clone=...`  | For `tlv` types, clone (or copy) child definitions from another `tlv` type
+| `key`        | This member is a "key" type.  The struct can have different xref:dictionary/struct.adoc[STRUCT] children depending on the value of the key.
 |=====
 
 .Examples
diff --git a/doc/antora/modules/reference/pages/dictionary/protocol.adoc b/doc/antora/modules/reference/pages/dictionary/protocol.adoc
new file mode 100644
index 00000000000..6b860ce1616
--- /dev/null
+++ b/doc/antora/modules/reference/pages/dictionary/protocol.adoc
@@ -0,0 +1,34 @@
+= The PROTOCOL keyword
+
+.Syntax
+----
+PROTOCOL <name> <value> [<option>]
+----
+
+.Description
+
+The `PROTOCOL` keyword defines a new top-level protocol such as `RADIUS`, `DHCPv4`, etc.
+
+
+<name>:: The name of the protocol
+
+<value>:: A number associated with the protocol.
++
+These numbers have no meaning outside of FreeRADIUS, and are assigned by the FreeRADIUS developers.
+
+<option>:: The only supported option is `verify=lib`.
++
+The option tells the server to load a dynamic library
+``libfreeradius-``_<name>_.  It then uses special callbacks in that
+library to verify the contents of the protocol dictionary.
+
+The `PROTOCOL` keyword is documented for completeness, but it should
+only be used by the FreeRADIUS developers.
+
+.Examples
+----
+PROTOCOL RADIUS 1 verify=lib
+----
+
+// 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/dictionary/struct.adoc b/doc/antora/modules/reference/pages/dictionary/struct.adoc
new file mode 100644
index 00000000000..10b33413af7
--- /dev/null
+++ b/doc/antora/modules/reference/pages/dictionary/struct.adoc
@@ -0,0 +1,65 @@
+= The STRUCT keyword
+
+.Syntax
+----
+STRUCT <name> <field> <value> [<flags>]
+----
+
+.Description
+The `STRUCT` keyword defines a child structure of a previous `struct`,
+which is keyed by a particular xref:dictionary/member.adoc[MEMBER].
+
+Many protocols are defined as a _header_ which contains information
+about the protocol, and a _data_ portion which contains data carried
+by that _header_.  The _header_ usually includes a _type_ field, which
+defines how the _data_ portion is interpreted.  The `STRUCT` keyword
+allows the server to automatically decode these protocols, and all of
+their contents.
+
+<name>:: The name of the attribute.  The name can contain alphanumeric
+characters, `-`, and `_`.  The name should be short and descriptive.
++
+As the names are hierarchical, the name is scoped to its parent.  So
+the name `Counter` can mean different things, depending on its
+context.
+
+<field>:: The name of a previous xref:dictionary/member.adoc[MEMBER]
+which has been marked up with the word `key` in the `flags` field. 
++
+In most cases, the _<field>_ reference is simply the name of a field
+in the attribute of type `struct` which was defined immediately before
+this definition.
++
+The _<field>_ reference can also be an OID-style name, as in
+`Client-Id.Type`.  The name is always looked up in the current dictionary.
+References cannot be to fields in other dictionaries.
+
+<value>:: When the _<field>_ has this value, the data is interpreted
+as this `struct`.  Numbers can be specified as decimal (`19`), or as
+hex (`0xffee`).
+
+<flags>:: Can only be `length=uint16`.  When encoding or decoding the
+structure, it is prefixed by a `uint16` field containing the length of
+the structure.
+
+Common flags and meanings
+[options="header"]
+[cols="30%,70%"]
+|=====
+| Name             | Description
+| `length=uint16`  | When encoding or decoding the structure, it is prefixed by a `uint16` field containing the length of the structure.
+|=====
+
+
+.Examples
+----
+ATTRIBUTE Information 1 struct
+MEMBER Type uint8 key
+
+STRUCT Foo Type 1
+MEMBER Bar uint16
+MEMBER Baz uint16
+----
+
+// 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/dictionary/value.adoc b/doc/antora/modules/reference/pages/dictionary/value.adoc
new file mode 100644
index 00000000000..06102daae70
--- /dev/null
+++ b/doc/antora/modules/reference/pages/dictionary/value.adoc
@@ -0,0 +1,44 @@
+= The VALUE keyword
+
+.Syntax
+----
+VALUE <attribute-name> <name> <data>
+----
+
+.Description
+The `VALUE` keyword defines name for a particular value of an xref:dictionary/attribute.adoc[ATTRIBUTE] or xref:dictionary/member.adoc[MEMBER].
+
+In many cases, it is useful to refer to values by name, for the same
+reason it is useful to refer to attributes by name.
+
+<attribute-name>:: The name of the attribute, which must exist.
++
+It is not possible to define a `VALUE` for structural attributes, such
+as `tlv`, `struct`, `group`, etc.  It is also not possible to define a
+`VALUE` for `string` attributes, or for an xref:dictionary/alias.adoc[ALIAS].
+
+<name>:: The name of the `VALUE`.  It can be used instead of the `<data>`.
++
+Where an attribute has a `VALUE` defined, the `<name>` will be be
+printed instead of the corresponding `<data>`.  It is still possible
+to assign a `<data>` value to an attribute, as the `<name>` is a
+synonym for the `<data>`, and does not replace the `<data>`
+
+== Data Types and VALUEs
+
+Unlike earlier versions of the server, ``VALUE``s are not limited to
+`integer` data types.  It is possible to define a `VALUE` for any
+non-structural data type.  That is, any data type which has values,
+and does not contain other attributes.
+
+It is therefore not possible to define ``VALUE``s for data types
+`group`, `struct`, `tlv`, `vendor`, etc.
+
+.Examples
+----
+VALUE Service-Type Login-User 1
+VALUE Framed-IP-Address broadcast 255.255.255.255
+----
+
+// 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/dictionary/vendor.adoc b/doc/antora/modules/reference/pages/dictionary/vendor.adoc
new file mode 100644
index 00000000000..c44f7e69460
--- /dev/null
+++ b/doc/antora/modules/reference/pages/dictionary/vendor.adoc
@@ -0,0 +1,32 @@
+= The VENDOR keyword
+
+.Syntax
+----
+VENDOR <name> <number> [<option>]
+----
+
+.Description
+
+The `VENDOR` keyword defines a name to number mapping for vendor
+http://www.iana.org/enterprise-numbers.txt[private enterprise codes].
+These codes are assigned by the Internet Assigned Numbers Authority
+(http://iana.org[IANA]) to each vendor.
+
+
+<name>:: The name of the vendor.
+
+<numver>:: The number associated with the vendor.
+
+<option>:: The protocol-specific option associated with the vendor definition.
++
+Please see the protocol dictionaries for examples of these options.
+Only the options which are used in a protocol dictionary are valid,
+and those options are only valid for that protocol dictionary.
+
+.Examples
+----
+VENDOR Cisco 1
+----
+
+// Copyright (C) 2023 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
+// Development of this documentation was sponsored by Network RADIUS SAS.