Enable policy tracing
Note: Although you can recreate the rule via CPL and add it to the local policy file via the command line, you cannot view the output of the debug file.
You can enable policy tracing globally or by setting up a specific rule. While the global option is quick and easy to enable, it can generate a lot of data very quickly. Therefore, the global option is not recommended, although it can be a valid option on a proxy with a small amount of traffic.
To enable policy tracing as a global option
CAUTION: Tracing all policy execution requires a lot of CPU resources, and will also generate a large trace file. Symantec does not recommend this option for ProxySG appliances that are under medium or heavy load.
- Navigate to Configuration > Policy > Policy Options.
- Select Trace all policy execution.
- Click Apply.
- Reproduce the issue as quickly as possible.
- Disable policy tracing.
- Click Apply.
- See the section "Analyze the policy trace" for next steps.
To enable policy tracing as a rule (recommended)
WARNING: Follow these instructions very carefully; any mistake could cause a service interruption. The trace rule has to be in its own layer so that other policy rules are not bypassed. Also, by default, creating a new web access rule sets the action for that rule to "Deny." If this is not changed to "None," the proxy wlll block all traffic.
- Open the Visual Policy Manager.
- Click Policy > Add Web Access Layer.
- Enter a name and click OK.
- Right-click the source, and then click Set.
- Click New, and then select Client IP Address/Subnet.
- Enter the IP Address of the workstation you are going to test from. As a subnet, enter 255.255.255.255, since we only want that specific host.
- Click Add > Close > OK.
- In the Action column, right-click Deny, and then click Delete. The action should now be "None."
- in the Track column, right-click None, and then click Set.
- Click New > Trace.
- Choose Verbose tracking, enable Trace file, and enter a file name.
- Click OK, and click OK again.
- You should now have a layer with a single rule; the source is the IP address of the workstation, and the track object is the object you just created.
- Click the Install policy tab.
- Reproduce the issue.
- Disable or delete the Web Access Layer you just created. It's best to disable it for now in case another test needs to be done.
The rule should look like this when done properly.
Note: In some cases, when the policy is large and the buffer overflows, it will overwrite the relevant transactions and only later transactions will be captured. In that case, you may need to add the following rule to the steps above after step 7:
- Right-click the destination, and click Set.
- Click New, and select Request URL.
- In the domain field of the object, enter the domain of the URL in question (example.com).
- Click Add > Close > OK.
Analyze the policy trace
- To open the debug file generated by the policy trace, go to https://X.X.X.X:8082/policy. You should see policy trace you named in Step 11 above.
- If you enabled the global policy trace option, the file will be called default_trace.html.
- If you used a rule, the file name will depend on the object you created.
- Click on the file to display it. The default extension is HTML, but the content of the file is plain text.
- Let's look at what a typical policy trace looks like. The numbers in red were added for this article. They are explained in more details further down.
start transaction ------------------- (1)
miss : time.utc=1800..2000
miss : category=(Alcohol, Auctions, Gambling) DENY (3)
MATCH: ALLOW (4)
connection: service.name=HTTP client.address=10.1.1.10 proxy.port=8080 (5)
time: 2009-06-15 16:38:02 UTC
GET http://www.google.com/ (6)
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:184.108.40.206) Gecko/2009060215 Firefox/3.0.11 (7)
user: unauthenticated (8)
url.category: Search Engines/[email protected] Coat (9)
DSCP client outbound: 65
DSCP server outbound: 65
stop transaction -------------------- (1)
- Start/Stop markers - These markers appear at the top and bottom of every transaction. A transaction is a web transaction; for example, a "Get" request. Accessing one web site will generate many transactions since every object (html code, java, images, banners; everything has its own transaction).
- Layer markers - These are the most popular layer types. A layer marker means that a new layer was evaluated. When a transaction is evaluated against the policy, every layer is part of that evaluation (unless it has a layer guard). Rules are evaluated from the top down, and once a rule matches, the proxy jumps to the next layer. If you have a layer with 30 rules, for example, but only the first 10 were evaluated, it's because the 10th rule was a match and the proxy didn't look at the rest of that layer
- Rule evaluated with a "miss" - In this example, this rule doesn't have a source condition, it has 3 categories set as a destination, and "Deny" configured as the action. The policy debug shows "miss" for this rule which means that this transaction did not match the condition. In this example, google.com did not match the BCWF categories "Alcohol", "Auctions," or "Gambling.
- Rule evaluated with a "MATCH" - This rule was a match so action was taken by the proxy. In this example, there are no conditions, it's simply a rule with an "Allow" action so everything would match that rule. Note that this is the last rule evaluated, which means that the proxy reached the end of the active policy.
- Connection information - This line shows connection details specific to that transaction. We know that the service was HTTP, that the source IP was 10.1.1.10, and that the port used to connect to the proxy was 8080.
- The actual request - In this example, we see that a "get" request was made to www.google.com. The most common types of requests are "get," when the browser fetches an object, and "post," when information is sent from the browser back to the server (for example, form information and file uploads).
- http:// Regular web connection
- https:// Decrypted (SSL Intercepted) SSL web connection
- ssl:// Non-decrypted SSL connection
- tcp:// Tunneled connection
- The user agent - This line is important when debugging a problem with a website. We can see that Firefox 3.0.11 made this request, which means it's the browser itself. Some user agents will make a request directly. Winamp, Microsoft Outlook, and iTunes are examples of user agents that go directly to the Internet. Those user-agent do not support everything that a browser does so they sometimes cause problems, especially with authentication. Usually, the result is that the user is prompted to enter credentials. We have seen occurrences of iTunes going into a loop of authentication when the proxy was set up in a transparent way and authentication was configured to use cookie surrogates. The iTunes user-agent would not save the cookie and subsequently make the request over and over again, while the proxy would save the cookie.
- Authentication status - If a username was bound to a connection, it would show up here as domain\username. In the example above, the connection was unauthenticated.
- Category - url.category shows the matching category (or categories) bound to the URL accessed. If you see "unlicensed/unavailable," this means that the license for the content filtering database has expired.
Proxy or network latency
You can also review checkpoint timing to discover possible proxy or network latency issues. For more information, see Understanding Policy Trace checkpoint timing.
For some connections, instead of seeing "match" or "miss", the proxy will report "n/a" which means the rule did not apply to that connection. In most cases, it is because the rule is specific to a protocol and the connection was not using that protocol. Another typical scenario is a user or group-specific rule where a connection goes unauthenticated.
CAUTION: Remember to turn off policy tracing after debugging is complete. Policy tracing (especially enabling tracing for all policy evaluation) generates a lot of logs, so it should be turned off when not in use.