Rules

Rules

Rules are used frequently in Untangle and many other firewalls. Rules are very powerful, but can sometimes be difficult to configure. This documentation describes how rules work and gives some basic examples and some common mistakes to avoid. Many applications use rules like Firewall, Captive Portal, Application Control, Bandwidth Control, etc. All of these rules essentially share the same logic.

Basics

Rules are configured by the user to categorize and act upon traffic. For example, Firewall uses rules to determine whether to block or pass traffic. Bandwidth Control uses rules to determine how to prioritize a session.

Rules are evaluated in order from top to bottom against sessions (not packets!). If a rule matches then the action from that rule is performed and no more rules are evaluated. If no matching rule is found the behavior is defined by the application, which is usually doing nothing.

This is similar to other firewalls. Untangle rules are "quick" rules which means the first match is always used. Unlike some other firewalls, Untangle evaluates against sessions, not packets. This means that the "Source Address" will be the initiator of the session and the "Destination Address" will be the server address the client is connecting to, and the same is true for "Source Port" and "Destination Port."

Each rule has several properties:

• An enable checkbox
• A name/description
• A set of conditions
• An action or set of actions

Rule Anatomy

The enable checkbox determines if the rule is evaluated. If the enable checkbox is not checked, the rule is simply skipped.

The description is for the user to document what the rule does. It is highly suggested to give the rule a meaningful name. Trying to troubleshoot a set of rules all named "[no description]" can be extremely difficult.

The set of conditions is the description of the traffic that should match the rule. If all of the conditions are true for the given session then the rules matches. This is discussed in more details in the next section.

The action or set of actions configures what action is performed if the rule matches. This is dependent on the application. For example, in Firewall it determines whether to block or pass the session and additionally if it should be flagged.

Conditions

Conditions define which sessions will match the rule. If and only if all of the conditions match, the rule is considered a match. Conditions can also be inverted by selecting "is NOT" in the dropdown, effectively inverting when it matches. Destination Port "is NOT" "80" matches on all ports except port 80.

Lets take a simple example: We want to block TCP traffic to port 80 on a server. There is a web service running on that server that you don't want to allow access to. First, create a rule and check the enable checkbox and give it a reasonably descriptive name like "blocking TCP port 80 to serverX." Now you will need to add some conditions that match only the traffic you want to block. So in this example will will add:

• Protocol is TCP
• Destination Address is 1.2.3.4 (The IP address of the server)
• Destination Port is 80

Finally, set the action to block and flag, and click "Done" and "Apply". Since all conditions must be true this rule will block TCP traffic to 1.2.3.4 port 80 only and nothing else.

Rule Conditions

There are many conditions available to carefully define precise sets of traffic. The following Table defines the list of conditions.

Each condition has several properties:

• Name - The Name of the condition
• Syntax - The accepted Syntax of the condition. If editing through the UI, some conditions have custom editors to help you craft conditions, others are just a text field.
• Availability - The Availability is the availability of that matcher at various times. Some conditions, like Destination Address, are always known and can always be used to match. Other conditions, like Application Control: Application, are only known after the session is created and some data flows and Application Control is able to identify the application. These type conditions are 'deep session' conditions because they are not able to be evaluated at session creation time, only after some data flows. As such they are not available in rules that are evaluated at session creation time, like Firewall and Captive Portal.
• Reliability - The Reliability is a "reliability" of that condition. True means it is 100% reliable. False means it is 99% or less reliable. For example, some conditions, like Destination Port, are always known and thus matching on Destination Port is 100% reliable. Other conditions, like Client Hostname, only match if the hostname for the client hostname is known. Hostname is determined through many ways, including DNS and DHCP. If all of these methods fail then it is entirely possible that the hostname of a server is "foo" but Untangle has not been able to determine this and as such a Client Hostname is "foo" condition will not match. This column is there purely as a warning that users in these cases must be aware of when conditions might deliver false negatives.

Condition List

