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.

​

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
• profiles, user_groups, categories, request_profiles, application_signatures
• bypassed — whether bypass was active on that request

​

Examples

​

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.

​

See also

• First configuration
• Access restrictions
• Authentication
• Access Profiles
• Architecture
• Debug response headers

CLI: man safesquid-logging