How to debug squid ACLs

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: RTFM

check debug sections avaliable:

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 (near the top usually).


debug_options 28,3

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

service squid reload

Step 3: Test and evaluate

Now check the logs:

tail -f /var/log/squid/cache.log

Note: realistically you probably don’t want to tail the logs, you are best to try your failing web site then open the log with ‘less’ etc and do a search for you website.

In this example my blocklist had downloaded some unfiltered characters and ended up with a zero (”0”) on a line by itself. (Why they ended up there is a different conversation)

2015/01/07 15:51:42.237| ACL::checklistMatches: checking 'zeus_block_list'
2015/01/07 15:51:42.237| aclRegexData::match: checking ''
2015/01/07 15:51:42.237| aclRegexData::match: looking for '24b5'
2015/01/07 15:51:42.237| aclRegexData::match: looking for '0'
2015/01/07 15:51:42.238| aclRegexData::match: match '0' found in ''
2015/01/07 15:51:42.238| ACL::ChecklistMatches: result for 'zeus_block_list' is 1

Removing the zero from the


and reloading squid resolved the issue.

Note that true evaluations are represented by 1, while false evaluations are represented by 0.

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 reload squid.

Thanks to FreeBSD forums for the walk-through