Name	Syntax	Function	Availability	Reliability
Destination Address	IP Matcher	Matches if value matches the Destination/Server Address of the session. (after NAT/port forwarding)	all	True
Destination Port	Int Matcher	Matches if value matches the Destination/Server Port of the session. (after NAT/port forwarding)	all	True
Destination Interface	checkboxes	Matches if value matches the Destination/Server Interface of the session. (after routing/port forwarding)	all	True
Destined Local	boolean	Matches if the session is destined to one of Untangle's IP addresses.	all	True
Source Address	IP Matcher	Matches if value matches the Source/Client Address of the session. (before NAT/port forwarding)	all	True
Source Port	Port Matcher	Matches if value matches the Source/Client Port of the session. (before NAT/port forwarding)	hidden	True
Source Interface	checkboxes	Matches if value matches the Source/Client Interface of the session. (before routing/port forwarding)	all	True
Protocol	checkboxes	Matches if value matches the Protocol of the session.	all	True
Username	User Matcher	Matches if value matches the username associated with the Client IP in the Host table.	all	False
Host Hostname	Glob Matcher	Matches if value matches the hostname associated with the Local Address in the Host table.	all	False
Client Hostname	Glob Matcher	Matches if value matches the hostname associated with the Client IP in the Host table.	all	False
Server Hostname	Glob Matcher	Matches if value matches the hostname associated with the Server IP in the Host table.	all	False
Client MAC Address	Glob Matcher	Matches if value matches the MAC address associated with the Client IP in the ARP table.	all	False
Server MAC Address	Glob Matcher	Matches if value matches the MAC address associated with the Server IP in the ARP table.	all	False
Client MAC Vendor	Glob Matcher	Matches if value matches the device manufacturer. This is identified using the Client IP's MAC address in the ARP table and OUI Lookup.	all	False
Server MAC Vendor	Glob Matcher	Matches if value matches the device manufacturer. This is identified using the Server IP's MAC address in the ARP table and OUI Lookup.	all	False
Host has no Quota	boolean	Matches if the local address has no quota	all	True
User has no Quota	boolean	Matches if the username has no quota	all	True
Client has no Quota	boolean	Matches if the client has no quota	hidden	True
Server has no Quota	boolean	Matches if the server has no quota	hidden	True
Host has Exceeded Quota	boolean	Matches if the local address has exceeded their quota	all	True
User has Exceeded Quota	boolean	Matches if the user has exceeded their quota	all	True
Client has Exceeded Quota	boolean	Matches if the client has exceeded their quota	hidden	True
Server has Exceeded Quota	boolean	Matches if the server has exceeded their quota	hidden	True
Host Quota Attainment	Int Matcher	Matches the local address quota used to quota size ratio (">1" means over quota, ">.5" means over 50% used, etc)	all	True
User Quota Attainment	Int Matcher	Matches the username quota used to quota size ratio (">1" means over quota, ">.5" means over 50% used, etc)	all	True
Client Quota Attainment	Int Matcher	Matches the client quota used to quota size ratio (">1" means over quota, ">.5" means over 50% used, etc)	hidden	True
Server Quota Attainment	Int Matcher	Matches the server quota used to quota size ratio (">1" means over quota, ">.5" means over 50% used. etc)	hidden	True
HTTP: Hostname	Glob Matcher	Matches if the value matches the hostname specified in the HTTP session	deep sessions	False
HTTP: Referer	Glob Matcher	Matches if the value matches the referer string specified in the HTTP header	deep sessions	False
HTTP: URI	Glob Matcher	Matches if the value matches the latest URI specified in the HTTP session	deep sessions	False
HTTP: URL	URL Matcher	Matches if the value matches the latest URL (hostname+URI) specified in the HTTP session	deep sessions	False
HTTP: Content Type	Glob Matcher	Matches the content-type of the latest content in the HTTP session	deep sessions	False
HTTP: Content Length	Int Matcher	Matches if Int Matcher matches the content length specified in the latest HTTP response	deep sessions	False
HTTP: Request Method	Glob Matcher	Matches if the value matches the HTTP request method of the requested URL. Standard request methods include GET, POST, HEAD, OPTIONS, PUT, DELETE, TRACE, and CONNECT.	deep sessions	False
HTTP: Request File Path	Glob Matcher	Matches if the value matches the entire file path of the requested URL. This is everything including and after the first slash character following the host name or address. (e.g. /some/location/mypage.html)	deep sessions	False
HTTP: Request File Name	Glob Matcher	Matches if the value matches the file name of the requested URL. This is everything after the final slash character of the request. (e.g. mypage.html)	deep sessions	False
HTTP: Request File Extension	Glob Matcher	Matches if the value matches the file extension of the requested URL. This is everything after following the dot after the final slash character of the request. (e.g. html)	deep sessions	False
HTTP: Response Content Type	Glob Matcher	Matches if the value matches the content or MIME type reported in the server response.	deep sessions	False
HTTP: Response File Name	Glob Matcher	Matches if the value matches the file name returned in the server response.	deep sessions	False
HTTP: Response File Extension	Glob Matcher	Matches if the value matches the file extension returned in the server response. This is everything after (but not including) the final dot of the file name.	deep sessions	False
HTTP: Client User Agent	Glob Matcher	Matches if the value matches the User Agent string for the client in the Host table	all	False
Application Control: Application	Glob Matcher	Matches if the value matches the Application determined by Application Control	deep sessions	False
Application Control: Category	Glob Matcher	Matches if the value matches the Category of the Application determined by Application Control	deep sessions	False
Application Control: Protochain	Glob Matcher	Matches if the value matches the Protochain determined by Application Control	deep sessions	False
Application Control: Detail	Glob Matcher	Matches if the value matches the Detail of the Application determined by Application Control	deep sessions	False
Application Control: Confidence	Int Matcher	Matches if Int Matcher matches the confidence rating determined by Application Control	deep sessions	False
Application Control: Productivity	Int Matcher	Matches if Int Matcher matches the productivity rating determined by Application Control	deep sessions	False
Application Control: Risk	Int Matcher	Matches if Int Matcher matches the risk rating determined by Application Control	deep sessions	False
Application Control Lite: Signature	Glob Matcher	Matches if the value matches the Signature determined by Application Control Lite	deep sessions	False
Application Control Lite: Category	Glob Matcher	Matches if the value matches the Category of the Signature determined by Application Control Lite	deep sessions	False
Application Control Lite: Description	Glob Matcher	Matches if the value matches the Description of the Signature determined by Application Control Lite	deep sessions	False
Web Filter: Category	Glob Matcher	Matches if the value matches the Category determined by Web Filter	deep sessions	False
Web Filter: Category Description	Glob Matcher	Matches if the value matches the Description of the Category determined by Web Filter	deep sessions	False
Web Filter: Site is Flagged	boolean	Matches if the latest request in this session was flagged by Web Filter	deep sessions	False
Directory Connector: User in Group	Group Matcher	Matches if the username associated with the client in the Host Table is in the specified group(s)	all	False
HTTPS: SNI Host Name	Glob Matcher	Matches if the value matches the Server Name Indication (SNI) host name included by the client in the initial session request.	all	False
HTTPS: Certificate Subject	Glob Matcher	Matches if the value matches the Subject DN in the SSL certificate received from the external server.	all	False
HTTPS: Certificate Issuer	Glob Matcher	Matches if the value matches the Issuer DN in the SSL certificate received from the external server.	all	False
Time of Day	Time of Day Matcher	Matches times of day.	all	True
Day of Week	Day of Week Matcher	Matches days of the week.	all	True
Client Country	Glob Matcher	Matches if value matches the country associated with the Client IP.	all	False
Server Country	Glob Matcher	Matches if value matches the country associated with the Server IP.	all	False

