TIP: Debug squid ACL matches


Aspiring Daemon

Reaction score: 121
Messages: 781

This tip was tested on FreeBSD 6.4 running squid 3.0.STABLE10. Different squid versions may require marginally different configuration for the same effect.

[ This tip was inspired by - but differs substantially from - a debugging strategy enumerated in the excellent book Squid: The Definitive Guide by Duane Wessels. ]


For tricky squid ACL troubleshooting situations, it is helpful to be able to see which access control entries a request matches and does not match. This information can be discovered easily using squid's debugging facility.

Step 1: Read the documentation

Determine the debug section that refers to ACLs for your installation. This will be located in the file [font="Fixedsys"]/usr/local/share/doc/squid/debug-sections.txt[/font] (or similar).

# grep -i 'access' /usr/local/share/doc/squid/debug-sections.txt
section 28    Access Control
section 46    Access Log

In this case, we can see that squid's ACLs are managed by section 28.

Step 2: Make squid more chatty

Given the ACL section, we can tell squid to log more information about ACL traversal. We feed him the section (28) and the log level (3, or similar) in squid.conf.

debug_options 28,3

... and we tell the daemon to re-read the configuration:

# squid -k reconfigure

Step 3: Test and evaluate

Now we're ready to run some tests from one of the client web browsers. After attempting to view a page (which is either accepted or denied), review [font="Fixedsys"]/usr/local/squid/logs/cache.log[/font]. Entries similar to the following will appear:

2009/08/01 15:40:51.408| ACLChecklist::preCheck: 0x8a3d010 checking 'http_access 
allow my_clients my_sites'
2009/08/01 15:40:51.408| ACLList::matches: checking my_clients
2009/08/01 15:40:51.408| ACL::checklistMatches: checking 'my_clients'
2009/08/01 15:40:51.408| aclMatchIp: '' found
2009/08/01 15:40:51.408| [b]ACL::ChecklistMatches: result for 'my_clients' is 1[/b]
2009/08/01 15:40:51.408| ACLList::matches: checking my_sites
2009/08/01 15:40:51.408| ACL::checklistMatches: checking 'my_sites'
2009/08/01 15:40:51.408| aclMatchDomainList: checking 'www.yahoo.com'
2009/08/01 15:40:51.408| aclMatchDomainList: 'www.yahoo.com' NOT found
2009/08/01 15:40:51.408| [b]ACL::ChecklistMatches: result for 'my_sites' is 0[/b]
2009/08/01 15:40:51.408| aclmatchAclList: 0x8a3d010 returning false (AND list entry failed to match)
2009/08/01 15:40:51.410| ACLChecklist::preCheck: 0x8a3d010 checking 'http_access deny all'
2009/08/01 15:40:51.410| ACLList::matches: checking all
2009/08/01 15:40:51.410| ACL::checklistMatches: checking 'all'
2009/08/01 15:40:51.410| aclMatchIp: '' found
2009/08/01 15:40:51.410| [b]ACL::ChecklistMatches: result for 'all' is 1[/b]
2009/08/01 15:40:51.410| aclmatchAclList: 0x8a3d010 returning true (AND list satisfied)
2009/08/01 15:40:51.410| ACLChecklist::markFinished: 0x8a3d010 checklist processing finished
2009/08/01 15:40:51.410| ACLChecklist::check: 0x8a3d010 match found, calling back with 0
2009/08/01 15:40:51.410| ACLChecklist::checkCallback: 0x8a3d010 answer=0

With some patience and a careful eye, we can determine exactly which access entries were matched and which were not. Note that true evaluations are represented by 1, while false evaluations are represented by 0.

Of particular interest here:
  • My client IP ( was matched by the "my_clients" entry.
  • The yahoo domain name was not matched by the "my_sites" entry.
  • My client IP was matched by the "all" entry (and subsequently denied access by "http_access deny all").

Hmm. It looks like I will need to tweak my configuration and troubleshoot further, as I want to visit the yahoo site. Now I know the access control entry to focus on: "my_sites".

Step 4: Post-troubleshooting cleanup

It is important to disable the debug_options when you are finished troubleshooting. They produce a copious amount of logging, and they can generally be a (disk space) liability when you aren't using them.

To reverse the changes, simply comment out the debug_options line above, and:

# squid -k reconfigure



Reaction score: 1
Messages: 39

still struggling with mixed environments (using Active Directory authentication on Squid), will pass this to our Windows Admin. thank you for the tip