NG Firewall Rule Syntax

Untangle Server User's Guide

About Untangle Rule Syntax

Throughout the Untangle 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

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