How to use policy trace to debug access issues

<< Back to Knowledge Search



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.


Enabling policy trace

Note : Although is 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

Note : Tracing all policy execution requires a lot of CPU ressources and will also generate a large trace file. This method is not recommend for ProxySG units that are under medium or heavy load.


  • 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

Note : Please follow the instructions very carefully as a mistake done during the procedure might cause a service interruption. The trace rule has to be in it's own layer not to cause other policy rules to be bypassed. Also, by default, creating a new web access rule will set the action for that rule to "Deny", which if left unchanged to "None" will cause the proxy to block all traffic. 

  • 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 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.

 The rule should look like this if done properly.



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: client.address= proxy.port=8080   (5)
  time: 2009-06-15 16:38:02 UTC
  GET       (6)
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv: 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, 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 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 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.




Additional Information
Bug Number
InQuira Doc IdKB2935

Article Feedback

Hide Properties
First Published      10/01/2014
Last Modified      10/01/2014
Last Published      10/01/2014
Article Audience
Product      ProxySG
Topic      Content Filtering
Article Number      000011446
Was this helpful?
Previous MonthNext Month