Solutions

How to use policy trace to debug access issues

Problem Description
Policy tracing is use when debugging access to web sites. When something is allowed and it
should be denied, or vice-versa, using the policy trace feature is the best way to diagnose that
type of issue. In this article, we will go over enabling the trace and examining the debug file that
was generated by it.

Resolution
Enabling policy trace

Note: Although IS possible to recreate the rule via CPL and add it to the local policy file via
command line, it will not be possible to view the output of the debug file.

Policy trace can be enabled globally or by setting up a specific rule. Enabling the global option is
quick and easy but it can generate a lot of data very quickly so it's not the recommended way of
taking a policy trace but it can be an valid option on a proxy that doesn't have too much traffic.

To enable policy tracing as a global option

 Go to Configuration / Policy / Policy Options. Set the option to "Trace all policy execution"
 Click 'Apply'
 Reproduce the issue as quickly as possible
 Disable policy tracing
 Click 'Apply'
 Move ahead in this article to the section "Analyzing the policy trace"

To enable policy tracing as a rule

 Open the visual policy manager

 From the 'Policy' menu, click on 'Add Web access layer'
 Name it and click ok
 Right-Click the source and click on 'Set', 'New', 'Client IP Address/Subnet'
 Enter the IP address of the workstation you are going to test from, and as subnet, enter
255.255.255.255 since we only want that specific host.
 Right click the "Deny" item in the 'Action' column and click 'Delete'. The action should
now be "None"
 Right click the 'None' in the "Track" column and click 'Set', 'New', 'Trace...'
 Choose 'Verbose tracking', enable 'Trace file' and enter a file name
 Click 'Ok'
  You should now have a layer with a single rule, the source would be the IP address of the
workstation, and the track object should be the object just created.
 Install the policy
 Reproduce the issue
 Disable or delete the web access layer just created. It's best to disable it for now in case
another test needs to be done.

Analyzing the policy trace

To open the debug file generated by the policy trace, go to https://<proxy ip>:8082/policy

You should see policy trace filenames in there. 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)

CPL Evaluation Trace: transaction ID=659540
<Proxy> (2)
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)
Referer: http://www.google.com/
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.0.11)
Gecko/2009060215 Firefox/3.0.11 (7)
user: unauthenticated (8)
url.category: Search Engines/Portals@Blue Coat (9)
DSCP client outbound: 65
DSCP server outbound: 65
stop transaction -------------------- (1)

(1) Start/Stop markers

Those markers show the top and bottom of every transaction. A transaction is a web
transaction. A 'Get' request for example. Accessing one web site will generate many transactions
since every object (html code, java, images, banners, everything has it's own transaction).

(2) Layer markers

 <Proxy> and <Cache> 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 is
a match, 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

(3) Rule evaluated with a "miss"

In the above example, this rule doesn't have a source condition, has 3 categories set as
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 case here, google.com did
not match the BCWF categories "Alcohol", "Auctions" or "Gambling"

(4) Rule evaluated with a "MATCH"

This rule was a match so an 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. Not
that this is the last rule evaluated so that means the proxy reached the end of the active policy.

(5) 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

(6) The actual request

For our example above, we can see that it was a "get" request made to www.google.com. 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 (form information and file uploads for
example).

http:// Regular web connection

ssl:// Intercepted SSL connection

tcp:// Tunneled connection

(7) The user agent

This line is important when debugging a problem with a web site. We can see that it was
Firefox 3.0.11 that made this request, which means it's the browser itself. Some user-agents out
there will make a request directly. Winamp, Microsoft Outlook and iTunes are examples of user-
agents that go directly to the internet. Those user-agent don't support everything that a browser
does so they sometimes cause problems, especially with authentication. Usually, the result of that
is the user getting prompted to enter credentials. We have seen occurrences of iTunes going into
a loop of authentication when the proxy was setup in a transparent way and authentication was
configured to use cookie surrogates. The iTunes user-agent would not save the cookie and make
the request over and over again, and the proxy would.

(8) 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

(9) Category

url.category shows he matching category (or categories) bound to the URL accessed. If you see
"unlicensed/unavailable", it means that the license for the content filtering database has expired.

Additional information

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 would be
user or group specific rule when a connection went by unauthenticated.

Remember to turn off policy tracing after debugging is complete. Policy tracing (specially
enabling tracing for all policy evaluation) will generate lots of logs so it should be turned off
when not in use.