Untangle Rule Syntax

From UntangleWiki
Jump to: navigation, search

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/
*?.gov/* http://www.whitehouse.gov/, http://www.opm.gov/ http://www.govtoday.co.uk/

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


Time of Day Matcher

A "Time of Day" matcher is a syntax used to describe times of day.

A Time of Day Matcher can be any of the following syntax:

Name Example Description
Any Matcher "any" matches all times of day
Single Time "11:30" matches 11:30 AM only
Range of Times "11:00-14:00" matches all the times in that range.
Inverted Range of Times "04:00-02:00" matches all the times outside that range (all times except 2am->4am)
List of Time of Day Matchers "11:30,14:00-15:00" matches 11:30 and 2pm-3pm


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