Skip to main content

​
Find Answers With Logging and Troubleshooting

When a user says “the proxy blocked me” or “nothing loads,” logs are how you prove what SafeSquid did. You do not need every log family on day one — start with Detailed logs, then add Native families only for the module you are debugging.

​
Which log should I open?

​
Log families

  • Native logs — Internal diagnostics from the native logger. Each line is timestamped and tagged (for example security:, ldap:, cache:). File: /var/log/safesquid/native/safesquid.log
  • Detailed logs — One row per client transaction (tab-separated). Includes username, URL, status, filter_name, filtering_reason, profiles, categories, and user groups. Start here for user-facing issues. File: /var/log/safesquid/extended/extended.log
  • Config logs — Who changed what in the Web UI: section, action, arguments, URL, reason. File: /var/log/safesquid/config/config.log
  • Performance log — Resource and throughput statistics. File: /var/log/safesquid/performance/performance.log
  • Syslog — Native messages also go to syslog when running in foreground or when the native logger is unavailable. Init script messages use ident safesquid.init.

​
Viewing logs in the Web UI

Open Reports:
  • Native logs — live diagnostic tail
  • Detailed logs — search transactions by user, URL, filter, date
  • Config logs — configuration audit trail
  • Dashboard / Statistics — traffic overview
  • Active Connections, Password Cache, SSL Certs/Cache — live state alongside historical logs

​
Log level (native / putlog)

Set LOG_LEVEL in /opt/safesquid/startup.ini. It is a bitmask — add family values for more detail.
  • SECURITY (8388608) — Access, authentication, blocks — essential for auth and perimeter issues
  • LDAP (4) — Directory lookups and LDAP authentication
  • PROFILES (67108864) — Access Profiles and profile tags
  • REQUEST (1), NETWORK (2) — Request flow and connections
  • WARN (16777216), ERROR (33554432) — Review on every incident
  • DEBUG (134217728) — Very verbose. Enable only temporarily; default install excludes DEBUG (134217727). Full debug: 268435455.
Other families include HEADER, COOKIE, REDIRECT, REWRITE, CACHE, FORWARD, SSL, CATEGORY, ANTIVIRUS, ICAP, and MODULE. Enable the one that matches filter_name in Detailed logs.
Do not leave full DEBUG enabled in production. It grows disks quickly and makes logs harder to read.

​
Detailed log — key columns

  • client_id, request_id — correlate lines for one client
  • client_ip, username, interface
  • method, url, status, size
  • filter_name, filtering_reason — which module decided the outcome. This pair is usually the single most useful value on the entry, because it names which section’s configuration to open next instead of leaving you to guess.
  • profiles, user_groups, categories, request_profiles, application_signatures
  • bypassed — whether bypass was active on that request

​
Examples

​
1 — “I cannot browse at all”

  1. Confirm proxy host/port and Listen.
  2. Search Detailed logs for the client IP. If there are no rows, the request never reached SafeSquid (firewall, wrong proxy, or service down).
  3. If rows show access deny, fix Access restrictions (subnet, Interface, Default Access Policy).

​
2 — “Only one site is blocked”

  1. Find the URL in Detailed logs.
  2. Read filter_name and filtering_reason (often Access Profiles, redirect, or a scanner).
  3. Check profiles and categories on that row. Adjust the matching Access Profiles entry or enable Trace Entry on the suspect rule.

​
3 — “Login keeps asking for a password”

  1. Note whether Kerberos / SSO or System authentication is enabled (Authentication).
  2. Watch Native logs for security:, pam:, ldap:. The lines around the failed attempt usually name the specific step that failed. The password cache, the local system check, or the directory bind.
  3. Clear Reports → Password Cache after fixing credentials or PAM.

​
Rotation and remote copy

  • LOG_SIZE_LIMIT — Max log size before rotation (default 1G)
  • PROCESS_OLD_LOGS — 0 delete, 1 compress, 2 close only (appliance default)
  • UDP forwarding — Optional NATIVE_UDP_*, EXTENDED_UDP_*, CONFIG_UDP_* in startup.ini send copies to a remote collector

​
Debug response headers

For live policy visibility on a single request, enable System configuration → Send Debugging Headers To → CLIENT (test networks only). Browser tools show X-SafeSquid-Profiles, categories, user, and module headers. See Debug response headers.

​
Policy trace

On a single policy row in the Web UI, enable Trace Entry to log when that entry is evaluated — without turning on global DEBUG.

​
Troubleshooting workflow

  1. Note time, client IP, username, and URL.
  2. Search Detailed logs for filter_name and filtering_reason.
  3. Enable the matching native family (usually SECURITY) in LOG_LEVEL; reproduce once.
  4. For auth issues, look for security: and ldap: in Native logs.
  5. For surprise policy changes, check Config logs in the same time window.
  6. Turn DEBUG and CLIENT debug headers off when finished.

​
How to verify

  1. Reproduce the issue once and confirm a corresponding entry appears in Detailed logs with the expected timestamp, client, and URL.
  2. Confirm filter_name and filtering_reason on that entry name the module actually under suspicion before changing that module’s configuration.
  3. If a Native log family or Trace Entry was enabled for the investigation, confirm the expected line appears, then turn it back off.
  4. After a fix, reproduce again and confirm the new entry shows the expected outcome.

​
Next steps