more documentation

FreeRADIUS · Jul 29, 2019 · bdf15d4 · bdf15d4
1 parent a817ecf
commit bdf15d4
Show file tree

Hide file tree

Showing 8 changed files with 167 additions and 58 deletions.
diff --git a/doc/unlang/data.adoc b/doc/unlang/data.adoc
@@ -5,6 +5,75 @@ include::../img/header.adoc[]
 Unlang supports a number of data types. These data types can be used
 in conditional expressions or when assigning a value to an attribute.
 
+=== Basic Data Types
+
+The following data types are "basic" data types.  They are fixed-size,
+and encapsulate simple concepts such as "integer" or "IP address".
+
+These data types can be used in `unlang`, as they contain simple
+values which can be compared, or assigned to one attribute.
+
+.Basic Data Types
+[options="header"]
+[cols="15%,85%"]
+|=====
+| Data Type     | Description
+| bool		| boolean
+| date		| calendar date
+| ethernet	| Ethernet address
+| float32	| 32-bit floating point number
+| float64	| 64-bit floating point number
+| ifid		| interface ID
+| int8		| 8-bit signed integer
+| int16		| 16-bit signed integer
+| int32		| 32-bit signed integer
+| int64		| 64-bit signed integer
+| int64		| 64-bit signed integer
+| ipaddr        | IPv4 address
+| ipv6addr      | IPv6 address
+| octets        | raw binary, printed as hex strings
+| string        | printable strings
+| time_delta	| difference between two calendar dates
+| uint8		| 8-bit unsigned integer
+| uint16	| 16-bit unsigned integer
+| uint32	| 32-bit unsigned integer
+| uint64	| 64-bit unsigned integer
+|=====
+
+=== Structural Data Types
+
+The following data types are "structural", in that they form
+parent-child relationships between attributes.  These data types can
+only be used in the dictionaries.  These data types cannot be used in
+`unlang`.
+
+.Structural Data Types
+[options="header"]
+[cols="15%,85%"]
+|=====
+| struct	| structure which contains fixed-width fields
+| tlv		| type-length-value which contains other attributes
+| vsa		| Encapsulation of vendor-specific attributes
+|=====
+
+=== Protocol-Specific Data Types
+
+The following data types are used only in certain protocols.  These
+attributes can generally be used only in the dictionaries.  They
+cannot generally be used in `unlang`.
+
+.Protocol Specific Data Types
+[options="header"]
+[cols="15%,15%,70%"]
+|=====
+| Data Type     | Protocol | Description
+| abinary       | RADIUS   | Ascend binary filters
+| extended      | RADIUS   | attributes which "extend" the number space
+| ipv4prefix    | RADIUS   | IPv4 network with address and prefix length
+| ipv6prefix    | RADIUS   | IPv6 network with address and prefix length
+|=====
+
+
 // Copyright (C) 2019 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // Development of this documentation was sponsored by Network RADIUS SAS.
 include::../img/footer.adoc[]
diff --git a/doc/unlang/data_double.adoc b/doc/unlang/data_double.adoc
@@ -2,7 +2,7 @@ include::../img/header.adoc[]
 
 == Double-Quoted Strings
 
-"string"
+`"string"`
 
 A double-quoted string is interpreted via the usual rules in
 programming languages for double quoted strings. The double-quote
@@ -14,18 +14,21 @@ The main difference between the single and double quoted strings is
 that the double quoted strings can be dynamically expanded. The syntax
 `${...}` is used for parse-time expansion and `%{...}` is used for
 run-time expansion. The difference between the two methods is that the
-`${...}` form is expanded when the server loads the configuration files
-and is valid anywhere in the configuration files. The `%{...}` form is
-valid only in conditional expressions and attribute assignments and is
-otherwise used verbatim.
+`${...}` form is expanded when the server loads the configuration
+files and is valid anywhere in the configuration files. The `%{...}`
+link:xlat.adoc[string expansion] form is valid only in conditional
+expressions and attribute assignments.
 
 The output of the dynamic expansion can be interpreted as a string,
-a number, or an IP address, depending on its context. In general, it is
-safest to assume that the result will be interpreted as a string.
-
-Note that the language is not strongly typed, so the text `"0000"`
-can be interpreted as a data type "integer", having value zero, or a
-data type "string", having value `"0000"`.
+a number, or an IP address, depending on its context.
+
+Note that the interpretation of text _strongly_ depends on the
+context.  The text `"0000"` can be interpreted as a data type
+"integer", having value zero, or a data type "string", having value
+`"0000"`.  In general when a particular piece of text is used, it is
+used with the context of a known attribute.  That attribute has a
+link:data.adoc[data type], and the text will be interpreted as that
+data type.
 
 *Examples:*
 

diff --git a/doc/unlang/data_numb.adoc b/doc/unlang/data_numb.adoc
@@ -8,20 +8,6 @@ include::../img/header.adoc[]
 `563`
 
 Numbers are unsigned integers that are composed of decimal digits.
-Signed numbers, floating point, hex, and octal numbers are not supported
-in Unlang.
-
-These limitations are largely a result of the limitations of the
-underlying protocol. There is no way to transport signed numbers or
-floating point numbers in RADIUS, so there is no need to perform signed
-or floating point calculations.
-
-The maximum value for a number is machine-dependent but is at least
-32 bits or 4,294,967,296. In some cases, it may be necessary to perform
-calculations on numbers larger than 32 bits, as when calculating total
-data traffic to or from a user. In those cases, the calculations should
-either be one carefully to avoid 32-bit overflow or be done using real
-programming language.
 
 // Copyright (C) 2019 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // Development of this documentation was sponsored by Network RADIUS SAS.

