NG Firewall Rule Syntax
About NG Firewall Rule Syntax
Throughout the NG Firewall Server Administrative Interface, Administrators must enter information about their network and web locations. In some cases the values entered can be exact, and in others the text entered indicates a range of values.
The following describe common syntaxes to describe IPs, ports, strings, URLs, etc. The Rules documentation describes which syntax is used for which fields.
IP Matcher
IP Matcher syntax is a that describes an IP address or set of IP addresses. This can be used, for example, in Firewall or Policy Manager rules to match against certain traffic.
IP Matcher can be any of the following:
| Name | Example | Description |
|---|---|---|
| Any Matcher | any | matches all addresses |
| Single IP | 1.2.3.4 | matches the single IP address |
| Range of IPs | 1.2.3.4-1.2.3.100 | matches all the IPs in the range |
| CIDR range | 192.168.1.0/24 | matches all the IPs in that subnet |
| List of IP Matchers | 1.2.3.4,1.2.3.5,1.2.3.10-1.2.3.15 | matches all the IPs in the list and in that range |
Port Matcher
Int Matcher syntax is a that describes a integer or set of integers. This can be used, for example, in Firewall or Policy Manager rules to match against certain traffic destination ports.
Port Matcher can be any of the following:
| Name | Example | Description |
|---|---|---|
| Any | any | matches all |
| Single | 80 | matches that single integer |
| Greater Than | >1234 | matches all values greater than 1234 |
| Less Than | <1234 | matches all values less than 1234 |
| Range | 1024-65535 | matches all values within the range (inclusive) |
| List of Int Matchers | 80,443,8080-8088 | matches all 80, 443, and 8080 through 8088 |
Important notes:
- Floating point numbers are also allowed and apply in some cases. (example: ">2.5")
URL Matcher
The URL Matcher Syntax describes all or part of a website.
| Example | Matches | Does not Match |
|---|---|---|
| example.com | http://example.com/, http://www.example.com/, http://example.com/foo | http://example.net |
| example.com/bar | http://example.com/bar/test.html, http://www.example.com/bar | http://example.com/foo |
| *porn* | http://pornsite.com/ | http://foobar.com |
| example???.com/ | http://example123.com | http://example1.com |
| example.com/foo | http://example.com/foo, http://abc.example.com/foobar | http://example.com/ |
URL Matchers use globs which are describe more in depth in the Glob Matcher documentation.
Important notes:
- The left side of the rule is anchored with the regular expression "^([a-zA-Z_0-9-]*\.)*". "foo.com" will match only "foo.com" and "abc.foo.com" but not "afoo.com"
- The right side of the rule is anchored with with the regular expression ".*$". "foo.com" will match "foo.com/test.html" because it is actually "foo.com.*$". "foo.com/bar" is "foo.com/bar.*$" which will match "foo.com/bar/baz" and "foo.com/bar2". Also "foo" becomes "foo.*" which will match "foobar.com" and "foo.com"
- "http://" and "https://" are stripped from the rule.
- URIs are case-sensitive, but domains are not. The URL Matcher is case sensitive, but domains are converted to lowercase before evaluation because they should not be case sensitive. Any part of the matcher that should match against the domain should be lower case in the rule.
- "www." is automatically stripped from the rule. This is to prevent the frequent misconfiguration of users adding a block rule for something like "www.pornsite.com" which blocks "www.pornsite.com" but not just "pornsite.com." If you truly desire to only match www.pornsite.com and not pornsite.com then use "*www.pornsite.com" because the "*" will match zero or more characters.
- Similarly "*." is stripped from the rule for the same reason as above. If you truly want all subdomains but not the main domain matched, you can accomplish this by doing "*?.foo.com"
User Matcher
User Matcher syntax is a that describes an user or set of users. This can be used, for example, in Policy Manager or Bandwidth Control rules to match against certain traffic.
User Matcher can be any of the following:
| Name | Example | Description |
|---|---|---|
| Any Authenticated User | [authenticated] | matches all identified or authenticated users (excluding null) |
| Unauthenticated User | [unauthenticated] | matches all unidentified or unauthenticated users (including null) |
| Username | myuser | matches the "myuser" user |
| Glob Matcher | m*r | matches the "myuser" user |
| List of User Matchers | myuser1,myuser2 | matches "myuser1" and "myuser2" |
Group Matcher
Group Matcher syntax is a that describes an user or set of users. This can be used, for example, in Policy Manager or Bandwidth Control rules to match against certain traffic.
Group Matcher can be any of the following:
| Name | Example | Description |
|---|---|---|
| Any Matcher | [any] | matches all groups |
| None Matcher | [none] | matches no groups |
| Groupname | mygroup | matches the "mygroup" group |
| Glob Matcher | m*p | matches the "mygroup" group |
| List of Group Matchers | mygroup1,mygroup2 | matches "mygroup1" and "mygroup2" |
Glob Matcher
A Glob is a common way to match strings of characters against rules. An Untangle glob is similar to the syntax commonly used on Microsoft OSs to match filenames (example: "rm *.exe").
A glob matcher has two special characters: "*" means 0 or more of any characters (excluding return charater) and "?" means exactly 1 of any character (excluding return character).
| Example | String | Description |
|---|---|---|
| String | XYZ | matches "XYZ" but NOT "xYZ" and NOT "XYZZ" |
| String with * | X*Z | matches "XZ" and "XYZ" and "XYYZ" and "XyyyabcZ" but NOT "xYZ" and NOT "XYZA" |
| String with * | X*Z* | matches "XZ" and "XYZ" and "XYYZ" and "XyyyabcZ" and "XYZA" but NOT "xYZ" |
| String with ? | X?Z | matches "XYZ" and "XyZ" but NOT match "XZ" or "XYYZ" |
| List of Globs | X,Z | matches "X" and "Z" but NOT match "Y" or "X,Z" |
Globs are often used in rules like URL rules and filename rules to match various strings. The left and rights side are implicitly anchored. If you wish to match if a string contains the match you will need to use "*foo*".
For those familiar with regular expression you can derive the glob equivalent by doing the following:
- replace "." with "\." to escape the special meaning of "." in regular expressions
- replace "?" with "." to match any character
- replace "*" with ".*" to match zero or more characters
Note:
- "*" matches all values except null/unset
- "" matches null and nothing else
- All glob matching is case insensitive for domains but case sensitive for all other matches.
Time of Day Matcher
Day of Week Matcher
A "Day of Week" matcher is a syntax used to describe days of the week.
A Day of Week Matcher can be any of the following syntax:
| Name | Example | Description |
|---|---|---|
| Any Matcher | "any" | matches all days of the week |
| Single Day (English name) | "tuesday" | matches Tuesday only |
| Single Day (Digit 1-7) | "1" | matches Sunday only |
| List of Time of Day Matchers | "monday,2,wednesday" | matches Monday, Tuesday, and Wednesday |
