.Example
[source,unlang]
----
-(data =~ /regex/)
-(data =~ /regex/i)
+(<subject> =~ /<pattern>/)
+(<subject> =~ /<pattern>/[imsux])
-(data !~ /regex/)
-(data !~ /regex/i)
+(<subject> !~ /<pattern>/)
+(<subject> !~ /<pattern>/[imsux])
----
+== Matching
The regular expression operators perform regular expression matching
-on the data. The `data` field can be an attribute reference or data,
-as with the other xref:condition/cmp.adoc[comparison] operators. The `/regex/`
+on the data. The `<subject>` field can be an attribute reference or data,
+as with the other xref:condition/cmp.adoc[comparison] operators. The `/<pattern>/`
field must be a valid regular expression.
The `=~` operator evaluates to `true` when `data` matches the
-`/regex/` expression. Otherwise, it evaluates to `false`.
+`/<pattern>/`. Otherwise, it evaluates to `false`.
The `!~` operator evaluates to `true` when `data` does not match the
-`/regex/` expression. Otherwise, it evaluates to `true`.
+`/<pattern>/`. Otherwise, it evaluates to `true`.
The regular expression comparison is performed on the _string
representation_ of the left side of the comparison. That is, if the
behave is if the attribute was printed to a string, and the match was
performed on the resulting string.
+== Dialects
+
The syntax of the regular expression is defined by the regular
expression library available on the local system.
+
FreeRADIUS currently supports:
* link:https://www.pcre.org/original/doc/html/[libpcre] and
provide
link:https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions[Perl
Compatible Regular expressions].
-* link:http://en.wikipedia.org/wiki/Regular_expression#POSIX_basic_and_extended[
+* Functions provided by the local libc implementation, usually
+link:http://en.wikipedia.org/wiki/Regular_expression#POSIX_basic_and_extended[
Posix regular expressions].
-The regular expression may be followed by a single `i` character. The
-`i` indicates that the regular expression match should be done in a
-case-insensitive fashion.
+[TIP]
+====
+Use the output of `radiusd -Xxv` to determine the regular expression library is in use.
+
+[source,shell]
+----
+...
+Debug : regex-pcre : no
+Debug : regex-pcre2 : yes
+Debug : regex-posix : no
+Debug : regex-posix-extended : no
+Debug : regex-binsafe : yes
+...
+Debug : pcre2 : 10.33 (2019-04-16) - retrieved at build time
+----
+====
+
+[WARNING]
+====
+Depending on the regular expression library or libc implementation the server
+was built against, the pattern matching function available may not be binary
+safe (see `regex-binsafe` in the output of `radiusd -Xxv`).
+
+If a binary safe regex match function is not available, and a match is
+attempted against a subject that contains one or more `NUL` ('\0') bytes, the
+match will be aborted, and a warning will be emitted.
+====
+
+== Flags
+
+The regular expression `/<pattern>/` may be followed by one or more flag
+characters. Again, which flags are available depends on the regular expression
+library the server was built with. Multiple may be set per `/pattern/`.
+
+.Flags and their uses
+
+[options="header"]
+|=====
+| Flag Character | Available in | Effect
+| `i` | All | Enable case-insensitive matching.
+| `m` | All | '^' and '$' match newlines within the subject.
+| `s` | libpcre[2] | '.' matches anything, including newlines.
+| `u` | libpcre[2] | Treats subjects as UTF8. Invalid UTF8
+ sequences will result in the match failing.
+ |`x` | libpcre[2] | Allows comments in expressions by ignoring
+ whitespace, and text between '#' and the next
+ newline character.
+|=====
+
+== Subcapture groups
When the `=~` operator is used, then parentheses in the regular
expression will define variables that contain the matching text.
-The special variable `%\{0\}` contains a copy of the result of
-evaluating the data field. The variables `%\{1\}` and following refer
-to the subsequent matched substring in the regular expression.
+The special expansion `+%{0}+` expands to the portion of the subject that
+matched. The expansions `+%{1}+`..`+%{32}+` expand to the contents of any
+capture groups in the pattern.
+
+When using libpcre[2], named capture groups may also be accessed using the
+built-in expansion `+%{regex:<named capture group}+`.
-Please see the xref:xlat/predefined.adoc#_0[xlat documentation] for
+Please see the xref:xlat/predefined.adoc#_0_32[xlat documentation] for
more information on regular expression matching.
.Example
== Miscellaneous Expansions
-=== +%{0}+
+=== +%{0}+..+%{32}+
-Refers to the string that was last used to match a regular expression.
-The variables `+%{1}+` and following refer to the subsequent matched
-substring in the regular expression.
+`+%{0}+` expands to the portion of the subject that matched the last regular
+expression evaluated. `+%{1}+`..`+%{32}+` expand to the contents of any capture
+groups in the pattern.
+
+Every time a regular expression is evaluated, whether it matches or not,
+the numbered capture group values will be cleared.
+
+=== +%{regex:<named capture group>}+
+
+Return named subcapture value from the last regular expression evaluated.
+
+Results of named capture groups are available using the `%{regex:<named capture
+group>}` expansion. They will also be accessible using the numbered expansions
+described <<_0_32,above>>.
+
+Every time a regular expression is evaluated, whether it matches or not,
+the named capture group values will be cleared.
+
+[NOTE]
+====
+This expansion is only available if the server is built with libpcre or libpcre2.
+Use the output of `radiusd -Xxv` to determine the regular expression library in use.
+
+[source,shell]
+----
+...
+Debug : regex-pcre : no
+Debug : regex-pcre2 : yes
+Debug : regex-posix : no
+Debug : regex-posix-extended : no
+Debug : regex-binsafe : yes
+...
+Debug : pcre2 : 10.33 (2019-04-16) - retrieved at build time
+----
+====
=== +%{nexttime:<time>}+
.Example:
-With the current time at 16:18, `%{nexttime:1h}` will expand to
-`2520`.
+With the current time at 16:18, `%{nexttime:1h}` will expand to `2520`.
[source,unlang]
----
The source/destination ports associated with the packet.
-=== +%{regex:<capture_group>}+
-
-Return named subcapture value from previous regex.
-
-If a regular expression match has previously been performed, then the
-special variable `+%{0}+` will contain a copy of the matched portion of
-the input string.
-
-If the server is built with `libpcre` or `libpcre2`, the results of named
-capture groups are available using the `%{regex:capture group}`
-expansion. They will also be accessible using the variables described
-above.
-
-Every time a regular expression is evaluated, whether it matches or not,
-the capture group values will be cleared.
-
.Return: _string_.
.Example
projects / thirdparty / freeradius-server.git / commitdiff
