> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safesquid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging and troubleshooting

<Note>
  CLI man page: `safesquid-logging(7)`
</Note>

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?

| Symptom                                    | Open first                                                                                       |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| One user or URL blocked or allowed wrongly | **Reports → Detailed logs**                                                                      |
| Login / Kerberos / PAM / LDAP              | Detailed logs, then Native (`security:`, `ldap:`, `pam:`)                                        |
| “It worked yesterday”                      | **Config logs** for who changed policy                                                           |
| Unsure which profile matched               | Detailed logs + [debug headers](/admin_guide/start_here/debug_response_headers) on a test client |

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

<Warning>
  Do not leave full DEBUG enabled in production. It grows disks quickly and makes logs harder to read.
</Warning>

## 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

<Tip>
  ### 1 — “I cannot browse at all”

  1. Confirm proxy host/port and [Listen](/admin_guide/infrastructure_and_access/network_settings).
  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](/admin_guide/infrastructure_and_access/access_restrictions) (subnet, Interface, Default Access Policy).
</Tip>

<Tip>
  ### 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](/admin_guide/policies_and_profiles/access_profiles) entry or enable Trace Entry on the suspect rule.
</Tip>

<Tip>
  ### 3 — “Login keeps asking for a password”

  1. Note whether Kerberos / SSO or System authentication is enabled ([Authentication](/admin_guide/start_here/authentication)).
  2. Watch Native logs for `security:`, `pam:`, `ldap:`.
  3. Clear **Reports → Password Cache** after fixing credentials or PAM.
</Tip>

## 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](/admin_guide/start_here/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](/admin_guide/start_here/first_configuration)
* [Access restrictions](/admin_guide/infrastructure_and_access/access_restrictions)
* [Authentication](/admin_guide/start_here/authentication)
* [Access Profiles](/admin_guide/policies_and_profiles/access_profiles)
* [Architecture](/admin_guide/start_here/architecture)
* [Debug response headers](/admin_guide/start_here/debug_response_headers)

CLI: `man safesquid-logging`


## Related topics

- [Integrations](/admin_guide/start_here/integrations.md)
- [SafeSquid daemon](/admin_guide/start_here/daemon.md)
- [Debug response headers](/admin_guide/start_here/debug_response_headers.md)
- [Tools and Reports](/admin_guide/start_here/tools_and_reports.md)
- [Authentication](/admin_guide/start_here/authentication.md)