Order

As discussed above, the order of rules is very important. Often users want to do very complex tasks that can be difficult or impossible with a single rule. In these cases, multiple rules is useful. For example, assume you want to use Firewall to block all traffic to a server (1.2.3.4) except port 80 traffic or from the admin IP (192.168.1.100) to RDP (port 3389).

Doing this in one rule would be difficult (actually impossible in this case), but it is quite easy using several rules: First, create a rule to just block all traffic to the server IP, 1.2.3.4. Above that rule create a rule that passes all traffic from the admin IP, 192.168.1.100, to the server IP where Destination Port == "3389", and another rule that passes all traffic to 1.2.3.4 with Destination Port == "80." This set of three rules does exactly what we describe above and effects no other traffic.

Rule Anatomy

Common Mistakes

This is a list of common mistakes to avoid.

Conditions must ALL match

In order for a rule to match, ALL conditions must match. In some cases you may want to add a rule that just passes all traffic to and from an IP. Users sometimes will create a pass rule with two conditions:

• Destination Address is "1.2.3.4"
• Source Address is "1.2.3.4"

This rule will never match anything because it will only match traffic where the destination address is 1.2.3.4 AND the source address is 1.2.3.4 (a session destined to itself). If you want to match when the destination address is 1.2.3.4 OR the source address is 1.2.3.4, then you must create two separate rules, one for the destination address and one for the source address.

Rule Order

Occasionally, you will add a rule and not understand why it is not working as intended. Often we find that there was a rule above that was matching the session before the desired rule. For example, just adding a rule to the bottom often isn't sufficient, you must find the appropriate place in your ruleset to place the new rule.

To do so simply logically evaluate the rules in your head starting at the top to find the appropriate place for your rule. Also use the event log to run several tests to see how the session was handled in the event log and adjust your ruleset accordingly.