From: Alan T. DeKok Date: Mon, 1 Aug 2022 12:03:34 +0000 (-0400) Subject: deprecate filter documentation X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=29ebcbf3c673c1a6dd1218d12716f4120183d3ab;p=thirdparty%2Ffreeradius-server.git deprecate filter documentation --- diff --git a/doc/antora/modules/reference/pages/unlang/filter.adoc b/doc/antora/modules/reference/pages/unlang/filter.adoc index 55b46b7262c..6cd6b2e5126 100644 --- a/doc/antora/modules/reference/pages/unlang/filter.adoc +++ b/doc/antora/modules/reference/pages/unlang/filter.adoc @@ -1,131 +1,11 @@ = The filter Statement -.Syntax -[source,unlang] ----- -filter [ ] { - - ... -} ----- +The `filter` statement is deprecated. It may work, but it will be +removed in a future release. The `filter` statement does not support +the data types of `group` and `struct`. -The `filter` statement filters attributes in, the named __. -Attributes which do not match the filter conditions are removed. -Attributes that are not named in the `filter` section are unchanged. - -The `filter` statement consists of the following syntax elements: - -.: The attribute list which will be filtered. The list is -usually `request`, `reply`, or `control`. -+ -If the __ qualifier is omitted, then each entry inside of the -`filter` section *must* be prefixed with a list name. For example, -`&request.User-Name ...` - -:: The server attribute which is being filtered via the given -__. - -:: The operator such as `<`, `>=`, etc. - -:: The value which is used to filter the attribute. If the -field is a double-quoted string, it undergoes xref:xlat/index.adoc[string -expansion], and the resulting value is used to filter the attribute. - -The change process is atomic, in that either all of the attributes are -modified, or none of them are modified. If the `filter` fails for any -reason, then all of the results are discarded, and the `filter` does -not affect any server attributes. - -.Example -[source,unlang] ----- -filter reply { - &Session-Timeout <= 3600 -} ----- - -== Lists - -The __ field sets the attribute list that will be filter. If -the __ qualifier is omitted, then each entry inside of the -`filter` section *must* be prefixed with a list name. For example, -`&request.User-Name ...` - -Please see the xref:unlang/list.adoc[list] page for valid list names. - -== Server Attributes - -The __ field is an attribute name, such as -`&Reply-Message`. The attribute name may also be prefixed with a -__ qualifier, which overrides the __ given at the start -of the `filter` section. - -NOTE: In version 3, the leading `&` was optional. In version 4, the -leading `&` is required. - -== Editing Operators - -The `` field is used to define how the values are filtered -Different operators allow attributes to be added, deleted, or -replaced, as defined below. - -== Filtering Operators - -The following operators may also be used in addition to the ones -listed above. These operators use the __ and -__ fields to enforce limits on all attributes in the given -__, and to edit attributes which have a matching -__ name. All other attributes are ignored. - -.Filtering Operators -[options="header] -[cols="10%,90%"] -|===== -| Operator | Description -| -= | Remove all attributes from the list that match __. -| == | Keep only the attributes in the list that match __ -| < | Keep only the attributes in the list that have values less than __. -| \<= | Keep only the attributes in the list that have values less than or equal to __. -| > | Keep only the attributes in the list that have values greater than __. -| >= | Keep only the attributes in the list that have values greater than or equal to __. -| !* | Delete all occurances of the attribute, no matter what the value. -| =~ | Keep only the attributes in the list which match the regular expression given in __. -| !~ | Keep only the attributes in the list which do not match the regular expression given in __. -|===== - -The `==` operator is very different from the `=` operator listed -above. The `=` operator is used to add new attributes to the list, -while the `==` operator removes all attributes that do not match the -given value. - -For IP addresses, the operators `>`, `>=`, `<`, and `\<=` check for -membership in a network. The __ field should then be a IP -network, given in `address/mask` format. - -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 -_filtering_ of the attributes. That is, the filtering operators will -modify or delete attributes, but they will never create an attribute. - -== Values - -The __ field is the value which is used to filter the -__. The interpretation of the __ 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`. - -.Example -[source,unlang] ----- -filter reply { - &Session-Timeout <= 3600 -} ----- +All new configuration should use the new xref:unlang/edit.adoc[edit] +syntax. It is more flexible and more powerful than `filter` sections. // Copyright (C) 2021 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // Development of this documentation was sponsored by Network RADIUS SAS.