diff --git a/doc/unlang/data_simple.adoc b/doc/unlang/data_simple.adoc
diff --git a/doc/unlang/data_single.adoc b/doc/unlang/data_single.adoc
@@ -2,13 +2,12 @@ include::../img/header.adoc[]
 
 == Single Quoted Strings
 
-'string'
+`'string'`
 
-A single quoted string is interpreted without any dynamic string
-expansion. The quotes allow the string to contain spaces, which are not
-allowed in the `word` form described in the previous section. The single
-quote character can be placed in such a string by escaping it with a
-backslash.
+A single-quoted string is interpreted without any dynamic string
+expansion. The quotes allow the string to contain spaces, among other
+special characters. The single quote character can be placed in such a
+string by escaping it with a backslash.
 
 *Examples:*
 

diff --git a/doc/unlang/data_unquoted.adoc b/doc/unlang/data_unquoted.adoc
@@ -0,0 +1,24 @@
+include::../img/header.adoc[]
+
+== Unquoted Text
+
+*Examples:*
+
+`Hello` +
+`192.168.0.1` +
+`00:01:02:03:04:05`
+
+Where a series of characters cannot be parsed as a decimal number,
+they are interpreted as a simple string composed of one word. This
+word is delimited by spaces, or by other tokens, such as `)` in
+conditional expressions.
+
+This unquoted text is interpreted as simple strings and are generally
+equivalent to placing the string in single quotes.
+
+The interpretation of the text depends on the context, which is
+usually defined by an attribute which has a link:data.adoc[data type].
+
+// Copyright (C) 2019 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
+// Development of this documentation was sponsored by Network RADIUS SAS.
+include::../img/footer.adoc[]
diff --git a/doc/unlang/home.adoc b/doc/unlang/home.adoc
@@ -93,6 +93,43 @@ update reply {
 }
 ----
 
+=== Data Types
+
+Each attribute used by the server has an associated
+link:data.adoc[data type].  The `unlang` interpreter enforces
+restrictions on assignments, so that only valid data types can be
+assigned to an attribute.  Invalid assignments result in a run-time
+error.
+
+The interpreter is flexible when parsing data types.  For example, a
+particular attribute may be of data type `ipaddr` for IPv4 address.
+The interpreter will accept the following strings as valid IPv4 addresses:
+
+`192.168.0.2`:: link:data_unquoted.adoc[Unquoted text], interpreted as the data type
+
+`'192.168.0.2'`:: link:data_single.adoc[Single-quoted string], interpreted as the data type.
+The single-quoted string form is most useful when the data type
+contains special characters that may otherwise confuse the parser.
+
+`"192.168.0.2"`:: link:data_double.adoc[Double-quoted string].
+
+The contents of the string are dynamically expanded as described
+above.  The resulting output is then interpreted as the given data
+type.
+
+Similar processing rules are applied when parsing assignments and
+comparisons, for all attributes and data types.
+
+.Example
+[source,unlang]
+----
+update reply {
+	&Framed-IP-Address := 192.0.2
+	&Session-Timeout := 5
+	&Reply-Message := "hello"
+}
+----
+
 === Design Goals of Unlang
 
 The goal of `unlang` is to allow simple policies to be written with

diff --git a/doc/unlang/update.adoc b/doc/unlang/update.adoc
@@ -106,8 +106,10 @@ finishes, it is deleted, and is no longer accessible to the parent.
 
 === Server Attributes
 
-The _<server-attribute>_ field is usually an attribute name such as
-`&Reply-Message`.
+The _<server-attribute>_ field is an attribute name, such as
+`&Reply-Message`.  The attribute name may also be prefixed with a
+_<list>_ qualifier, which over-rides the _<list>_ given at the start
+of the `update` section.
 
 NOTE: In version 3, the leading `&` was optional.  In version 4, the
 leading `&` is required.
@@ -171,12 +173,24 @@ For IP addresses, the operators `>`, `>=`, `<`, and `<=` check for
 membership in a network.  The _<value>_ field should then be a IP
 network, given in `address/mask` format.
 
-IMPORTANT: In version 3, some filtering attributes would _create_ the
+IMPORTANT: In version 3, some filtering operators would _create_ the
 attribute if it did not exist in the destination list.  In version 4,
-this functionality has been removed.  Instead version 4 only performs
+this functionality has been removed.  Instead, version 4 only performs
 _filtering_ of the attributes.  That is, the filtering operators will
 modify or delete attributes, but they will never create an attribute.
 
+=== Values
+
+The _<value>_ field is the value which is assigned to the
+_<server-attribute>_.  The interpretation of the _<value>_ field
+depends on the data type of the contents.  For example, if the string
+`"192.0.2.1"` is assigned to an attribute of the `string` data type,
+then the result is an ASCII string containing that value.  However, if
+the same string is assigned to an attribute of the `ipaddr` data type,
+then the result is a 32-bit IPv4 address, with binary value `0xc0000201`.
+
+Th
+
 .Example
 [source,unlang]
 ----