For now, BEGIN-FOO and END-FOO are not (yet) documented.
--- /dev/null
+= 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.
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
| 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
|=====
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"]
| 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
--- /dev/null
+= 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.
--- /dev/null
+= 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.
--- /dev/null
+= 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.
--- /dev/null
+= 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.
projects / thirdparty / freeradius-server.git / commitdiff
