# Application Ecosystem
Source: https://docs.safesquid.com/architecture/application_ecosystem/main
Navigation hub for SafeSquid SWG enforcement, DNS security, browser isolation, reporting, self-service operations, and intelligence feeds.
# Navigate the SafeSquid Application Ecosystem
SafeSquid SWG is an operating ecosystem, not a single proxy daemon. The proxy service enforces policy and DNS security reduces resolution-time risk. Reporting preserves evidence, the Self-Service Portal manages cloud-linked workflows, and threat-intelligence feeds keep controls current.
The legacy source page for Application Eco-system identifies the operating scope. It covers SafeSquid files and folders, startup parameters, Self-Service Portal management, required supporting services, and SIEM log forwarding. This hub maps those topics into the current Architecture tab.
## Quickstart path
1. [Proxy Service](/architecture/application_ecosystem/proxy_service) — understand the enforcement point before designing traffic flow.
2. [Integrated DNS Security](/architecture/overview/integrated_dns_security) — reduce phishing, malware, and DNS tunnelling risk before HTTP policy runs.
3. [Remote Browser Isolation](/architecture/application_ecosystem/remote_browser_isolation) — separate high-risk browsing activity from trusted endpoints.
4. [Reporting Service](/architecture/interface/reporting_service) — preserve audit, forensic, and SIEM-ready evidence.
5. [Self-Service Portal](/architecture/interface/self_service_portal) — manage activation, licensing, categorization, certificate, and backup-linked workflows.
6. [Threat Intelligence Feeds](/architecture/application_ecosystem/threat_intelligence_feeds) — keep classification, malware, SSL, GeoIP, and content signals current.
## Next steps
* Use [Supporting Services](/architecture/interface/supporting_services) to operate Monit, BIND, and NTP dependencies.
* Use [Policy Management Console](/architecture/policy_management_console/main) to configure policy, reports, and support workflows.
* Use [Files and Folders](/architecture/files_and_folders/files_and_folders) to locate server-side configuration and evidence paths.
# Proxy Service
Source: https://docs.safesquid.com/architecture/application_ecosystem/proxy_service
SafeSquid proxy service role, startup dependency, policy enforcement path, and operational evidence for enterprise SWG deployments.
# Keep the Proxy Service Enforcing Policy
The SafeSquid proxy service is the enforcement point for user web traffic. It receives client requests, evaluates policy and applies inspection controls. It also generates evidence that administrators use for operations, audit, and incident response.
The Application Eco-system source calls out SafeSquid startup parameters as part of the operating model. Treat those parameters as production controls because incorrect service startup can change listening behavior, logging behavior, or enforcement availability.
## Risks the service controls
* Uncontrolled web access to phishing, malware, remote-access, and data-exfiltration destinations
* Policy drift when proxy instances do not start with the intended runtime settings
* Evidence gaps when access, extended, native, or configuration logs are not generated or forwarded
* Availability loss when the proxy process is not monitored by supporting services
## Operational responsibilities
The proxy service depends on a clear operating boundary:
| Responsibility | Control value | Evidence to retain |
| - | - | - |
| Start with approved parameters | Prevents accidental listener, cache, or log changes | Service unit, startup parameters, change ticket |
| Enforce Layer 7 policy | Blocks or allows HTTP and HTTPS traffic by rule | `extended.log`, policy reports, SIEM events |
| Preserve configuration history | Supports audit and rollback | `config.log`, backup record |
| Stay supervised | Reduces downtime after process failure | Monit status, service restart events |
## Production checks
Verify the proxy service after installation, upgrade, and major policy changes:
1. Confirm the SafeSquid service is running under the expected service manager.
2. Confirm the client traffic path uses the intended proxy listener.
3. Trigger a known allowed and known blocked request.
4. Confirm the event appears in local logs or the Reporting Service.
5. Confirm Monit or the approved service supervisor reports healthy status.
## Related controls
* [SafeSquid Proxy Cluster](/architecture/overview/safesquid_proxy_cluster) for scale-out and failover design.
* [Monit Service Governance](/architecture/interface/supporting_services_monit) for process supervision.
* [Reporting Service](/architecture/interface/reporting_service) for audit and forensic evidence.
## Next steps
* Use [Integrated DNS Security](/architecture/overview/integrated_dns_security) to add DNS-layer protection.
* Use [Configure](/architecture/policy_management_console/configure) to manage policy through the console.
# Remote Browser Isolation
Source: https://docs.safesquid.com/architecture/application_ecosystem/remote_browser_isolation
Remote Browser Isolation role in the SafeSquid SWG ecosystem for separating risky browsing from trusted enterprise endpoints.
# Isolate Risky Browsing From Endpoints
Remote Browser Isolation (RBI) separates high-risk web activity from the endpoint. Use it when the business must allow access to uncertain or risky sites. Active web content then does not get direct execution access on managed devices.
RBI is part of the application ecosystem because it complements proxy policy. The proxy decides whether a request is allowed, blocked, inspected, or redirected into a safer browsing path. Isolation reduces endpoint exposure when a complete block would interrupt legitimate work.
## Risk and control fit
| Scenario | Proxy-only outcome | RBI-assisted outcome |
| - | - | - |
| Unknown research site | User reaches active content on the endpoint if allowed | Site opens away from the endpoint trust boundary |
| High-risk category with business need | Teams choose between block and exception | Access can be constrained to an isolated session |
| Phishing investigation | Analysts risk endpoint exposure | Analysts review content with reduced local execution risk |
## Use RBI when
* Legal, finance, security, or research teams must inspect unknown sites.
* Executives and privileged users face targeted phishing risk.
* A temporary exception is necessary but direct endpoint rendering is too risky.
* Audit teams need proof that risky access was controlled, not silently allowed.
## Evidence to retain
Pair RBI decisions with proxy and reporting evidence:
* user identity and destination
* policy decision that sent the session to isolation
* time of access and session result
* related block, bypass, or exception record
## Next steps
* Use [Proxy Service](/architecture/application_ecosystem/proxy_service) to understand the enforcement point.
* Use [Reporting Service](/architecture/interface/reporting_service) to retain investigation evidence.
* Use [Threat Intelligence Feeds](/architecture/application_ecosystem/threat_intelligence_feeds) to review the feeds behind URL classification and signatures.
# Threat Intelligence Feeds
Source: https://docs.safesquid.com/architecture/application_ecosystem/threat_intelligence_feeds
SafeSquid threat-intelligence feed role for URL classification, malware signatures, SSL updates, GeoIP, and content-aware enforcement.
# Keep Threat Intelligence Feeds Current
Threat-intelligence feeds keep SafeSquid policy decisions current. Static rules decay quickly against phishing kits, malware delivery domains, remote-access tooling, and newly abused cloud services.
The application ecosystem places feed delivery beside the proxy, DNS, reporting, and Self-Service Portal paths. That placement matters: a feed outage can weaken classification and detection even when the proxy service itself is healthy.
## Feed categories
SafeSquid ecosystem documentation identifies these intelligence categories:
| Feed | Control value |
| - | - |
| Threat Intelligence | Identifies malicious destinations and suspicious behavior. |
| URL Classification | Supports category-based access policy and exception handling. |
| Application Identification | Helps distinguish sanctioned and unsanctioned application use. |
| Image Analysis AI Feed | Supports content-aware inspection and visual-risk decisions. |
| Content Fingerprints | Identifies known content patterns for inspection and policy. |
| Malware Signatures | Improves file and payload detection. |
| Geo-Location | Adds country or region context to destination policy. |
| SSL Updates | Keeps certificate and TLS-related decisions current. |
## Operational checks
Verify feed health during deployment and incident response:
1. Confirm the deployment can reach approved SafeSquid cloud dependencies.
2. Confirm feed update status in the appropriate operating view or logs.
3. Test a known category, malware-test, or policy-safe indicator.
4. Confirm the Reporting Service or SIEM receives the resulting event.
## Failure symptoms
| Symptom | Likely cause | Verification |
| - | - | - |
| New malicious sites are not classified | Feed update path blocked | Check cloud allowlists and update status. |
| Category policy behaves inconsistently | Outdated or unsynced feed state | Compare feed timestamps across nodes. |
| SSL trust decisions look stale | SSL update path unavailable | Review update logs and certificate behavior. |
## Next steps
* Use [Self-Service Portal](/architecture/interface/self_service_portal) to understand cloud-linked operational workflows.
* Use [Reporting Service](/architecture/interface/reporting_service) to verify intelligence-driven policy events.
* Use [Proxy Service](/architecture/application_ecosystem/proxy_service) to review the service that enforces policy on every request.
# Application Binaries and Modules
Source: https://docs.safesquid.com/architecture/files_and_folders/application_binaries_and_modules
SafeSquid SWG binary, module, feature library, section XML, and default startup file path reference.
# Locate Application Binaries and Modules
SafeSquid binaries and modules load the enforcement engine and optional feature capabilities. Treat these paths as product-owned. Removing, replacing, or manually modifying files can disable controls, break the interface, or create unsupported runtime behavior.
## Core binary paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/opt/safesquid/bin/safesquid` | SafeSquid executable link for the running SafeSquid version. | Service fails to start, upgrade verification, or binary integrity review. | Proves which runtime binary the service uses. The wiki warns that deleting this file stops SafeSquid from working. |
| `/opt/safesquid/bin/sections` | Stores SafeSquid feature XML files, except add-on module XMLs. SafeSquid uses these XML files to render the user interface. | Interface sections are missing, feature pages fail to render, or support asks for UI structure evidence. | Shows product section definitions. Manual edits can break management interface rendering. |
| `/opt/safesquid/default` | Stores default `startup.ini` and `setup.ini`. | Startup parameter review, setup parameter recovery, or upgrade comparison. | Keep default files unchanged. Modified startup parameters belong in `/opt/safesquid/startup.ini`; manual setup changes require a copied `/opt/safesquid/setup.ini`. |
## Module root
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/opt/safesquid/bin/modules` | Stores add-on modules loaded when SafeSquid starts. Modules include shared objects and XML files. | Feature fails to load, startup errors mention modules, or support asks for module inventory. | Confirms which add-on capability files exist. Mismatched files can disable features or prevent clean startup. |
## Feature module paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/opt/safesquid/bin/modules/dlp` | Stores DLP module shared objects and XML. DLP detects and blocks potential data exfiltration. | Upload control fails, DLP policies do not apply, or module inventory is required. | Supports evidence that the DLP module is present. Missing files can remove data-loss controls. |
| `/opt/safesquid/bin/modules/elevated` | Stores Elevated Privacy module files. This feature can block third-party cookies and hide referer and user-agent details according to privacy level. | Privacy controls fail or policy behavior differs from expectation. | Shows whether Elevated Privacy module files are installed. Changes can affect privacy enforcement. |
| `/opt/safesquid/bin/modules/icap` | Stores ICAP module files. ICAP enables request or response modification through an ICAP server. | ICAP integration fails, external content filtering breaks, or request modification is not applied. | Confirms ICAP module presence. Incorrect changes can disrupt external scanning or transformation workflows. |
| `/opt/safesquid/bin/modules/imgfilter` | Stores Image Analyzer module files. The wiki states it can block suspicious images and is typically `80%-90%` accurate, depending on configuration. | Image filtering does not trigger or support asks for module state. | Shows installed image analysis files. Treat accuracy as configurable, not absolute. |
| `/opt/safesquid/bin/modules/imgfilter/imgfilter` | Stores Image Analyzer dependency libraries such as `libIAImageReaderShared.so.*`, `libIAEngineShared.so.*`, and `imgfilter.tune`. | Image Analyzer loads but scoring or dependencies fail. | Contains engine, reader, and threshold tuning files. Changes can alter image block behavior. |
| `/opt/safesquid/bin/modules/rewrite` | Stores Content Re-Write module files. The feature uses regular expressions to modify pages, files, client headers, or server headers in real time. | Rewrite policy behaves unexpectedly or high-risk content modification is under review. | High-risk control surface. Use change control because incorrect expressions can alter trusted content before delivery. |
| `/opt/safesquid/bin/modules/sscore` | Stores SScore module files. SScore queries SafeSquid Content Categorisation Service to classify websites. | Category decisions fail or classification evidence is needed. | Confirms website categorization module files. Missing files can reduce category-based enforcement. |
| `/opt/safesquid/bin/modules/svscan` | Stores SvScan module files. SvScan is a high-speed in-memory malware scanner with signature database support. | Malware scanning fails or signature-dependent behavior needs proof. | Confirms anti-malware module files. Missing files can weaken malware protection. |
| `/opt/safesquid/bin/modules/wccp` | Stores WCCP module files. WCCP redirects traffic from WCCP-enabled routers to SafeSquid for transparent proxying. | Transparent redirection fails, router integration changes, or failover is reviewed. | Confirms WCCP support files. Misconfiguration can bypass proxy enforcement or affect routing. |
## Change-control guidance
Do not manually replace module files during normal administration. Use supported package, upgrade, or support-directed procedures. Capture directory listings before and after upgrades so reviewers can explain changed capabilities.
## Next steps
* Use [Runtime Data and Signatures](/architecture/files_and_folders/runtime_data_and_signatures) to review downloaded signature and library stores.
* Use [Proxy Service](/architecture/application_ecosystem/proxy_service) to understand how service startup affects enforcement.
* Use [Service and Startup Files](/architecture/files_and_folders/service_and_startup_files) to locate the service control and startup files.
# Files and Folders
Source: https://docs.safesquid.com/architecture/files_and_folders/files_and_folders
SafeSquid SWG server path reference for service control, policy storage, runtime data, logs, audit evidence, backup, and rollback.
# Locate SafeSquid Files and Folders
SafeSquid server paths are part of the enforcement boundary. They hold service control scripts, module binaries, policy XML, and activation material. They also hold SSL data, reporting databases, signature stores, runtime files, and logs. Uncontrolled edits can break proxy availability, weaken inspection, erase rollback evidence, or create audit gaps.
Use this section to prove what changed, locate operational evidence, and decide which files need change control. Do this before an upgrade or incident response.
## Control the file surface
Treat these paths as production controls, not ordinary local files:
| Path group | Control value | Primary risk |
| - | - | - |
| Service and startup files | Prove how SafeSquid starts, restarts, and tunes the host | Unapproved runtime changes or service outage |
| Binaries and modules | Load SafeSquid features and interface section definitions | Missing modules, mismatched libraries, or unsupported edits |
| Policy and security files | Store activation, policy, SSL, SQLite, and UI assets | Policy drift, certificate exposure, or support risk |
| Runtime data and signatures | Store cache, temporary files, databases, and downloaded signatures | Stale data, failed updates, or lost reporting history |
| Logs and PID state | Preserve audit, forensic, performance, and runtime evidence | Missing incident evidence or incorrect process state |
## Protect sensitive evidence
Activation files, SSL folders, policy XML, reporting databases, and SafeSquid logs contain security-sensitive data. Logs can include user identifiers, source IP addresses, destinations, policy outcomes, browser metadata, and investigation context.
Before exporting or sharing evidence, redact personal data unless an approved audit or incident investigation requires it. Retain copied files according to your organization's evidence-handling policy.
## Use change control
Do not edit SafeSquid-controlled files directly unless a documented procedure requires it. Record the path, owner, reason, backup location, reviewer, and rollback step. Do this before changing service scripts, startup parameters, policy XML, SSL material, modules, templates, or log settings.
For policy work, prefer the SafeSquid interface. File-level edits should be reserved for recovery, support-directed remediation, or documented administrative tasks.
## Locate the right path
| Need | Start here |
| - | - |
| Verify service controls, startup behavior, TCP tuning, log rotation, Monit, PAM, or kernel tuning | [Service and Startup Files](/architecture/files_and_folders/service_and_startup_files) |
| Understand binaries, modules, section XMLs, and default startup or setup files | [Application Binaries and Modules](/architecture/files_and_folders/application_binaries_and_modules) |
| Locate activation, policy, SSL, SQLite, UI, CGI, template, CSS, JS, image, or font files | [Policy, Security, and UI Files](/architecture/files_and_folders/policy_security_and_ui_files) |
| Review temporary data, cache, report databases, SSL certificate cache, user data, and signature stores | [Runtime Data and Signatures](/architecture/files_and_folders/runtime_data_and_signatures) |
| Collect config, extended, native, performance, privacy, and process evidence | [Logs and Audit Evidence](/architecture/files_and_folders/logs_and_audit_evidence) |
## Minimum incident set
For an operational incident, preserve:
1. affected user, source IP, destination, and timestamp
2. matching report entry or SIEM event
3. relevant `extended.log`, `native.log`, `performance.log`, or `config.log` lines
4. recent configuration backup files
5. service state and startup parameters
6. Monit, BIND, and NTP health status
7. SafeSquid process ID from `/var/run/safesquid`
## Next steps
* Use [Logs and Audit Evidence](/architecture/files_and_folders/logs_and_audit_evidence) to collect proof for investigation and audit.
* Use [Support](/architecture/policy_management_console/support) to prepare escalation evidence.
* Use [Policy, Security, and UI Files](/architecture/files_and_folders/policy_security_and_ui_files) to locate policy, security, and UI files.
# Logs and Audit Evidence
Source: https://docs.safesquid.com/architecture/files_and_folders/logs_and_audit_evidence
SafeSquid SWG config, extended, native, performance, privacy, and process evidence path reference.
# Locate Logs and Audit Evidence
SafeSquid logs prove who changed policy, what users accessed, which controls matched, and whether the proxy had enough capacity. Preserve these files before remediation. Reboots, rotation, compression, or emergency cleanup can remove the only evidence that explains a security incident.
## Configuration audit logs
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/var/log/safesquid/config` | Stores `config.log`, which records SafeSquid configuration changes made through the interface. Rotated files are named like `XXXX-config.log`. | Policy dispute, rollback, unauthorized change review, or audit evidence collection. | Shows who changed configuration, from which source, on which page or section, and why. Missing logs weaken change accountability. |
`config.log` records this legend:
```text theme={null}
"ACCESS_TIME" "SAFESQUID_INTERFACE" "USERNAME@IP" "PAGE" "SECTION" "ACTION" "HTTP_METHOD" "URL" "REFERER" "ARGUMENTS" "CONFIG_FILE" "REASON"
```
## Traffic and policy logs
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/var/log/safesquid/extended` | Stores `extended.log`, which details users, applications, security breaches, and each request or response processed by SafeSquid. Rotated files are named like `XXXX-extended.log`. | Incident investigation, user activity review, SIEM comparison, or policy verification. | Contains user, destination, policy, profile, category, application, and content-type evidence. Treat as sensitive personal and security data. |
`extended.log` records this legend:
```text theme={null}
"record_id" "client_id" "request_id" "date_time" "elapsed_time" "status" "size" "upload" "download" "bypassed" "client_ip" "username" "method" "url" "http_referer" "useragent" "mime" "filter_name" "filtering_reason" "interface" "cachecode" "peercode" "peer" "request_host" "request_tld" "referer_host" "referer_tld" "range" "time_profiles" "user_groups" "request_profiles" "application_signatures" "categories" "response_profiles" "upload_content_types" "download_content_types" "profiles"
```
## Native troubleshooting logs
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/var/log/safesquid/native` | Stores `native.log`, which records functional details for requests, security, redirects, and feature behavior. Rotated files are named like `XXXX-native.log`. | Feature behavior is unclear, request handling needs debugging, or support requests native evidence. | Supports deep troubleshooting. High verbosity can grow quickly and expose detailed traffic context. |
Native log verbosity is controlled by `LOG_LEVEL`:
| Value | Meaning |
| - | - |
| `16777216` | Warnings only |
| `33554432` | Errors only |
| `67108864` | Profiles only |
| `134217728` | Debug only |
| `268435455` | All activities and debug information |
| `33554435` | Default: errors, requests, and network |
## Performance evidence
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/var/log/safesquid/performance` | Stores `performance.log`, which records performance metrics for outages, resource shortfall, internet connectivity failure, and traffic surge analysis. Rotated files are named like `XXXX-performance.log`. | Slow browsing, connection exhaustion, memory pressure, DNS failures, or capacity review. | Provides progressive line-based metrics that can be analyzed with third-party tools such as GNU Plot. Missing data weakens capacity root-cause analysis. |
`performance.log` includes metrics for timestamps, elapsed time, client connections, transactions, thread pools, and outbound connection pools. It also records bytes in and out, cache object counts, and DNS query reuse and failures. It tracks memory, connection deltas, load averages, process counts, and CPU time.
## Privacy and process paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/var/log/safesquid/privacy` | Privacy log path listed in the wiki source. | Privacy-related logging is enabled or support asks for the path. | The wiki does not describe contents. Verify live product behavior before making definitive claims. |
| `/var/run/safesquid` | Stores `safesquid.pid`, the current SafeSquid process ID. The file changes on every restart. | Service status differs between tools, process restart is disputed, or incident timeline needs confirmation. | Confirms runtime process state. Stale PID data can mislead operations during outage response. |
## Log rotation
SafeSquid log rotation controls large log files. The wiki states SafeSquid rotates logs when they exceed `1GB` and compresses rotated logs with gzip. Before troubleshooting old events, check both active and rotated files.
## Next steps
* Use [Service and Startup Files](/architecture/files_and_folders/service_and_startup_files) to verify logrotate and startup controls.
* Use [Reports](/architecture/policy_management_console/reports) to compare log evidence with report views.
* Use [Files and Folders](/architecture/files_and_folders/files_and_folders) to return to the full server path reference.
# Files and Folders
Source: https://docs.safesquid.com/architecture/files_and_folders/main
Navigation hub for SafeSquid SWG server paths, service controls, policy files, runtime data, logs, and audit evidence.
# Find the Right File and Folder Reference
SafeSquid server paths hold service controls, module files, policy data, activation material, runtime databases, signature stores, and audit logs. Know these paths before an outage, upgrade, policy dispute, or support escalation so evidence is preserved and changes stay reviewable.
## Quickstart path
1. [Files and Folders](/architecture/files_and_folders/files_and_folders) - classify server paths by risk, evidence value, and change-control expectation.
2. [Service and Startup Files](/architecture/files_and_folders/service_and_startup_files) - verify service control, startup behavior, TCP tuning, log rotation, Monit, PAM, and kernel tuning.
3. [Application Binaries and Modules](/architecture/files_and_folders/application_binaries_and_modules) - identify SafeSquid binaries, add-on modules, feature libraries, section XML, and default startup files.
4. [Policy, Security, and UI Files](/architecture/files_and_folders/policy_security_and_ui_files) - locate activation files, policy XML, SSL material, SQLite configuration, UI files, CGI scripts, and templates.
5. [Runtime Data and Signatures](/architecture/files_and_folders/runtime_data_and_signatures) - review temporary files, cache, reporting databases, SSL runtime data, user data, and signature stores.
6. [Logs and Audit Evidence](/architecture/files_and_folders/logs_and_audit_evidence) - collect configuration, traffic, native, performance, privacy, and process evidence.
## Next steps
* Use [Support](/architecture/policy_management_console/support) to package evidence for escalation.
* Use [Reporting Service](/architecture/interface/reporting_service) to centralize log evidence.
# Policy, Security, and UI Files
Source: https://docs.safesquid.com/architecture/files_and_folders/policy_security_and_ui_files
SafeSquid SWG activation, policy, SSL, SQLite, user interface, CGI, template, CSS, JavaScript, image, and font path reference.
# Locate Policy, Security, and UI Files
Policy, security, and interface files define who can use SafeSquid and which controls apply. They also define how SSL material is stored and how the management interface renders. Treat these paths as sensitive. Unreviewed edits can stop the service, expose certificates, break policy rollback, or make support evidence unreliable.
## Product-owned root
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/usr/local/safesquid` | Contains `security`, `ui_root`, `sqlite`, and `bin` subdirectories for activation, user interface rendering, SQLite database configuration, SSL certificates, and scripts. | Building a server inventory, preparing support evidence, or confirming product-owned paths. | Shows the local SafeSquid application data root. Apply least privilege and backup controls. |
| `/usr/local/safesquid/bin` | Stores scripts that can run through the External Applications section. User-created scripts belong here when execution is required. | External application integrations fail or script execution needs review. | Shows executable extension points. Treat scripts as privileged automation and review them before deployment. |
## Security and policy paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/usr/local/safesquid/security` | Contains `policies`, `ssl`, and `dns` subdirectories plus activation files such as `activation_key`, `activation_key.updates`, and `activation_key.updates.backup`. | Activation fails, service stops unexpectedly, or license state needs evidence. | Activation files are service-critical. The wiki warns they should never be deleted because SafeSquid can stop. |
| `/usr/local/safesquid/security/policies` | Stores policy XML. The wiki identifies `default.config.xml`, current `config.xml`, and timestamped backup files named like `config_XXXX@YYYY_ZZZZ.xml`. | Policy rollback, audit review, change dispute, or configuration recovery. | `config.xml` is the latest saved configuration. Backup files preserve prior saves by username, IP address, and modification time. Treat all policy XML as sensitive. |
| `/usr/local/safesquid/security/ssl/` | Stores SSL root certificates, trusted bundle files, and `subca` material used in OpenVPN configuration. | HTTPS inspection issues, certificate trust review, or incident evidence collection. | Contains certificate material. Restrict access, back up securely, and avoid casual copying. |
| `/usr/local/safesquid/sqlite` | Stores SQLite configuration files: `users.db.conf`, `reporting_db.conf`, and `bypass_db.conf`. | Reporting, user database, or bypass database behavior needs investigation. | Shows database configuration. Incorrect edits can affect user, reporting, or bypass behavior. |
## Interface and template paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/usr/local/safesquid/ui_root/` | Root for files used to render the SafeSquid web user interface. | Interface rendering breaks or support asks for UI file evidence. | Product-owned interface surface. Customization can affect supportability. |
| `/usr/local/safesquid/ui_root/cgi-bin` | Stores scripts for defined functions such as support tarball generation, performance plot generation, and Kerberos setup. | Support bundle generation fails, performance plots fail, or Kerberos setup scripts need review. | Contains executable UI-backed functionality. Review changes as privileged code. |
| `/usr/local/safesquid/ui_root/css` | Stores CSS files that define interface display. | Interface layout breaks after change or upgrade. | Unsupported edits can disrupt the management interface. Use change control for any customization. |
| `/usr/local/safesquid/ui_root/fonts` | Stores web font files, including `glyphicons-halflings-regular.*`, `fontawesome-webfont.*`, and `hinted-SegoeUI.*`. | Icons or fonts fail to render in the interface. | Evidence for UI rendering dependencies. Avoid edits unless support directs them. |
| `/usr/local/safesquid/ui_root/img` | Stores image files shown in the SafeSquid interface, including PNG and GIF assets. | Interface images fail to load or branding changes need review. | Custom image changes can require related CSS or JavaScript changes. Treat as support-sensitive. |
| `/usr/local/safesquid/ui_root/js` | Stores JavaScript files used by the SafeSquid interface. | Interface actions fail or browser errors appear. | JavaScript changes can break administration workflows. Avoid manual edits without review. |
| `/usr/local/safesquid/ui_root/templates` | Stores templates and scripts such as `upgrade.sh`, `success.html`, `landing.html`, and `block_bypass.html`. | Block pages, captive portal pages, login success pages, or upgrades fail. | Templates affect user-facing security decisions and upgrade behavior. Test and review all changes. |
## Rollback guidance
Before changing policy, SSL, activation, UI, or script paths, preserve the original files. Record owner, timestamp, reason, and rollback path. For policy rollback, use timestamped `config_XXXX@YYYY_ZZZZ.xml` files only after confirming the correct user, source IP, and modification time.
## Next steps
* Use [Logs and Audit Evidence](/architecture/files_and_folders/logs_and_audit_evidence) to correlate policy changes with `config.log`.
* Use [Configure](/architecture/policy_management_console/configure) for normal policy administration.
* Use [Runtime Data and Signatures](/architecture/files_and_folders/runtime_data_and_signatures) to locate runtime data and signature stores.
# Runtime Data and Signatures
Source: https://docs.safesquid.com/architecture/files_and_folders/runtime_data_and_signatures
SafeSquid SWG temporary files, cache, reporting databases, SSL runtime data, user data, and signature store path reference.
# Locate Runtime Data and Signatures
Runtime data and signature stores explain what SafeSquid is processing now, what it cached. They also show which local data supports categorization, content inspection, image analysis, and malware scanning. These files support investigation and capacity review, but they can also contain sensitive traffic or user context.
## Temporary and cache paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/tmp/safesquid` | Stores temporary files created while SafeSquid runs or upgrades. | Upgrade fails, temporary disk use grows, or support requests runtime artifacts. | Temporary files can explain interrupted operations. Review before cleanup during an incident. |
| `/var/cache/safesquid` | Default store for cacheable objects when caching is enabled. | Disk growth, cache behavior, or performance issues. | Cache content can contain requested objects. Treat as sensitive and align cleanup with policy. |
## Database paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/var/db/safesquid/report` | Stores SQLite reporting database files such as `main.db`, `safesquid2.db`, `main.db-shm`, `main.db-wal`, `safesquid2.db-shm`, `safesquid2.db-wal`, and timestamped `YYYYMMDDhhmmss-main.db` files. | Reports are missing, SIEM results differ from local data, or investigation needs database evidence. | The wiki states a timestamped `YYYYMMDDhhmmss-main.db` file is created after every `1000` transactions. `DB-WAL` files hold pending write-ahead log changes; `DB-SHM` files hold shared memory state. |
| `/var/db/safesquid/ssl` | Stores temporary SSL certificates created for web servers during HTTPS inspection. | HTTPS inspection fails or certificate cache behavior needs review. | Contains generated certificate material. Restrict access and avoid exporting without approval. |
| `/var/db/safesquid/users` | Reserved user database path in the wiki source. | User database behavior needs investigation or support asks for the path. | The wiki does not describe contents. Verify live product behavior before making claims. |
## Signature and library paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/var/lib/safesquid/application_signatures` | Stores the `applications3` file in an `updates` folder. SafeSquid checks and downloads the latest application signature file from the cloud hourly. | Application detection fails or signature update state needs evidence. | Shows local application signature state. Failed hourly updates can reduce application-aware controls. |
| `/var/lib/safesquid/category` | Stores `category.db`, the local database for custom categories. | Custom categories do not match expected policy results. | Contains local category data. Back up before category recovery work. |
| `/var/lib/safesquid/content_signatures` | Stores `magic.mgc`, `libmagic.so`, and an `updates` folder containing `content4`. SafeSquid checks and downloads the latest content signature file hourly. | Content-type detection fails or content inspection results change unexpectedly. | Shows local content signature and library state. Failed updates can weaken content classification. |
| `/var/lib/safesquid/imgfilter` | Stores Image Analyzer libraries such as `libIAImageReaderShared.so`, `libIAEngineShared.so`, and `imgfilter.tune`. SafeSquid checks and downloads the latest library files hourly. | Image Analyzer fails, dependency errors appear, or threshold behavior needs review. | Contains runtime dependencies and tuning for image analysis. Changes affect block decisions. |
| `/var/lib/safesquid/sscore2` | Stores SScore libraries and signatures. SScore signatures are in `parental_sig`; the latest `libbdupdatesdk.so` is downloaded to `update` hourly. | Website categorization fails or SScore update health needs evidence. | Shows categorization support files. Failed updates can reduce classification accuracy. |
| `/var/lib/safesquid/svscan` | Stores SvScan libraries and anti-malware signatures. Anti-malware signatures are in `Plugins`; the latest `libbdupdatesdk.so` is downloaded to `update` hourly. | Malware scanning fails or signature currency needs evidence. | Shows anti-malware update state. Failed updates can weaken malware detection. |
## Evidence handling
Database, cache, SSL, and signature files can contain sensitive operational data. Copy them only for approved troubleshooting or audit work. Preserve timestamps and file ownership when evidence integrity matters.
## Next steps
* Use [Application Binaries and Modules](/architecture/files_and_folders/application_binaries_and_modules) to confirm the related feature modules exist.
* Use [Reporting Service](/architecture/interface/reporting_service) to compare local reporting data with centralized evidence.
* Use [Logs and Audit Evidence](/architecture/files_and_folders/logs_and_audit_evidence) to locate the logs that record audit evidence.
# Service and Startup Files
Source: https://docs.safesquid.com/architecture/files_and_folders/service_and_startup_files
SafeSquid SWG service control, startup, TCP tuning, log rotation, Monit, PAM, and system tuning path reference.
# Locate Service and Startup Files
Service and startup files define how SafeSquid starts, stops, recovers, and tunes the Linux host. Treat them as availability controls. Unapproved changes can stop enforcement, hide startup drift, or make performance symptoms harder to explain during an incident.
## Startup control paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/etc/init.d/safesquid` | Controls the SafeSquid service with `start`, `stop`, `restart`, `status`, and `foreground`. It also sets required startup dependencies and environment variables. | Installation, upgrade, service outage, startup drift, or incident review. | Shows the local service control path. Incorrect edits can prevent SafeSquid from starting after reboot. |
| `/etc/init.d/tcp_tune.sh` | Tunes TCP parameters for connection queues, socket buffers, pending requests, port ranges, overflow handling, TIME-WAIT reuse, keep-alive behavior, and receive or transmit memory. | Capacity tuning, connection surge, slow response, or failed connection investigations. | Writes modified TCP parameters to `/tmp/sysctl_.conf` for debugging. Poor tuning can reduce throughput or exhaust host resources. |
| `/etc/sysctl.conf` | Stores Linux kernel tuning parameters used at runtime under `/proc/sys`. SafeSquid modifies and saves this file for system variables. | Performance review, network tuning, or post-upgrade verification. | Records host-level tuning for memory, connection limits, packet queues, port ranges, socket memory, and TCP buffers. Unreviewed edits can affect every service on the host. |
## Service supervision paths
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/etc/monit/conf.d/safesquid.monit` | Monit configuration that monitors SafeSquid and restarts it if the process stops. | Service unexpectedly stops, auto-restart fails, or production health checks disagree. | Proves whether SafeSquid has local self-healing configured. Missing or broken rules can leave the proxy down until manual intervention. |
| `/etc/pam.d/safesquid` | PAM configuration for SafeSquid authentication workflows. The wiki references `pam_unix.so` and `pam_permit.so`. | Authentication failures, PAM hardening, or support escalation. | Shows which PAM modules participate in authentication. Treat changes as security-sensitive because PAM can affect user validation and access behavior. |
## Log lifecycle path
| Path | Purpose | Inspect when | Evidence and risk |
| - | - | - | - |
| `/etc/logrotate.d/safesquid` | Rotates and archives SafeSquid logs. The wiki states SafeSquid logrotate rotates related logs when a log file exceeds `1GB` and compresses rotated logs with gzip. | Disk growth, missing logs, retention review, or SIEM mismatch. | Proves local log lifecycle behavior. Incorrect rotation can fill disks, delete evidence early, or break forensic continuity. |
## Change-control guidance
Back up these files before editing them. Record the change ticket, reviewer, original file hash, modified file hash, restart requirement, and rollback command. After service or startup changes, verify SafeSquid status and confirm a known request appears in local logs.
## Next steps
* Use [Logs and Audit Evidence](/architecture/files_and_folders/logs_and_audit_evidence) to verify service and log behavior.
* Use [Supporting Services](/architecture/interface/supporting_services) to validate Monit, BIND, and NTP dependencies.
* Use [Application Binaries and Modules](/architecture/files_and_folders/application_binaries_and_modules) to locate the binaries and modules the service loads.
# BIND Local DNS Resolver
Source: https://docs.safesquid.com/architecture/interface/bind
Low-latency, reliable DNS resolution for SafeSquid SWG with secure recursion and caching
# Run BIND as the Local DNS Resolver
BIND provides a local DNS resolver for SafeSquid, reducing lookup latency and improving cache hit rates for frequently accessed domains.
**Why you need this:** Relying on external DNS servers introduces latency, rate-limiting, and dependency on third parties. A local BIND resolver improves performance and reliability.
## Prerequisites
:::note
**Before You Start**
* Linux host with root/sudo access
* SafeSquid installed
* Firewall allows UDP/TCP port 53 outbound (to root DNS servers or forwarders)
* NTP configured (for DNSSEC validation)
:::
## Installation and Configuration
### 1. Install BIND
**Debian/Ubuntu:**
```bash theme={null}
sudo apt update
sudo apt install -y bind9 bind9-utils
```
**RHEL/Rocky/CentOS:**
```bash theme={null}
sudo dnf install -y bind bind-utils
```
**Verify installation:**
```bash theme={null}
named -v
```
Expected result: one line starting with `BIND 9.`, for example `BIND 9.20.26-1~deb13u1-Debian (Stable Release)`. If the shell reports `command not found`, run `/usr/sbin/named -v`, because `/usr/sbin` is not on the default PATH of a non-root user.
***
### 2. Configure BIND Options
**Edit configuration file:**
* **Debian/Ubuntu:** `/etc/bind/named.conf.options`
* **RHEL/CentOS:** `/etc/named.conf`
```bash theme={null}
sudo nano /etc/bind/named.conf.options
```
**Add/modify:**
```text theme={null}
options {
directory "/var/cache/bind";
recursion yes;
allow-recursion { 127.0.0.1; 10.0.0.0/8; 172.16.0.0/12; 192.168.0.0/16; };
listen-on port 53 { 127.0.0.1; 10.0.0.1; }; // Replace 10.0.0.1 with your server IP
allow-query { any; };
dnssec-validation auto;
auth-nxdomain no;
minimal-responses yes;
rate-limit {
responses-per-second 25;
};
};
```
**Explanation:**
* **recursion yes** — Enables BIND to query upstream DNS on behalf of clients
* **allow-recursion** — Limits recursion to private IP ranges (prevents open resolver abuse)
* **listen-on** — IP addresses BIND listens on (127.0.0.1 + server IP)
* **dnssec-validation auto** — Validates DNSSEC signatures
* **rate-limit** — Prevents DNS amplification attacks
**Verify configuration syntax:**
```bash theme={null}
sudo named-checkconf
```
Should return nothing (silence means success).
***
### 3. Configure Root Hints and Local Zones (Optional)
**Download root hints file:**
```bash theme={null}
sudo curl -o /var/cache/bind/root.hints https://www.internic.net/domain/named.root
```
**Add root hints to configuration:**
Edit `/etc/bind/named.conf` (or `/etc/named.conf`):
```bash theme={null}
zone "." {
type hint;
file "/var/cache/bind/root.hints";
};
```
**Configure local zone overrides** (for internal domains):
Create `/etc/bind/named.conf.local`:
```bash theme={null}
sudo nano /etc/bind/named.conf.local
```
Add:
```text theme={null}
zone "corp.local" {
type forward;
forwarders { 10.0.0.10; 10.0.0.11; }; // Your internal DNS servers
};
```
**Verify zone syntax:**
```bash theme={null}
sudo named-checkzone corp.local /dev/null
```
***
### 4. Enable and Start BIND
```bash theme={null}
# Debian/Ubuntu:
sudo systemctl enable --now bind9
systemctl is-active bind9
# RHEL/CentOS:
sudo systemctl enable --now named
systemctl is-active named
```
Expected result: each `is-active` command prints `active`.
***
### 5. Point SafeSquid to Local Resolver
**Edit `/etc/resolv.conf` on the SafeSquid server:**
```bash theme={null}
sudo nano /etc/resolv.conf
```
**Set:**
```text theme={null}
nameserver 127.0.0.1
```
**Or if BIND is on a different server:**
```text theme={null}
nameserver 10.0.0.1 # BIND server IP
```
**Test DNS resolution:**
```bash theme={null}
dig @127.0.0.1 example.com
```
Expected result: `status: NOERROR`, flags `qr rd ra`, an `ANSWER SECTION` listing one or more `A` records, and `SERVER: 127.0.0.1#53(127.0.0.1) (UDP)`. A cached repeat answers in about 0 msec.
***
### 6. Harden Resolver (Production)
**Enable logging:**
Edit `/etc/bind/named.conf` (or `/etc/named.conf`):
```bash theme={null}
logging {
channel default_log {
file "/var/log/named/default.log" versions 5 size 10m;
severity info;
print-time yes;
};
category resolver { default_log; };
category security { default_log; };
};
```
**Create log directory:**
```bash theme={null}
sudo mkdir -p /var/log/named
sudo chown bind:bind /var/log/named
```
**Restart BIND:**
```bash theme={null}
sudo systemctl restart bind9 # or named
```
**Additional hardening:**
* **Restrict recursion** to SafeSquid server IP only (tighten `allow-recursion`)
* **Enable Response Policy Zones (RPZ)** for threat blocking (optional)
* **Monitor logs** for unusual query patterns
***
## Verify BIND is Working
### Test DNS Query
```bash theme={null}
dig @127.0.0.1 example.com +stats
```
Expected result:
* `status: NOERROR`
* **ANSWER SECTION** with IP address
* **Query time** in milliseconds
* **SERVER: 127.0.0.1#53** (confirming local resolver)
**Check cache hit:**
Run the same query twice:
```bash theme={null}
dig @127.0.0.1 google.com
dig @127.0.0.1 google.com
```
Second query should be faster (cached response).
***
### Check BIND Status
```bash theme={null}
sudo rndc status
```
**Expected:** Shows version, uptime, and statistics.
***
### Monitor Logs
```bash theme={null}
# Debian/Ubuntu:
sudo journalctl -u bind9 -f
# RHEL/CentOS:
sudo journalctl -u named -f
# Or custom log:
sudo tail -f /var/log/named/default.log
```
**Expected log entries:**
```text theme={null}
[date] info: client 192.168.1.1#port: query: example.com IN A
[date] info: resolver: success for example.com
```
***
## Troubleshooting
| **Issue** | **Likely Cause** | **Fix** |
| - | - | - |
| SERVFAIL on DNSSEC domains | NTP not configured or trust anchors missing | Configure NTP first, verify `dnssec-validation auto` |
| High query latency | No caching or blocked egress to root servers | Check firewall allows UDP/TCP 53 outbound; verify `root.hints` |
| "Refused" queries | Recursion restricted or listen-on mismatch | Check `allow-recursion` includes client IP; verify `listen-on` has server IP |
| Port 53 already in use | Another resolver (systemd-resolved, dnsmasq) running | Stop conflicting service: `sudo systemctl disable --now systemd-resolved` |
| Cache not working | BIND restarting frequently or low memory | Check `journalctl -u bind9` for errors; increase memory if needed |
**Still not working?**
1. **Test DNS path:**
```bash theme={null}
dig @8.8.8.8 example.com +short
```
If this works but local doesn't, BIND config issue.
2. **Check BIND configuration:**
```bash theme={null}
sudo named-checkconf
sudo rndc status
```
3. **Trace DNS query:**
```bash theme={null}
dig @127.0.0.1 example.com +trace
```
Shows full resolution path from root to answer.
4. **Check logs:**
```bash theme={null}
sudo journalctl -u bind9 -n 50
```
***
## Source register
| Topic | Status | Source |
| - | - | - |
| Recursion, forwarding, `safesquid.dns.conf` stub patterns | **Confirmed** | This guide |
| DNSSEC validation dependency on NTP | **Confirmed** | This page, [NTP](/architecture/interface/ntp) |
***
## Next Steps
1. **[Monit](/architecture/interface/supporting_services_monit)** - Monitor BIND and auto-restart if it crashes
2. **[NTP](/architecture/interface/ntp)** - Required for DNSSEC validation
3. **[Integrated DNS Security](/architecture/overview/integrated_dns_security)** - Configure DNSBL for malicious domain blocking
# Policy Management Console
Source: https://docs.safesquid.com/architecture/interface/configuration_portal
Administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Control Policy From the Management Console
The Policy Management Console (Configuration Portal) is the SafeSquid web interface for defining, simulating, and enforcing policy. It covers access control, URL filtering, SSL inspection, and DLP. Administrators use it to configure restriction profiles, real-time content security, authentication, and operational settings.
## Problems addressed
Operators need a single **authoritative** place to define Layer 7 policy. They also need to simulate or review impact and push consistent rules to proxy nodes. Fragmented tooling increases misconfiguration risk and weakens audit narratives.
## Outcomes operators expect
* One console for restriction profiles, real-time content security, authentication, SSL inspection, and reports (paths in **Key Sections** below).
* Repeatable UI paths suitable for change control and screenshots in runbooks.
* A place where policy changes, interface access, and administrative actions can be traced for audit and investigation.
## Advantages vs “CLI-only” or multi-vendor policy stacks
SafeSquid ships the console **with** the SWG so policy and enforcement stay product-coupled.
## Acquire, deploy, use
Install SafeSquid and reach the UI via **Access Methods** below. Then follow the linked sections (SSL Inspection, Authentication, Access Restriction) for each control.
## Access Methods
Access the interface from a browser configured to use SafeSquid as proxy:
* **Via proxy:** `http://safesquid.cfg/` (embedded Rest UI interface built into SafeSquid; accessible only when your client uses the proxy, but NOT resolved by SafeSquid's DNS resolver)
* **Direct access:** `https://SERVER-IP:8443/` (before proxy configuration or for troubleshooting)
**First-time setup:** See [Connect Your Client](/getting_started/client_configuration/connect_your_client) to configure your browser to use SafeSquid.
:::tip
**Login Credentials**
Default credentials after SAB installation: **administrator** / **safesquid**\
Change immediately after first login for security.
:::
***
## Key Sections
### 1. Restriction Profiles
Define access control rules by URL category, application signature, user/group, and time window.
**Location:** Sidebar → **Restriction Profiles** → **Access Restrictions**
**Use for:**
* Block malicious sites and adult content
* Enforce work-hours internet access
* Allow specific applications while blocking others
**Details:** [Access Restriction](/use_cases/access_restriction/access_restriction)
***
### 2. Real-Time Content Security
Configure deep content inspection: DLP, malware scanning, image analysis, and content modification.
**Location:** Sidebar → **Real Time Content Security**
**Use for:**
* Data leakage prevention (DLP)
* Malware scanning with ClamAV/ICAP
* Rewrite HTTP headers
* Block specific MIME types
**Details:** [Data Leakage Prevention](/use_cases/data_leakage_prevention/data_leakage_prevention), [Malware Scanners](/use_cases/malware_scanning/malware_scanners)
***
### 3. Authentication
Integrate with Active Directory, LDAP, or configure local users for identity-based policies.
**Location:** Sidebar → **Authentication**
**Use for:**
* User-aware access control
* SSO with Active Directory
* PAM authentication
**Details:** [Authentication](/use_cases/authentication/authentication)
***
### 4. SSL Inspection
Enable HTTPS decryption to inspect encrypted traffic for threats and policy violations.
**Location:** Sidebar → **SSL Inspection**
**Use for:**
* Inspect HTTPS traffic
* Deploy enterprise Root CA
* Selective decryption by category/user
**Details:** [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)
***
### 5. Reports & Logs
Access real-time logs, historical reports, and traffic analytics.
**Location:** Top menu → **Reports**
**Use for:**
* Audit trails and compliance
* User activity investigation
* Traffic pattern analysis
## Operational significance
The configuration portal matters for more than policy editing:
* it is the operational source of truth for many SafeSquid controls
* interface actions can become audit evidence through configuration and access logs
* misconfiguration here can affect authentication, SSL inspection, DLP, categorization, and reporting at once
Teams should treat changes in this interface as change-controlled events, not casual clicks.
***
## Navigation Tips
* **Top-right menu:** System settings, support, and logout
* **Sidebar:** Policy configuration sections
* **Top menu:** Reports, diagnostics, and system status
* **Apply button:** Save and apply configuration changes (restart required for some settings)
***
## Best Practices
1. **Test policies before enforcement:** Use simulation mode when available
2. **Document changes:** Use policy description fields for change tracking
3. **Back up configuration:** Use cloud sync or manual export before major changes
4. **Review logs regularly:** Check policy effectiveness and adjust as needed
## Verification and validation
After making a change in the portal, confirm all of the following:
* the expected policy behavior actually changed
* the change is recorded in the configuration or interface evidence path
* clustered nodes reflect the intended policy state if clustering is in use
* no unrelated controls were affected by the edit
## Troubleshooting
**Symptom:** A policy change appears saved, but behavior does not change.\
**Likely cause:** The change was not fully applied, did not match the expected rule path, or did not replicate.\
**Isolation:** Compare the saved configuration, active policy scope, and if relevant the cluster state.\
**Remediation:** Reapply the intended change and verify the correct rule order.\
**Retest:** Run the same request and confirm the new policy outcome.
**Symptom:** Operators cannot prove who changed policy.\
**Likely cause:** Configuration or interface evidence is not being reviewed or retained.\
**Isolation:** Check `config.log`, UI access logs, and the reporting path.\
**Remediation:** Retain and review the administrative evidence path.\
**Retest:** Make a controlled change and confirm it is recorded.
***
## Source register
| Topic | Status | Source |
| - | - | - |
| Policy Management Console / sidebar structure | **Confirmed** | This page (UI paths) |
| Default credentials **administrator** / **safesquid** | **Confirmed** | This page; change after first login |
| `safesquid.cfg` / **8443** access | **Confirmed** | This page, [Getting Started](/getting_started/welcome) |
***
## Next Steps
1. **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - Enable HTTPS decryption
2. **[Authentication](/use_cases/authentication/authentication)** - Configure user authentication
3. **[Access Restriction](/use_cases/access_restriction/access_restriction)** - Set up URL filtering and content policies
# NTP Time Synchronization
Source: https://docs.safesquid.com/architecture/interface/ntp
Accurate system time for SafeSquid SWG authentication, TLS, and logging integrity
# Keep System Time Accurate With NTP
NTP (Network Time Protocol) keeps your SafeSquid server's clock synchronized with enterprise time sources. Accurate time is critical for SSO/Kerberos authentication, TLS certificate validation, and audit log timestamps.
**Why you need this:** Clock drift breaks Kerberos (requires ≤5 minutes skew) and causes TLS certificate errors. It also makes log correlation unreliable.
## Prerequisites
:::note
**Before You Start**
* Linux host with root/sudo access
* Enterprise NTP servers or domain controllers providing time
* Firewall allows UDP port 123 outbound
* Network connectivity to NTP sources
:::
## Installation and Configuration
### 1. Install Time Synchronization Service
**Prefer chrony** (modern, faster sync):
**Debian/Ubuntu:**
```bash theme={null}
sudo apt update
sudo apt install -y chrony
```
**RHEL/Rocky/CentOS:**
```bash theme={null}
sudo dnf install -y chrony
```
**Verify installation:**
```bash theme={null}
chronyd -v
```
Expected result: a line that names the installed chrony version.
:::tip
**Alternative: ntpd**
If your environment uses `ntpd` instead of `chrony`, install with:
```bash theme={null}
sudo apt install -y ntp # Debian/Ubuntu
sudo dnf install -y ntp # RHEL/CentOS
```
Configuration is similar but uses `/etc/ntp.conf`.
:::
***
### 2. Configure Time Sources
**Edit chrony configuration:**
* **Debian/Ubuntu:** `/etc/chrony/chrony.conf`
* **RHEL/CentOS:** `/etc/chrony.conf`
```bash theme={null}
sudo nano /etc/chrony/chrony.conf
```
**Replace default pool servers with your enterprise NTP servers:**
```text theme={null}
# For Active Directory environments, prefer domain controllers:
server dc1.company.com iburst
server dc2.company.com iburst
# Or use enterprise NTP servers:
server ntp1.company.com iburst
server ntp2.company.com iburst
# For AD, set minimal sources to 2:
# minsources 2
# Allow large initial time corrections:
makestep 1.0 3
# Drift file (tracks clock frequency):
driftfile /var/lib/chrony/chrony.drift
# Log directory:
logdir /var/log/chrony
```
**Explanation:**
* **server ... iburst** — Speeds up initial synchronization
* **makestep 1.0 3** — Allows step (immediate) corrections if offset >1 second, up to 3 times
* **driftfile** — Saves clock frequency for faster sync after restart
* **logdir** — Where chrony logs are stored
**Save and exit.**
***
### 3. Enable and Start Chrony
```bash theme={null}
sudo systemctl enable --now chronyd
systemctl is-active chronyd
systemctl is-enabled chronyd
```
Expected result: Both commands return `active` and `enabled`.
***
### 4. Validate Synchronization
**Check tracking status:**
```bash theme={null}
chronyc tracking
```
Expected result:
```text theme={null}
Reference ID : 192.168.1.10 (ntp1.company.com)
Stratum : 3
System time : 0.000123 seconds slow of NTP time
Last offset : -0.000045 seconds
RMS offset : 0.000123 seconds
```
**Key fields:**
* **Reference ID:** Your NTP server
* **Stratum:** Lower is better (1-4 typical)
* **System time offset:** Should be within milliseconds (\< 0.1 seconds)
***
**Check source status:**
```bash theme={null}
chronyc sources -v
```
Expected result:
```text theme={null}
.-- Source mode '^' = server, '=' = peer
/ .- Source state '*' = current best, '+' = combined, '-' = not combined,
| / '?' = unreachable, 'x' = time may be in error
||
|| MS Name/IP address Stratum Poll Reach LastRx Last sample
|| ===============================================================================
^* ntp1.company.com 2 6 377 25 -123us[ -156us] +/- 12ms
^+ ntp2.company.com 2 6 377 26 +234us[ +201us] +/- 15ms
```
**Key fields:**
* **\*** (asterisk) — Current best source (should have at least one)
* **Reach** — Should be `377` (all recent polls successful)
* **Last sample** — Time offset in microseconds/milliseconds
***
### 5. Align SafeSquid Authentication
**For SSO/Kerberos with Active Directory:**
Verify time skew is within 5 minutes of the domain controller:
```bash theme={null}
# Check local time:
date
# Check DC time (if accessible):
net time \\DC1.company.com /set /yes
```
**Or use this to compare:**
```bash theme={null}
ntpdate -q dc1.company.com
```
Expected result: Offset less than 300 seconds (5 minutes).
:::caution
**Kerberos Requirement**
Kerberos authentication fails if time skew exceeds 5 minutes. For production Active Directory environments, keep skew under 1 minute.
:::
***
## Verify NTP is Working
### Check Synchronization Status
```bash theme={null}
chronyc tracking
```
Expected result:
* **Reference ID:** Shows your NTP server (not `0.0.0.0`)
* **System time offset:** \< 0.1 seconds
* **Stratum:** 2-4 (depending on your NTP server)
***
### View Source Statistics
```bash theme={null}
chronyc sourcestats -v
```
Expected result: All sources show reasonable offsets and low jitter.
***
### Monitor Logs
```bash theme={null}
# Check recent sync events:
sudo journalctl -u chronyd -n 50
# Or check chrony log:
sudo tail -f /var/log/chrony/tracking.log
```
Expected result (log entries):
```text theme={null}
Selected source 192.168.1.10
System time wrong by 0.123 seconds
Clock was stepped
```
***
## Troubleshooting
| **Issue** | **Likely Cause** | **Fix** |
| - | - | - |
| No synchronization | UDP 123 blocked or wrong server names | Allow UDP 123 outbound; verify server names resolve: `dig ntp1.company.com` |
| Frequent step corrections | Unstable time source or VM host time interference | Use stable NTP sources; disable VM time sync if using NTP |
| Stratum shows 16 | Can't reach any NTP server | Check firewall, network connectivity, server names |
| SSO/Kerberos failures | Time skew >5 minutes | Force sync: `sudo chronyd -q 'server ntp1.company.com iburst'` |
| "System clock wrong" errors | Large initial offset | Run `sudo chronyd -q` to step clock, then restart chronyd |
**Still not working?**
1. **Test NTP server connectivity:**
```bash theme={null}
ntpdate -q ntp1.company.com
```
Should show offset.
2. **Check chrony configuration:**
```bash theme={null}
chronyc sources
chronyc tracking
```
3. **Force time sync:**
```bash theme={null}
sudo chronyd -q 'server ntp1.company.com iburst'
sudo systemctl restart chronyd
```
4. **Check logs:**
```bash theme={null}
sudo journalctl -u chronyd -n 50
```
***
## Production Best Practices
1. **Use at least 3 NTP sources** for redundancy:
```text theme={null}
server ntp1.company.com iburst
server ntp2.company.com iburst
server ntp3.company.com iburst
```
2. **For Active Directory, prefer domain controllers:**
```text theme={null}
server dc1.company.com iburst prefer
server dc2.company.com iburst
```
3. **Monitor time drift with Monit:**
Add to `/etc/monit/conf.d/chrony`:
```text theme={null}
check process chronyd matching chronyd
start program = "/bin/systemctl start chronyd"
stop program = "/bin/systemctl stop chronyd"
```
4. **Alert on large offsets:**
* Configure monitoring to alert if offset >1 second
* Investigate VM host time sync conflicts
* Check for network latency to NTP servers
***
## Source register
| Topic | Status | Source |
| - | - | - |
| Chrony / NTP for Kerberos and TLS | **Confirmed** | This guide, [Authentication](/use_cases/authentication/authentication) |
| AD clock skew tolerance | **Draft** | **5 minutes** called out in the [Supporting Services hub](/architecture/interface/supporting_services_monit); **CTO** confirm max skew for supported builds |
***
## Next Steps
1. **[Monit](/architecture/interface/supporting_services_monit)** - Monitor chronyd and auto-restart if needed
2. **[BIND](/architecture/interface/bind)** - DNSSEC validation requires accurate time
3. **[Authentication](/use_cases/authentication/authentication)** - Configure SSO/Kerberos (requires NTP)
# Reporting & Forensics
Source: https://docs.safesquid.com/architecture/interface/reporting_service
Reporting and forensics in SafeSquid — centralized visibility, SIEM-ready logging, audit evidence, and operational investigation workflows for proxy deployments.
# Investigate Incidents With Reporting and Forensics
Reporting is not optional in an enterprise SWG. If SafeSquid enforces policy but the team cannot prove what happened, the control cannot support investigations, audits, or serious operations. Proof means who accessed what, which policy fired, and how an override occurred.
## Problem statement
Distributed proxy nodes, encrypted traffic, identity-aware policy, and exception handling all create evidence that must be retained and searched. When reporting is weak, incident response slows down, audit narratives break, and teams lose confidence in enforcement.
## Client scenario
Use this page when you need to understand how SafeSquid supports:
* centralized visibility across one or more proxy nodes
* forwarding to SIEM or reporting stacks
* forensic use of access, configuration, bypass, privacy, and security logs
* audit evidence for policy enforcement and privileged changes
## Key benefits
* Centralized evidence for multi-node deployments
* Better incident investigation because logs include user, destination, action, and policy context
* Stronger auditability through configuration, bypass, interface, and security records
* Operational flexibility because logs can stay local, feed the Reporting Service, or stream to external SIEM tooling
## What SafeSquid provides
### Centralized reporting and analytics
The Reporting Service is the centralized visibility layer for SafeSquid traffic and policy outcomes. It supports dashboards, reporting workflows, and evidence collection for security operations and audit review.
### SIEM-ready log forwarding
Internal product knowledge confirms that SafeSquid generates detailed access logs consumable by SIEM tools that accept UDP log input. Confirmed compatible destinations include:
* Splunk
* IBM QRadar
* ArcSight
* ELG-based reporting stacks
This matters because many enterprises already standardize on a SIEM. SafeSquid should fit the existing investigation workflow rather than forcing the SOC to use only the proxy-local interface.
### Forensic log classes
SafeSquid documents several log classes that are directly relevant to investigations:
* `extended.log` for detailed request-level activity
* `config.log` for configuration changes and interface actions
* `performance.log` for system behavior and capacity troubleshooting
* `bypass.log` for policy override and bypass-related events
* `privacy.log` for privacy-related records
* native logs for functional and debugging detail
The security posture knowledge base also confirms these evidence-relevant record types:
* UI Access Logs
* Privileged Access Logs
* Bypass Logs
* Deep Content Security Logs
* Content Security Policy Violation Logs
### Evidence value
Use reporting and logging to answer questions such as:
* Which user or group accessed the destination?
* Was the request allowed, blocked, bypassed, or modified?
* Which policy or profile influenced the outcome?
* Did a privileged administrator change configuration before the incident?
* Did SSL inspection, DLP, or malware-related controls trigger?
## Deployment patterns
### Local reporting on a single node
Use this for small or temporary deployments where reporting scale and retention needs are limited.
### Dedicated reporting path
Use a dedicated reporting service or SIEM path when:
* the deployment has multiple proxy nodes
* retention requirements exceed local storage comfort
* the SOC expects centralized search and alerting
* auditors require durable, exportable evidence
### External SIEM integration
Use external SIEM when the organization already has an established investigation platform. SafeSquid evidence then appears in the same operational workflow.
## Verification and validation
After deployment, validate all of the following:
* the expected logs are being generated
* forwarded logs arrive in the reporting destination or SIEM
* clustered nodes all contribute events
* user identity appears where authentication is expected
* configuration changes and bypass events are traceable
Useful evidence includes:
* searches for a known test request in `extended.log`
* a visible configuration change in `config.log`
* a known bypass event in `bypass.log`
* confirmation that the external reporting destination receives UDP log traffic
## Troubleshooting guide
**Symptom:** Traffic works, but no events appear in the SIEM.\
**Likely cause:** Log forwarding path, destination listener, or network allowlist is wrong.\
**Isolation:** Confirm local log generation first, then trace the forwarding path to the SIEM collector.\
**Remediation:** Correct forwarding configuration or network access.\
**Retest:** Trigger a fresh test request and confirm it appears in the destination.
**Symptom:** Logs exist, but user attribution is missing.\
**Likely cause:** Authentication is not active for the tested flow, or the request used a bypass path.\
**Isolation:** Compare the request path against authentication policy and identity logs.\
**Remediation:** Correct authentication scope or remove unintended bypass.\
**Retest:** Repeat the same request with an authenticated user and confirm attribution.
**Symptom:** Audit trails do not show who changed policy.\
**Likely cause:** Configuration logging or interface access review is incomplete.\
**Isolation:** Check `config.log`, UI access logs, and privileged-access records.\
**Remediation:** Enable or retain the required evidence path.\
**Retest:** Make a controlled change and confirm it is recorded.
## Related controls / next steps
* [Audit & Forensics](/use_cases/audit_and_forensics/audit_forensics) for the broader logging and evidence model
* [Security Logs](/use_cases/audit_and_forensics/security_logs) for detailed log classes and locations
* [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) for multi-node evidence planning
# Self-Service Portal
Source: https://docs.safesquid.com/architecture/interface/self_service_portal
SafeSquid Self-Service Portal — cloud-managed activation, licensing, backup, categorization, certificate, and related operational workflows for SafeSquid deployments.
# Manage Activation and Licensing in the Self-Service Portal
The Self-Service Portal is a SafeSquid-managed cloud service at `https://key.safesquid.com`. It is part of the product operating model, not just a convenience website. It handles activation-key distribution and other cloud-managed workflows that influence licensing, categorization, backup, and certificate-related operations.
**Access:** [https://key.safesquid.com](https://key.safesquid.com)
## Problem statement
If licensing, categorization, backup, or certificate workflows are scattered across email threads and manual files, deployments become fragile and support-dependent. Teams need a controlled place to retrieve activation material and manage cloud-linked settings. They also need to align multiple installations to the same organizational context.
## Client scenario
Use the portal when you need to:
* register and obtain activation keys
* manage licensing and subscription state
* support SSL certificate workflows
* manage custom categorization or cloud-linked policy data
* understand cloud dependencies in restricted or sovereignty-sensitive deployments
## Key benefits
* Reduces dependence on manual support for routine licensing tasks
* Centralizes cloud-linked deployment metadata by activation key
* Supports repeatable rollout across multiple SafeSquid instances
* Makes cloud dependency explicit so teams can design around it where needed
## Portal layout
Confirmed live (2026-09-02, logged-in session, all six tabs inspected):
* **Manage Key** (default landing tab): key details, instance list, Download Key.
* **Manage Categories**: Check Website Category, Modify Category, single-URL search.
* **Manage Certificates**: Generate, then Download, an SSL certificate for the key.
* **Manage VPN**: C-code/activation key against a URL field, Set URL.
* **Manage Signatures**: "Available Signatures for \[C-code]", Add New, a Keywords/Signature table.
* **Manage Account**: subscription details, Conserve Subscription.
A standing **Download Key** action appears on every tab. So do the **Download latest ISO** and **Download latest tarball** links (`downloads.safesquid.com/appliance/safesquid.iso` and `.../binary/safesquid_latest.tar.gz`).
## What the portal is used for
Internal product knowledge confirms the portal is used for:
1. **Activation key distribution**\
Obtain and re-download the activation key used to bind a deployment to SafeSquid licensing workflows.
2. **License management**\
Track subscription and activation status for SafeSquid instances.
3. **Custom categorization and related cloud-managed settings**\
Support organization-specific categorization workflows tied to the activation context.
4. **Certificate-related workflows**\
Support SSL inspection deployment workflows that depend on trusted certificate handling.
5. **Configuration and policy synchronization functions**\
The knowledge base identifies the Self-Service Portal as part of the cloud path. It covers licensing, activation-key distribution, threat-intelligence delivery, and policy or configuration synchronization across deployments.
6. **Backup and restore support**\
The broader architecture model places configuration backup and restore as a peer operational service in the SafeSquid ecosystem.
***
## Prerequisites
**Before you start**
* SafeSquid account (see [Register and get your key](/getting_started/register) if you haven't registered yet)
* Use your business/corporate email for enterprise benefits
* Have your SafeSquid installation details ready (for license activation)
***
## Access the portal
**Direct link:** [https://key.safesquid.com](https://key.safesquid.com)
**From SafeSquid.com:**
1. Visit [https://www.safesquid.com](https://www.safesquid.com)
2. Click **Self-Service Portal** in the top menu
3. Login with your registered email and password
**First-time users:** if you haven't created an account yet, see [Register and get your key](/getting_started/register) for registration steps.
***
## Common tasks
### Download Activation Key
1. **Log in** to the portal — lands on the **Manage Key** tab by default.
2. **Click Download Key**.
3. Save the `activation_key` file (do not rename it).
The Manage Key tab also lists your key's C-Code, current usage counters, Support Validity date,
and instance details (Service ID, version, last update) — plus **Download latest ISO** and
**Download latest tarball** links for the install media itself.
**Use this key for:** [License activation](/getting_started/activate) during SafeSquid setup, or
upload under [Subscription](/configuration/infrastructure_and_access/subscription) when renewing —
status then shows on the [Support](/configuration/infrastructure_and_access/support) page's License
Details panel.
***
### Generate and download your SSL certificate
1. **Log in** to the portal.
2. **Open the Manage Certificates tab** — shows your C-code and Key Name against a **Generate**
action.
3. Click **Generate**, then **Download** the resulting certificate.
Certificate retrieval here must still be paired with endpoint trust deployment and SafeSquid-side
SSL inspection configuration — this step alone doesn't complete an HTTPS Inspection rollout.
**Details:** [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)
***
### Manage confidential-data signatures
1. **Log in** to the portal.
2. **Open the Manage Signatures tab** — shows "Available Signatures for \[C-code]" and an **Add
New** action, with a Keywords/Signature table (empty until you add one).
3. **Add New** opens an "Editing Signature for \[C-code]" form: a **Signature name** field and a
**Keywords** field (one keyword per line, with live regex detection — the form flags whether
what you typed reads as a regex pattern). **Submit** to save.
**Use for:** feeding custom keyword-based signatures into
[DLP](/configuration/real_time_content_security/dlp) OCR scoring on the appliance.
***
### Check or modify a website's category
1. **Log in** to the portal.
2. **Open the Manage Categories tab** — a **Check Website Category** / **Modify Category**
toggle.
3. **Check Website Category** takes a URL (protocol selector plus a `www.example.com`-style text
box) and a **Search** button — looks up how that URL is currently categorized.
4. **Modify Category** instead opens with a **Select Category** field (dropdown/autocomplete over
existing categories, not a URL search) — pick a category to act on.
**Use for:** looking up a site's current category, or changing which category an existing
category-set applies to.
***
### Check subscription status and conserve or renew
1. **Log in** to the portal.
2. **Open the Manage Account tab.**
3. **View:** Active Subscription status, Subscription ID, C-Code, Key Name, Plan (for example
Trial or Commercial), Named Users, No of Instances, and Support Validity date.
4. If you need more time before renewing, use **Conserve Subscription** — see
[Handle expiry](/deployment/manage_subscription_state) for what this does and does not buy you.
A "Renew Subscription" action was not visible on this tab for a Trial-plan account when last
checked (2026-09-02) — only Conserve Subscription showed. Whether Renew appears for a Commercial
plan, or lives somewhere else, is unconfirmed.
***
### Manage VPN client licensing
1. **Log in** to the portal.
2. **Open the Manage VPN tab.**
3. The tab lists your C-code and activation key against a **URL** field (unset by default —
shows "Not Defined") with a **Set URL** action.
**Use for:** licensing SafeSquid's roaming-user VPN web-security clients against this activation
key. This is also where the "Manage VPN settings" topic once flagged as missing from
[Configuration](/configuration/main) actually lives — it isn't a local console feature.
## Verification and validation
After using the portal, verify all of the following:
* the activation key is accepted by the SafeSquid deployment
* the expected license or subscription state appears on the instance
* custom categorization or related cloud-managed changes appear after sync
* SSL-related assets required for inspection workflows are available where expected
## Troubleshooting
| **Issue** | **Likely Cause** | **Fix** |
| - | - | - |
| Cannot login | Wrong credentials or account not activated | Reset password; check email for activation link |
| Activation key download fails | Browser cache or session expired | Clear cache, logout/login, try different browser |
| SSL-related workflow fails | Missing organization details or incomplete certificate workflow | Verify the portal state and then complete the SafeSquid-side SSL steps |
| Custom categories not applying | The instance is not synced to the correct activation context | Recheck the activation key and synchronization path |
| Cloud-linked features do not update | Restricted network path blocks portal or feed communication | Allowlist the required SafeSquid cloud dependencies |
## Related controls / next steps
* [Register and get your key](/getting_started/register) to establish the activation path
* [Activate your license](/getting_started/activate) to bind the deployment to the key
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) for certificate-dependent HTTPS inspection workflows
# Supporting Services
Source: https://docs.safesquid.com/architecture/interface/supporting_services
Supporting Services reference and operational guidance for SafeSquid SWG administrators.
# Set Up the Services SafeSquid Depends On
Supporting services ensure SafeSquid SWG operates reliably, performs well, and maintains accurate time synchronization.
**Critical for production:** These services prevent downtime, improve DNS performance, and ensure authentication works correctly.
## Why You Need These Services
| Service | Purpose | What Happens Without It |
| - | - | - |
| Monit | Process monitoring and auto-restart | SafeSquid crashes stay down until manual restart |
| BIND | Local DNS resolver with caching | Slow DNS lookups, dependency on external resolvers |
| NTP | Time synchronization | SSO fails, TLS certificate errors, log timestamps incorrect |
## Service Guides
### Monit
**Automated monitoring and self-healing** for SafeSquid and dependent processes.
**What it does:**
* Auto-restarts SafeSquid if it crashes
* Monitors port 8080 for responsiveness
* Cleans up temporary files and rotates logs
* Fetches threat intelligence updates
* Triggers housekeeping tasks
**Install and configure:** [Monit Configuration Guide](/architecture/interface/supporting_services_monit)
### BIND
**Local DNS resolver** for fast, reliable domain resolution.
**What it does:**
* Caches DNS responses for faster lookups
* Reduces dependency on external DNS servers
* Improves consistency and auditability
* Enables local DNS overrides for internal domains
**Install and configure:** [BIND Configuration Guide](/architecture/interface/bind)
### NTP
**Time synchronization** critical for authentication and TLS validation.
**What it does:**
* Keeps system time within 5 minutes of Active Directory (required for SSO/Kerberos)
* Ensures accurate TLS certificate validation
* Provides correct timestamps in logs for forensics
* Prevents authentication failures due to clock drift
**Install and configure:** [NTP Configuration Guide](/architecture/interface/ntp)
## Quick Setup Checklist
For a production-ready SafeSquid deployment:
1. **Install all three services:** `# Debian/Ubuntu: sudo apt install -y monit bind9 chrony # RHEL/CentOS: sudo dnf install -y monit bind chrony`
2. **Configure Monit:** Add SafeSquid process check Enable port 8080 monitoring Configure auto-restart
3. **Configure BIND:** Point to root DNS servers Enable recursion for internal networks only Configure local zone overrides
4. **Configure NTP/Chrony:** Point to enterprise NTP servers or domain controllers Verify time synchronization within 5 minutes of AD
5. **Enable all services:** `sudo systemctl enable --now monit sudo systemctl enable --now bind9 # or named sudo systemctl enable --now chronyd`
6. **Verify:** `# Monit: monit summary # BIND: dig @127.0.0.1 example.com # NTP: chronyc tracking`
## Next Steps
1. **Configure each service** using the detailed guides above
2. **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - NTP is critical for TLS validation
3. **[Authentication](/use_cases/authentication/authentication)** - NTP is required for SSO/Kerberos
4. **[Audit & Forensics](/use_cases/audit_and_forensics/audit_forensics)** - Accurate timestamps for compliance
## Next steps
* Use [BIND](/architecture/interface/bind) to operate local DNS services.
* Use [NTP](/architecture/interface/ntp) to keep logs and authentication time-aligned.
# Monit Service Governance
Source: https://docs.safesquid.com/architecture/interface/supporting_services_monit
Automated monitoring and self-healing for SafeSquid SWG processes and host resources
# Supervise SafeSquid Processes With Monit
Monit automatically monitors SafeSquid and restarts it if it crashes or becomes unresponsive. It also performs housekeeping tasks like log rotation and temporary file cleanup.
**Why you need this:** Without Monit, a SafeSquid crash requires manual intervention. In production, this means downtime until someone notices and restarts the service.
## Prerequisites
:::note
**Before You Start**
* Linux host with systemd
* Root or sudo access
* SafeSquid installed and running
* Log storage capacity for Monit logs
:::
## Installation and Configuration
### 1. Install Monit
**Debian/Ubuntu:**
```bash theme={null}
sudo apt update
sudo apt install -y monit
```
**RHEL/Rocky/CentOS:**
```bash theme={null}
sudo dnf install -y monit
```
**Verify installation:**
```bash theme={null}
monit -V
```
Expected result: `This is Monit version 5.34.3` (the number varies by release), followed by the build options.
***
### 2. Enable Monit Service
```bash theme={null}
sudo systemctl enable --now monit
systemctl is-active monit
systemctl is-enabled monit
```
Expected result: `systemctl is-active monit` prints `active` and `systemctl is-enabled monit` prints `enabled`.
***
### 3. Configure Monit HTTP Interface (Local Only)
Edit `/etc/monit/monitrc`:
```bash theme={null}
sudo nano /etc/monit/monitrc
```
Add or uncomment:
```text theme={null}
set httpd port 2812 and
use address localhost
allow localhost
```
**Save and reload:**
```bash theme={null}
sudo monit reload
```
**Verify:**
```bash theme={null}
curl -s http://localhost:2812 | head -n1
```
Expected result: the first line of an HTML page that starts with `` and contains the title `Monit: ` followed by the hostname.
***
### 4. Add SafeSquid Process and Port Checks
Create `/etc/monit/conf.d/safesquid`:
```bash theme={null}
sudo nano /etc/monit/conf.d/safesquid
```
Add:
```text theme={null}
check process safesquid with pidfile /var/run/safesquid/safesquid.pid
start program = "/bin/systemctl start safesquid"
stop program = "/bin/systemctl stop safesquid"
if failed port 8080 protocol http then restart
if 3 restarts within 5 cycles then alert
```
**Explanation:**
* Monitors SafeSquid process via PID file
* Checks port 8080 for HTTP responsiveness
* Auto-restarts if port check fails
* Alerts if SafeSquid restarts 3+ times in 5 cycles (possible persistent issue)
**Reload and verify:**
```bash theme={null}
sudo monit reload
sudo monit status safesquid
```
Expected result: status shows `Running` and `OK`.
***
### 5. Add Housekeeping Checks
**Log Rotation Trigger:**
Create `/etc/monit/conf.d/safesquid-logs`:
```bash theme={null}
sudo nano /etc/monit/conf.d/safesquid-logs
```
Add:
```text theme={null}
check file ss-log-size with path /var/log/safesquid/extended/extended.log
if size > 500 MB then exec "/usr/sbin/logrotate -f /etc/logrotate.d/safesquid"
```
**Temporary Files Cleanup:**
Add to the same file:
```text theme={null}
check directory ss-tmp with path /tmp
if timestamp > 24 hours then exec "/usr/bin/find /tmp -type f -mtime +1 -delete"
```
:::caution
**Cleanup Script Risk**
The temp file cleanup example deletes files older than 1 day in `/tmp`. Adjust the path and age to match your environment to avoid deleting needed files.
:::
**Reload:**
```bash theme={null}
sudo monit reload
sudo monit status
```
***
### 6. Add Update Orchestration (Optional)
If you want Monit to trigger SafeSquid upgrades when an upgrade flag file appears:
Create `/etc/monit/conf.d/safesquid-upgrade`:
```bash theme={null}
sudo nano /etc/monit/conf.d/safesquid-upgrade
```
Add:
```text theme={null}
check file ss-upgrade-flag with path /var/lib/safesquid/upgrade.flag
if changed checksum then exec "/usr/local/bin/safesquid-upgrade"
```
**Note:** You'll need to create the `/usr/local/bin/safesquid-upgrade` script separately.
***
### 7. Reload and Validate All Checks
```bash theme={null}
sudo monit reload
sudo monit summary
sudo monit status
```
**Expected:**
* `monit summary` shows all checks
* `monit status` shows all checks as `Running` and `OK`
***
## Verify Monit is Working
### Test Auto-Restart
**Simulate SafeSquid crash:**
```bash theme={null}
sudo systemctl stop safesquid
```
**Wait 1-2 minutes** (one Monit check cycle), then check:
```bash theme={null}
systemctl status safesquid
```
**Expected:** SafeSquid is running again (Monit restarted it automatically).
**Check Monit logs:**
```bash theme={null}
sudo tail -20 /var/log/monit.log
```
**Expected log entries:**
```text theme={null}
[UTC] info : 'safesquid' process is not running
[UTC] info : 'safesquid' trying to restart
[UTC] info : 'safesquid' process started
```
***
### View Monit Dashboard
**From the SafeSquid server:**
```bash theme={null}
curl http://localhost:2812
```
Or open in a browser on the server (if GUI available): `http://localhost:2812`
**Expected:** Monit dashboard showing SafeSquid status as green/running.
***
## Troubleshooting
| **Issue** | **Likely Cause** | **Fix** |
| - | - | - |
| Monit won't start | Incorrect permissions on `/etc/monit/monitrc` | `sudo chmod 600 /etc/monit/monitrc && sudo monit reload` |
| Checks not loading | Missing `include` directive | Add `include /etc/monit/conf.d/*` to `/etc/monit/monitrc` |
| Port 8080 check fails | SafeSquid on different port | Update `if failed port` to actual port in config |
| Frequent restarts (3+ in 5 cycles) | Resource exhaustion or dependency failure | Check `journalctl -u safesquid` and system resources (CPU, memory, disk) |
| Monit dashboard not accessible | HTTP interface not configured | Verify `set httpd port 2812` in `/etc/monit/monitrc` |
**Still not working?**
1. **Check Monit configuration syntax:**
```bash theme={null}
sudo monit -t
```
Should return: `Control file syntax OK`
2. **Check Monit logs:**
```bash theme={null}
sudo tail -50 /var/log/monit.log
```
3. **Verify SafeSquid PID file location:**
```bash theme={null}
ps aux | grep safesquid
cat /var/run/safesquid/safesquid.pid
```
If PID file doesn't exist, update the Monit check to use process name instead.
***
## Source register
| Topic | Status | Source |
| - | - | - |
| Monit restart / port checks for SafeSquid | **Confirmed** | This guide, `monitrc` examples |
| Threat-intelligence housekeeping mentions | **Draft** | **CTO:** confirm which jobs Monit triggers per product build |
***
## Next Steps
1. **[BIND](/architecture/interface/bind)** - Configure local DNS resolver
2. **[NTP](/architecture/interface/ntp)** - Ensure accurate time synchronization
3. **[Audit & Forensics](/use_cases/audit_and_forensics/audit_forensics)** - Monitor SafeSquid logs and events
# Integrated DNS Security
Source: https://docs.safesquid.com/architecture/overview/integrated_dns_security
Integrated DNS Security in SafeSquid — DNSBL, homograph detection, query accounting, GeoIP-aware controls, and DNS tunnelling risk reduction.
# Block Malicious Domains at DNS Resolution
## Problem statement
DNS is often the first successful step in phishing, malware delivery, command-and-control, and covert exfiltration. If malicious or deceptive resolution succeeds, the organisation pays for the connection attempt. This holds even when a later HTTP policy can still block the session. In tunnelling scenarios, DNS itself becomes the covert channel.
## Client scenario
Use Integrated DNS Security when the organisation needs more than simple name resolution:
* early blocking of known-malicious destinations
* protection against DNS tunnelling behavior
* controls for homograph and look-alike domain risk
* DNS visibility that supports investigation and policy design
* geographic restrictions on resolution targets where required
## Key benefits
* Stops some malicious activity before full web sessions begin
* Reduces wasted TCP and TLS setup for destinations that should never be reached
* Adds DNS-specific context to Layer 7 policy rather than replacing it
* Improves evidence for investigations involving tunnelling, phishing domains, or suspicious resolution patterns
## Prerequisites
Before you rely on DNS controls, define:
* whether SafeSquid is in the active DNS resolution path
* which upstream DNS dependencies are allowed
* whether DNSBL and related lookups are reachable from the deployment
* which internal domains and applications must never be disrupted by DNS policy
## Setup instructions
Integrated DNS Security combines several DNS-aware controls:
### DNSBL service
SafeSquid can query DNSBL services before allowing resolution of suspicious names or destinations. If the queried target is flagged as blacklisted, SafeSquid blocks access before the web session proceeds.
### Homograph detection
Homograph detection is relevant when attackers use look-alike domains that visually resemble trusted brands or business applications.
### DNS query accounting
Query accounting matters for investigations because it helps teams identify unusual volumes, suspicious patterns, and tunnelling-like behavior.
### GeoIP detection
GeoIP-aware DNS controls help when policy requires different treatment based on the destination country or region.
### DNS tunnelling protection
SafeSquid's documented threat model includes DNS tunnelling through CNAME or TXT query abuse for ransomware, remote-access tooling, and data exfiltration. DNS security is important because HTTP-layer controls do not see this path.
## Verification and validation
After configuration, test all of the following:
* a known-malicious or test-blacklisted destination is blocked
* a sanctioned business destination still resolves normally
* homograph or suspicious-resolution rules trigger where expected
* query-accounting logs show the events needed for investigation
Useful evidence includes:
* DNS-related event logs
* query records for the blocked test destination
* comparison of successful and blocked lookups
* proof that internal business domains are unaffected
## Troubleshooting guide
**Symptom:** Legitimate domains stop resolving.\
**Likely cause:** Overbroad DNSBL or policy scope, or upstream DNS dependency failure.\
**Isolation:** Compare blocked domains against the policy intent and verify upstream resolver health.\
**Remediation:** Narrow the rule or restore the upstream DNS path.\
**Retest:** Resolve a sanctioned destination and confirm success.
**Symptom:** Malicious test domains still resolve.\
**Likely cause:** SafeSquid is not in the effective DNS path, or the DNSBL dependency is unreachable.\
**Isolation:** Verify the actual resolver path and test DNSBL reachability.\
**Remediation:** Correct the DNS flow or allowlist the required external dependency.\
**Retest:** Repeat the same blocked-domain test and confirm prevention.
**Symptom:** DNS tunnelling indicators are not visible in logs.\
**Likely cause:** Query accounting or the relevant DNS logging path is not enabled or retained.\
**Isolation:** Review DNS logging configuration and retention behavior.\
**Remediation:** Enable the required DNS evidence path.\
**Retest:** Run a controlled test and confirm the event appears.
## Related controls / next steps
* [DNS Security](/use_cases/dns_security/dns_security) for the configuration guide
* [Access Restriction](/use_cases/access_restriction/access_restriction) for Layer 7 policy aligned to DNS decisions
* [SafeSquid SWG Overview](/architecture/overview/safesquid_swg) for the architecture context
# Configure
Source: https://docs.safesquid.com/architecture/policy_management_console/configure
Configure entry point for SafeSquid SWG policy, authentication, SSL inspection, DLP, DNS security, and operational settings.
# Configure Policy From One Entry Point
Use **Configure** as the controlled change path for SafeSquid policy. Changes here influence web access, inspection depth, identity enforcement, logging, and business availability.
Every production change should have a reason, an expected result, a rollback path, and evidence that proves the result. This protects the organization from silent overblocking, accidental bypass, and audit gaps.
## Common configuration domains
| Domain | Use it to control | Evidence to check |
| - | - | - |
| Access restrictions | Category, application, user, group, and time-based access | Reports and `extended.log` |
| Authentication | Identity-aware policy and SSO behavior | Authentication logs and user-attributed reports |
| SSL inspection | HTTPS visibility and selective decryption | Inspection reports and certificate validation results |
| Malware and content security | File, payload, keyword, and content controls | Security events and SIEM records |
| DNS security | Resolution-time blocking and DNS risk signals | DNS events and related reports |
## Change discipline
1. Back up configuration before high-impact edits.
2. Change one policy objective at a time.
3. Test with a known user, destination, and expected outcome.
4. Review Reports before expanding the scope.
5. Retain the change ticket, report evidence, and rollback note.
## Next steps
* Use [Policy Management Console](/architecture/interface/configuration_portal) for the complete interface guide.
* Use [Reports](/architecture/policy_management_console/reports) to prove the change worked.
* Use [Support](/architecture/policy_management_console/support) to collect evidence before you escalate.
# Policy Management Console
Source: https://docs.safesquid.com/architecture/policy_management_console/main
Navigation hub for SafeSquid SWG reports, configuration, and support workflows in the policy management console.
# Find the Right Management Console Page
The Policy Management Console is the administrator workbench for SafeSquid SWG. Use it to review reports, configure controls, and reach support workflows without separating policy intent from operational evidence.
## Quickstart path
1. [Reports](/architecture/policy_management_console/reports) — review access, security, and operational evidence before and after policy changes.
2. [Configure](/architecture/policy_management_console/configure) — manage web security, authentication, SSL inspection, DLP, and related settings.
3. [Support](/architecture/policy_management_console/support) — collect support evidence and align troubleshooting with the active configuration.
## Next steps
* Use [Reporting Service](/architecture/interface/reporting_service) for the broader evidence model.
* Use [Proxy Service](/architecture/application_ecosystem/proxy_service) to understand what the console controls.
# Reports
Source: https://docs.safesquid.com/architecture/policy_management_console/reports
Reports entry point for SafeSquid SWG policy evidence, forensic investigation, SIEM forwarding, and operational review.
# Review Policy Evidence in Reports
Use **Reports** to prove what SafeSquid allowed, blocked, inspected, bypassed, or forwarded. A policy without reportable evidence cannot support audit, incident response, or executive risk decisions.
The Application Eco-system source identifies SIEM log forwarding over UDP for real-time access, extended, and native logs. Treat Reports as the console entry point for that evidence flow.
## Evidence to review
* access outcomes by user, group, source, destination, and policy
* blocked malware, phishing, category, and application events
* bypass or exception activity
* configuration and privileged-access changes
* SIEM forwarding status for real-time investigation
## Verification
After a policy change, trigger a controlled request and confirm:
1. The expected allow or block decision appears in Reports.
2. The event includes enough identity and destination context for investigation.
3. The same event reaches the SIEM when forwarding is configured.
## Next steps
* Use [Reporting Service](/architecture/interface/reporting_service) for deployment patterns and troubleshooting.
* Use [Configure](/architecture/policy_management_console/configure) to adjust the policy that generated the report.
* Use [Support](/architecture/policy_management_console/support) to collect evidence before you escalate.
# Support
Source: https://docs.safesquid.com/architecture/policy_management_console/support
Support entry point for SafeSquid SWG troubleshooting evidence, configuration context, and escalation readiness.
# Collect Evidence Before You Escalate
Use **Support** when an issue needs structured evidence, not guesswork. Good support data shortens outages and prevents risky emergency changes that bypass security controls.
The Application Eco-system source highlights server files, folders, startup parameters, supporting services, and log forwarding. Those are the first evidence areas to collect before escalation.
## Evidence to collect
* SafeSquid version and activation state
* affected user, source IP, destination, and time window
* relevant Reports entries or SIEM events
* service health for SafeSquid, Monit, BIND, and NTP
* recent configuration changes from `config.log`
* startup parameters and service unit state
## Escalation checks
Before escalating, confirm:
1. The issue is reproducible or bounded to a clear time window.
2. Local logs show the same result users report.
3. Supporting services are healthy.
4. A rollback option exists for recent policy changes.
## Next steps
* Use [Files and Folders](/architecture/files_and_folders/files_and_folders) to locate server-side evidence.
* Use [Supporting Services](/architecture/interface/supporting_services) to validate dependencies.
* Use [Reports](/architecture/policy_management_console/reports) to review policy evidence in reports.
# Caching
Source: https://docs.safesquid.com/configuration/application_setup/accelerators/caching
Control in-memory HTTP caching in SafeSquid: set refresh rules, freshness limits, and object size limits for cached content.
# Control In-Memory Caching in SafeSquid
Open **Configure → Application Setup → Accelerators → Caching**. This section sits under the **Accelerators** menu group alongside [Caching](/configuration/application_setup/accelerators/caching) and [Prefetching](/configuration/application_setup/accelerators/prefetching). They interact, since a prefetched object is only useful if Caching later serves it.
The **Cache** section controls in-memory HTTP caching, refresh policy, and ICP parameters for forwarding.
```mermaid theme={null}
flowchart TB
open[cache_open read request] --> bypassCheck{Connection flagged to bypass cache?}
bypassCheck -->|Yes| noLookup[No cache lookup happens]
bypassCheck -->|No| enabledCheck{Enabled and object not CACHE_INVALID?}
enabledCheck -->|No| close[Close - return NULL]
enabledCheck -->|Yes| violationCheck{Object is CACHE_VIOLATION and Violate RFC is off?}
violationCheck -->|Yes| close
violationCheck -->|No| serve[Serve from memory]
```
## Core mechanics
### Refresh — first match wins
Walk Refresh rows top-down; first enabled row whose profiles match sets min/max age, validate, and cachable flag, then stops. `cachable=FALSE` sets `CACHE_INVALID` unless `CACHE_FORCE`.
**Disk store is hard-disabled.** Disk store selection is inactive — new objects are memory-only regardless of Store row configuration.
### Freshness semantics
What each Refresh age field actually does, once an entry has matched:
* **Minimum age** — guards against serving something that changed very recently: if the origin's Last-Modified is more recent than this many seconds ago, the object is not treated as safe to serve without revalidating.
* **Maximum age** — hard ceiling. SafeSquid expires the object this many seconds after caching regardless of the freshness the origin's own headers promised. `0` disables the ceiling.
* **Revalidate age** — applies only when the origin gave no explicit freshness guidance at all (no `Expires`, no `max-age`): fresh for this many seconds since caching, then must revalidate.
* **Last-Modified time factor** — last-resort heuristic, used only when the origin gave no freshness guidance but did supply a Last-Modified date: the longer ago the object was modified relative to when it was fetched, the longer it is assumed to stay fresh, scaled by this percentage.
### Violate RFC
Objects stored despite `no-cache` / `no-store` get `CACHE_VIOLATION`. When **Violate RFC** is off, reads return NULL (not served). When on, violation objects may be served.
### Object size limits
* **Minimum file size** — an object smaller than this is discarded after the write completes rather than kept.
* **Maximum file size** — an object exceeding this during writing is discarded unless the matching Refresh entry forced caching regardless of size.
`0` disables either check.
### Memory management
When memory used by cached objects exceeds **Memory cache size**, a cleanup pass evicts least-recently-used, currently-unread entries first, targeting Memory cache size minus **Memory free extra**. **Clean interval** is the minimum time between passes so cleanup does not run continuously under sustained pressure.
### Cache bypass
If the connection was flagged elsewhere to bypass the cache, no cache lookup happens at all.
### Manage cached objects
A regular-expression pattern plus "Delete matches" invalidates and removes every cached entry whose key matches, except an entry a client is actively reading at that moment, which is left alone rather than pulled out from under the reader.
## Schema fields
### Global fields
* **Enabled (`enabled`)** — master switch. Off means no cache lookup and no write for any request.
* **Violate RFC (`violate_rfc`)** — see above.
* **Memory cache size (`maxmemsize`)** — accepts `K` / `M` / `G` suffixes.
* **Memory free extra (`memextra`)** — how far below the cache size a cleanup pass frees.
* **Minimum file size (`minsize`)** / **Maximum file size (`maxsize`)** — see Object size limits above.
* **Prefetch window (`prefetchwindow`)** — seconds after a Prefetching-driven fetch during which a second prefetch write for the same URL is rejected.
* **ICP port (`icpport`)** — UDP port for ICP query/reply used by Proxy chain peer selection; `0` leaves ICP unbound.
* **ICP timeout (`icptimeout`)** — milliseconds to wait for a peer's ICP reply. A slow peer is treated as down for that query.
* **Store balance method (`sbalancemethod`)** — FILL SIZE picks the store holding the least data. FILL PERCENT picks the store least full by percentage of its own quota. No effect while disk caching is disabled.
* **journal size (`journalsize`)** — `0` uses a default of 128,000 records.
* **Clean interval (`cleaninterval`)** — `0` uses a default of 30 seconds.
### Store entry fields (inactive — disk caching is disabled)
* **Enabled (`enabled`)**, **Comment (`comment`)**, **Profiles (`profiles`)** — as elsewhere.
* **Path (`path`)** — blank skips the entry.
* **Maximum disk size (`maxdisksize`)** — `0` is treated as unconfigured and skipped in selection.
* **Disk free extra (`diskextra`)** — free space targeted below the quota during cleanup.
* **MD5 integrity check (`md5`)** — verifies each object's content hash on read and invalidates on mismatch when disk caching is active. No effect today.
### Refresh entry fields
* **Cachable (`cachable`)** — off marks new matching objects invalid on arrival.
* **Minimum age (`minage`)**, **Maximum age (`maxage`)**, **Revalidate age (`validate`)**, **Last-Modified time factor (`lmfactor`)** — see Freshness semantics above.
* **Profiles (`profiles`)** — blank matches every connection.
* **Comment (`comment`)** — administrator note.
## Examples
Open **Configure → Application Setup → Accelerators → Caching → Refresh**. Row fields are
Enabled, Comment, Profiles, Cachable, Minimum/Maximum age, Revalidate age, and Last-Modified
time factor.
![SafeSquid console showing Caching Refresh rows including a Do not cache entry, the Edit Policies icon on the first row circled]()
### Uncachable profile on top
**Config:** Refresh row 1 profiles `uncachable`, cachable off; row 2 blank profiles, cachable on.
**Result:** Tagged connections get CACHE\_INVALID on new entries; others use row 2 ages.
### Violate RFC off
**Config:** violaterfc false; stored no-store object.
**Result:** Second client does not receive object from cache — miss to origin.
### Store row present
**Config:** Store enabled with path and quota.
**Result:** select\_store still NULL — memory-only in current builds.
## How to verify
1. Enable CACHE in `LOG_LEVEL`.
2. Repeat URL request; check Detailed logs for hit/miss.
3. Use Manage cached objects to inspect or purge entries.
4) If an object you expect to be cached never shows as a hit, read the Refresh entries top to bottom. A broader entry above the intended one can be winning, exactly as in any other first-match list.
## Next steps
* **[Prefetching](/configuration/application_setup/accelerators/prefetching)** - prefetch linked stylesheets, scripts, and images into the cache while the HTML page is delivered. So the browser's follow-up requests load faster.
# Prefetching
Source: https://docs.safesquid.com/configuration/application_setup/accelerators/prefetching
Prefetch linked stylesheets, scripts, and images into the cache while the HTML page is delivered, so the browser's follow-up requests load faster.
# Speed Up Pages With Prefetching
Open **Configure → Application Setup → Accelerators → Prefetching**. This section sits under the **Accelerators** menu group alongside [Caching](/configuration/application_setup/accelerators/caching) and [Prefetching](/configuration/application_setup/accelerators/prefetching). They interact, since a prefetched object is only useful if Caching later serves it.
The **Prefetch** section configures SafeSquid to proactively download linked content — stylesheets, scripts, images, and similar resources — into cache while the main HTML page is still being delivered to the client. So the browser's own later request for those resources can already be served from cache, improving page load time.
```mermaid theme={null}
flowchart TB
html[HTML response tag scan] --> row{"Row profiles match and tag/attribute/pattern succeed?"}
row -->|No| next[Next row]
next --> row
row -->|Yes| cacheCheck{URL already cached?}
cacheCheck -->|Yes| abort[Abort prefetch]
cacheCheck -->|No| limits{Queue size and host limit allow?}
limits -->|No| reject[Reject - not queued]
limits -->|Yes| queue[Queue URL for background prefetch_thread]
```
## Core mechanics
Async queue, cache pre-check, HTML parser first-match.
* **Asynchronous Queue**: Prefetching is driven by an asynchronous, background worker thread (`prefetch_thread`) that monitors a `PREFETCH_QUEUE`. It does not block the primary client connection.
* **Cache Pre-Validation**: Before initiating a prefetch download, the thread checks if the object exists in the cache. If the object is already cached, the prefetch is aborted to save bandwidth.
* **Request Spoofing**: The background thread creates a synthetic, unattached HTTP connection, forces it through the routing pipeline, and uses a hardcoded User-Agent to request the file from the origin.
### Global fields
* **Enabled (enabled)**: When off, setup\_callbacks does not register HTML parsers — no automatic prefetch.
* **Threads (threads)**: Configured worker count for prefetch queue processing. This value is not applied in the current build.
* **Queue size (queuesize)**: Maximum URLs waiting in the prefetch queue; full queue rejects new URLs. Already-cached URLs are not queued. Rejected matches are not retried automatically. A later scan of that page, or another page linking the same resource, can queue it if there's room by then.
* **Host limit (hostlimit)**: Maximum queued prefetches per host name (0 disables per-host cap). Duplicate URLs are never queued twice.
### Prefetch rule fields
* **Profiles** — Limit the rule to connections with matching Access Profile tags. A `!`-prefixed value applies the entry when that profile is absent instead of present. Blank matches all.
* **Tag name** — HTML element to scan (case-insensitive), for example `a`, `img`, `link`. Blank skips the row.
* **Tag attribute** — Attribute holding the URL (for example `href` or `src`).
* **Attribute pattern** — POSIX regex on the attribute value after tag/attribute match. Blank accepts any non-empty value. On match, the URL is resolved and queued unless cached or queue full.
* **Maximum file size** — Skip prefetch when response Content-Length exceeds this size. `0` = no cap.
* **Recursion level** — How many levels prefetched HTML is analyzed for further links. Note: setting `0` follows links indefinitely per field help. The opposite of what the number suggests, since it removes the limit rather than capping at zero levels. Use `0` deliberately, and only if you intend genuinely open-ended recursive prefetching.
### Processing order
1. Enable Prefetching and Caching.
2. During HTML responses, enabled Prefetch rows are checked top to bottom.
3. The first row whose profiles match and whose tag/attribute/pattern succeeds wins for that element. Rows below it are not tested against that same element, though they remain available for other elements later in the same page.
4. Matched URLs enter the queue subject to queue size, host limit, and cache state.
5. Caching **Prefetch window** limits duplicate prefetch writes for the same URL within N seconds.
Some prefetch hooks and the **Prefetch now** CGI handler require `ENABLE_PREFETCH` at build time. If manual prefetch fails, confirm your build includes prefetch support.
## Examples
The **Prefetch** rule-row list ships empty by default — no live example available for a rule
row. **Prefetch now** is populated and matches Example 3 below.
Open **Configure → Application Setup → Accelerators → Prefetch → Prefetch now**.
![SafeSquid console showing the Prefetch now URL field for manually queuing a page]()
### 1 — Prefetch linked CSS and scripts
* Row 1: Tag `link`, attribute `href`, pattern `\.css$`
* Row 2: Tag `script`, attribute `src`, pattern blank
**Result:** on HTML pages, stylesheets matching `.css` and all script `src` URLs are queued for early fetch when row 1 or 2 matches first for that element scan order.
### 2 — Staff-only prefetch
* Prefetch row Profiles: `STAFF`
* Access Profiles adds `STAFF` for internal users only
**Result:** only staff connections trigger automatic prefetch; other users parse HTML without prefetch queue activity from that row.
### 3 — Manual warm-up of a portal page
* **Prefetch now**: enter `https://intranet.example.com/`
**Result:** when the handler is enabled, the URL is queued and fetched into cache so the next user request may hit cache immediately.
## How to verify
1. Enable CACHE in `LOG_LEVEL`; look for cache writes with prefetch-related flags.
2. Load an HTML page twice — second load should show cache hits for prefetched assets when Caching and rules allow.
3. Use the Caching tab above to search for prefetched URLs among Manage cached objects.
4. Watch queue rejection if Queue size or Host limit is exceeded (reduce rules or raise limits).
5. Confirm Caching is enabled and not excluding the relevant profiles — Prefetching only queues the fetch, Caching decides whether the result is kept.
## Next steps
* **[Caching](/configuration/application_setup/accelerators/caching)** - control in-memory HTTP caching in SafeSquid: set refresh rules, freshness limits, and object size limits for cached content.
# Access restrictions
Source: https://docs.safesquid.com/configuration/application_setup/access_restrictions
Define who can connect through SafeSquid, whether they must authenticate, and which proxy features they get, using ordered first-match rules.
# Control Who Connects Through Access Restrictions
The **Access** section defines the primary security perimeter: who may connect, whether they authenticate, which proxy features they may use, and which User-Groups and bypass flags attach to the connection.
Configure authentication mechanisms in [Authentication](/configuration/start_here/authentication). LDAP directory setup is in [Integrate LDAP](/configuration/application_setup/integrate_ldap). Content allow/deny is in [Access Profiles](/configuration/restriction_policies/access_profiles).
## Core mechanics
**Access restrictions is not cumulative — it is first-match-wins, per list.** Access Profiles evaluates every enabled entry top to bottom. A later entry can add to or override an earlier one. Access restrictions does not: within a list, the first enabled entry whose fields all match wins the pass. Every entry after it in that same list is skipped for that pass. A broad entry with no restriction (for example, a catch-all Allow meant for "everyone who authenticates") sitting above a narrower entry makes the narrow entry unreachable. It never fires, never logs as matched, and nothing in the Web UI flags the conflict. The only way to catch it is to read the list top to bottom, in order, before relying on it.
### Default policy and list order
With **Default Access Policy = Deny** (recommended):
1. Walk the **Allow** list top-down; first enabled row whose gates pass wins for that pass.
2. If an Allow row matched, walk the **Deny** list; a Deny match revokes access.
3. If no Allow row matched, access is denied.
With Default Allow, Deny is walked first, then Allow. Within one list, **first match wins** — lower rows are not evaluated for that pass.
```mermaid theme={null}
flowchart TB
conn[New connection] --> policy{Default Access Policy?}
policy -->|Allow| inverted["List order inverts: walk Deny list first, then Allow - same first-match-wins mechanics per list"]
policy -->|Deny - recommended| walkAllow[Walk Allow list top-down]
walkAllow --> gate["Row gates: Profiles, Interface, IP, LDAP Profiles - any failure skips to next row"]
gate --> firstMatch{First enabled row where gates pass?}
firstMatch -->|Match found - lower rows not evaluated| allowMatched[Allow row matched]
firstMatch -->|No match| denied[Access denied]
allowMatched --> walkDeny[Walk Deny list]
walkDeny --> denyMatch{Deny row matches?}
denyMatch -->|Yes| revoke[Access revoked]
denyMatch -->|No| grant["Apply access rights, groups, bypass, concurrency"]
```
### Inner gate order
For each enabled row: **Profiles** → **Interface** → **IP** → **LDAP Profiles**. Any failure skips to the next row.
### Client IP and X-Forwarded-For
When `X-Forwarded-For` is present, it replaces the TCP client IP for `ip` matching.
**Spoofing risk:** a client sending `X-Forwarded-For: 127.0.0.1` can match localhost IP rows and receive CONFIG (Web UI) access. Expose the proxy only on trusted networks.
### LDAP Profiles need identity first
An entry that sets only **LDAP Profiles** cannot match on the first, identity-less request — SafeSquid has no directory group list to test yet — and by itself will not trigger a login prompt. LDAP Profiles only has anything to test once identity is already known, from a prior Kerberos/SSO login, a completed System authentication challenge, or an IP-to-user map.
### Two-pass authentication
* **First pass (no credentials)** — If gates pass and `pamauth=TRUE` or User name is set, the row matches and issues a 407/401 challenge. If `pamauth=FALSE` and User name is blank, the row matches immediately — unauthenticated access.
* **Second pass (credentials present)** — SafeSquid populates the connection's LDAP distinguished name with group strings (commas stored as spaces). LDAP Profiles rows can match; PAM validation runs during the access check.
- **If the first list produces no match at all** — not even a credential challenge — the second list is skipped entirely and Default Access Policy decides the outcome directly.
### User-Groups assembly on match
On match, SafeSquid rebuilds the connection's User-Groups in this order: the entry's own **Add to User-Groups** values, then every LDAP group the signed-in user belongs to, then the user's own directory identity. **This assembled set — not just the entry's Add to User-Groups field — is what every later section's User-Groups matching actually tests** (Access Profiles, DLP, and similar).
### Kerberos / SSO (`ntlm_authentication`)
UI label **Kerberos / SSO**; internal field `ntlm_authentication`. When TRUE, SafeSquid offers **Negotiate** (GSSAPI/Kerberos). When FALSE, Negotiate is not advertised. Requires `HTTP.keytab` for SSO to succeed. See [Authentication](/configuration/start_here/authentication).
### DLP bypass
Requires both the **Allow bypassing** access right (`BYPASS`) and the **DLP** bypass checkbox. Either alone leaves DLP active.
### If nothing matches either list
When neither list produces a match, the connection is denied outright: it receives a block page and the connection is closed. If a match still needed credentials that never arrived, the client instead receives an authentication challenge and can retry.
## Recommended entry ordering
1. IP/interface no-auth rows (specific addresses first)
2. Profile-bypass rows (e.g. BYPASS AUTHENTICATION) — before auth rows
3. LDAP Profiles — before PAM regex (group beats username pattern)
4. PAM regex and entry-credential rows
5. Profile-gated showcase rows (each has a `profiles` constraint)
6. PAM catch-all — last Allow row
7. Deny exceptions — paired with an Allow range to demonstrate revoke
Open **Configure → Application Setup → Access restrictions → Allow list**. Row fields are Enabled,
Comment, Trace Entry, Profiles or IP Address, **PAM authentication** (labeled differently than
System authentication below — same underlying gate), Access, and Add to User-Groups.
![SafeSquid console showing Access restrictions Allow list rows with the bypass-authentication and tunnelled-UI-access entries, the Edit Policies icon on the first row circled]()
## Global fields
* **Default Access Policy** — Deny recommended. Controls default when no row matches and which list is walked first.
* **Kerberos / SSO** — Enables Negotiate when keytab is present.
## Rule fields
All configured criteria on a row must match. Blank means any.
* **IP Address** — Single IP, comma list, or hyphen range. CIDR not supported. Uses XFF when present.
* **Interface** — Listen socket IP:port of the accept.
* **System authentication** — Cache → PAM → LDAP bind; User name is a regex filter; Password ignored.
* **User name / Password** — With System auth off: exact case-sensitive match. Non-empty User name still triggers challenge on first pass.
* **LDAP Profiles** — Exact match against the connection's LDAP distinguished name; write DNs with spaces not commas.
* **Access** — CONFIG, PROXY, HTTP, TRANSPARENT, CONNECT, BYPASS — independent rights.
* **MAX Concurrent Connections** — Keyed `username@client-ip`; 0 = no cap.
- **Profiles (`add_profiles`)** — limits the entry to connections that already carry a listed Access Profile. Blank = ignored.
- **Negation** — `LDAP Profiles` and `Profiles` both accept `!value` to negate a match.
- **Add to User-Groups (`add_user_groups`)** — group names added to the connection's User-Groups on match. LDAP groups and the user's directory identity are added automatically alongside these, regardless of this field — see "User-Groups assembly on match" above.
- **Bypass (`bypass`)** — modules skipped on match: Header filtering, Redirect, Cookie filtering, Rewrite, External, Forward, Text analyzer/Keyword filtering, DNSBL, Limits, Antivirus, ICAP, DLP.
- **Interface username / Interface password (`ifusername` / `ifpassword`)** — optional second Web UI login, required together. Only relevant when this entry also grants the **Web interface** Access right.
- **Comment (`comment`)** — written to native security logs when this entry matches.
- **Trace Entry (`profile_tracing`)** — logs each User-Group this entry adds; turn off after testing.
- **MAX Concurrent Connections — the uncapped case** — `0` removes the connection ceiling. But connections are still counted against the entry, not skipped from counting.
## Examples
### The bug this file exists to prevent
**Config:** Allow list, in this order — (1) a general Allow entry with no IP, no Interface, no LDAP Profiles, no User name, matching any authenticated user; (2) an Accountants entry with LDAP Profiles set to the Accountants directory group, granting `Add to User-Groups: ACCOUNTANTS`.
**Result:** every accountant matches entry (1) first, because it is unconditional and sits above entry (2). Entry (2) is unreachable — never logged as matched, never adds the `ACCOUNTANTS` User-Group — and nothing anywhere flags this. Reorder so the Accountants entry sits above the general entry.
### Localhost Web UI and proxy
**Config:** IP `127.0.0.1`, Access CONFIG,PROXY,HTTP,TRANSPARENT,CONNECT, pamauth off, no username.
**Result:** Immediate match; User-Group LOCALHOST. Beware XFF spoofing on untrusted networks.
### Hyphen IP range without auth
**Config:** IP `203.0.113.0-203.0.113.255` (TEST-NET-3), pamauth off.
**Result:** Any address in range matches first pass; no challenge.
### LDAP group after login
**Config:** ldap\_profiles with Sales group DN, pamauth off, above PAM catch-all.
**Result:** First pass: ldap gate fails (empty dn), challenge from PAM row. Second pass: group match grants LDAP\_SALES; password not rechecked unless pamauth=TRUE.
### DLP bypass
**Config:** Access BYPASS + bypass DLP checkbox + profiles constraint.
**Result:** DLP skipped. Missing either condition — DLP still runs.
### Deny exception
**Config:** Allow range 203.0.113.0–255 + Deny 203.0.113.50; policy Deny.
**Result:** Allow matches, then Deny revokes. Deny row rights/groups not applied.
## How to verify
1. Test from a known client IP without spoofed XFF (unless testing that path).
2. **Reports → Detailed logs** — username, IP, access filter.
3. Enable **Trace Entry** on one row; check native logs.
4. SECURITY log family for authentication outcomes.
5) If Default Access Policy is Deny and an Allow-listed client is unexpectedly blocked, check the Deny list for a second-pass override before suspecting the Allow entry.
## Next steps
* **[Authentication](/configuration/start_here/authentication)** - choose how SafeSquid identifies users, including Kerberos SSO and system authentication, so Access Profiles and logs can name them.
* **[Integrate LDAP](/configuration/application_setup/integrate_ldap)** - sync directory users and groups into SafeSquid so Access Profiles and sign-in can apply policy by group membership, not IP address alone.
* **[Access Profiles](/configuration/restriction_policies/access_profiles)** - decide what each user can fetch by combining time, request type, response type, category, and group labels into ordered allow and deny rules.
# FTP browsing
Source: https://docs.safesquid.com/configuration/application_setup/ftp_browsing
Configure the global FTP-over-HTTP gateway: anonymous credentials, passive mode, and directory sort defaults.
# Configure FTP Browsing Defaults
The **FTP** section configures global FTP-over-HTTP gateway behaviour. There is no policy list — only global fields.
## Core mechanics
### Anonymous credentials
When the client sends no username, SafeSquid substitutes **Username** and **Password** from this section before USER/PASS. This is login to the remote FTP server, not proxy authentication — Access restrictions decide whether the client may use the proxy for FTP at all, before this section applies. See [Architecture and request pipeline](/configuration/start_here/architecture).
When the request's User-Agent header contains "Firefox", SafeSquid re-encodes any `+` character in the username or password to `%2B` before decoding it — without this, a `+` would be misread as a space.
### Passive mode
When on, PASV data connections; when off, PORT/active with local bind on the same interface as the control connection.
### Sort defaults
Directory HTML listings use **Sort field** and **Sort order** when the client does not pass CGI sort parameters.
### Caching anonymous FTP transfers
**Caching checks the literal word `anonymous`, not your configured anonymous-login username.** FTP file caching only happens when directory information is available *and* the request's username is exactly the literal word `anonymous` (case-insensitive). This check is against the fixed word itself, not against whatever value is set in **Username for anonymous login**. Rename that field to anything else (for example `ftpguest`) and anonymous logins keep working exactly as before. But files fetched anonymously silently stop being cached. Authenticated FTP transfers are never cached through this path, regardless of username.
```mermaid theme={null}
flowchart TB
req["Client requests ftp:// URL over HTTP"] --> userCheck{Client sent a username?}
userCheck -->|No| subst[Substitute configured Username and Password before login]
userCheck -->|Yes| login[Log in to remote FTP server with client credentials]
subst --> login
login --> mode{Passive mode?}
mode -->|On| pasv[PASV data connection]
mode -->|Off| port[PORT active - local bind on control connection interface]
pasv --> op[LIST directory or RETR file]
port --> op
op --> cacheCheck{Username exactly anonymous and directory info available?}
cacheCheck -->|Yes| cache[Cache the transfer]
cacheCheck -->|No| noCache[Not cached - configured anonymous-login Username is not tested here]
```
## Global fields
* **Passive mode (`passive`)** — PASV vs PORT data transfer.
* **Timeout (`timeout`)** — Control read timeout; 0 uses OS TCP keepalive interval.
* **Username / Password (`anonlogin` / `anonpass`)** — Anonymous defaults when client omits credentials. The password is conventionally an email-address-shaped string, the long-standing convention for anonymous FTP.
* **Sort order / Sort field (`sortorder` / `sortfield`)** — Default directory listing order (name, size, date).
Use passive mode when SafeSquid itself sits behind a firewall or NAT that would block an unsolicited inbound data connection. It keeps both the control and data channels outbound from SafeSquid.
## Examples
Open **Configure → Application Setup → FTP browsing**. A single Global screen holds Passive mode,
Timeout, Username/Password for anonymous login, and Sort order/field — no row list.
![SafeSquid console showing FTP browsing global fields with Passive mode and anonymous login defaults, the Edit Policy icon circled]()
### Anonymous behind firewall
**Config:** passive on, anonlogin anonymous.
**Result:** PASV data channel; listing and download without client credentials.
### Access denies FTP
**Config:** FTP globals normal; Access lacks proxy/FTP for client.
**Result:** Denied before FTP settings apply.
### Changing the anonymous username breaks caching, not login
**Config:** Username for anonymous login changed from `anonymous` to `ftpguest`.
**Result:** clients with no credentials of their own still log in successfully (now as `ftpguest`). But files fetched this way are no longer cached. The caching check looks for the literal username `anonymous`, which no longer appears in these requests.
### A large directory sorted by size
**Config:** Sort field `SIZE`; Sort order descending.
**Result:** a directory listing without client-supplied sort parameters shows the largest files first.
## How to verify
1. Open `ftp://` URL through proxy in browser.
2. Toggle passive if LIST works but RETR fails.
3. Check Detailed logs and REQUEST native logs.
4) To confirm anonymous caching is active, fetch the same anonymous FTP file twice and check whether the second is served from cache — and confirm **Username for anonymous login** is still `anonymous` if it unexpectedly is not.
## Next steps
* **[Architecture and request pipeline](/configuration/start_here/architecture)** - follow a request through SafeSquid from admission and identity, through protocol fork and enforcement, to fetch and response delivery.
# Integrate LDAP
Source: https://docs.safesquid.com/configuration/application_setup/integrate_ldap
Sync directory users and groups into SafeSquid so Access Profiles and sign-in can apply policy by group membership, not IP address alone.
# Integrate LDAP to Apply Policy by Group
The **LDAP** section syncs directory users and groups into memory for Access LDAP Profiles and LDAP bind authentication.
LDAP integration is the foundation for regulating web access by role or group membership rather than by IP address alone. The cached identity it builds feeds Access restrictions' **LDAP Profiles**, LDAP sign-in. Every downstream policy that must tell one user apart from another. The sync runs on a timer, and whenever configuration changes.
## Core mechanics
### Full sync — all valid servers
Each enabled valid **LDAP servers** row binds and runs a paged cache load in one update cycle. Maps accumulate entries from every successful server.
### Default @domain
First valid row's **Ldap Domain** becomes the default domain. Logins without `@` get `@domain` appended and uppercased for map keys.
If the user signs in with an explicit domain (for example `jane@other.com`), that domain is used for the lookup instead of the default suffix, matched against whichever server entry's **Ldap Domain** corresponds to it.
If the computed `LOGIN@DOMAIN` key is not found in the cache, SafeSquid makes an on-demand single-user lookup against the directory before giving up. This is what covers a user created after the last full sync.
### Auth — first matching server
Authentication walks servers until the domain and **Ldap Basedn** match; stops on bind success or invalid credentials.
### ldapgroupfilter
Stored in config but not used in search code — groups come from **Group Identifier** attributes and DN OUs. The group list is built from two sources combined and de-duplicated: the values of the **Group Identifier** attributes (commas within a value are replaced with spaces), plus the OU components of the user's own DN (same comma replacement). That combined list is what Access restrictions' **LDAP Profiles** field performs an exact-string match against.
```mermaid theme={null}
flowchart TB
cycle[Timer or config refresh triggers update cycle] --> walkServers[For each enabled valid LDAP servers row]
walkServers --> bind[Bind and run paged cache search]
bind --> accumulate[Accumulate user and group entries into maps]
accumulate --> domain["The first valid row's Ldap Domain becomes the default domain"]
domain --> keyCheck{"Login already includes a domain?"}
keyCheck -->|No| append[Append the default domain]
keyCheck -->|Yes| upper[Uppercase for the map key]
append --> upper
upper --> lookup["LOGIN@DOMAIN map key used for LDAP Profiles and Access"]
```
## What makes an entry valid
An **LDAP servers** entry participates in sync and sign-in only once it has a non-zero **Ldap Port**, an **Ldap Basedn**, an **Ldap Domain**, and at least one **Login Attributes** value. If **Host Name** is set it must exactly equal this appliance's own hostname, otherwise the entry is invalid on this node — which is how you pin one directory entry to one proxy in a multi-node deployment. An invalid entry is skipped silently: it never appears under LDAP Entries and plays no part in sign-in.
## Schema Fields
### Global
* **Enabled (`enabled`)** — master switch for the whole section.
### LDAP servers entry
* **Enabled (`enabled`)** — this entry is skipped for sync and sign-in when off.
* **Comment (`comment`)** — administrator note.
* **Host Name (`ldaphost`)** — if set, must exactly equal this appliance's own hostname, or the entry is invalid on this node.
* **Ldap FQDN\IP (`ldapip`)** — an FQDN, or the `FQDN\IP` form (backslash then a literal IP) when a Kerberos/keytab script specifically needs the IP form.
* **Ldap Port (`ldapport`)** — TCP port for the directory connection. Must be greater than `0` for the entry to be valid.
* **Use SSL (`ldapssl`)** — connect over LDAPS (encrypted) instead of plain LDAP.
Without a CA certificate configured for LDAP, an LDAPS connection still proceeds **without verifying the directory server's certificate**. Supply a CA certificate for a properly verified connection.
* **Ldap Bind Method (`ldapmethod`)** — Simple, NTLM, or Negotiate. Where NTLM/Negotiate are unavailable on the platform or build, the bind falls back to Simple regardless of the selection.
* **Query Record Limit (`ldaplimit`)** — page size for the bulk sync and the upper bound for any single search. A single-user lookup temporarily uses a limit of `1` regardless of this setting.
* **Ldap User Filter (`ldapuserfilter`)** — an LDAP filter fragment combined with a per-attribute test built from Login Attributes, used for both the full sync and single-user lookups.
* **Ldap Group Filter (`ldapgroupfilter`)** — stored in configuration but not used by the current search logic that builds group lists. Group membership comes from Group Identifier attributes and DN-derived OU components instead.
* **Ldap Username (`ldapusername`)** / **Ldap Password (`ldappassword`)** — the service account used to bind for directory search. May be blank on a directory allowing anonymous bind. Store the password with the Encrypt Password utility, never as plain text. An entry whose stored password fails to decrypt is treated as invalid.
* **Ldap Basedn (`ldapbasedn`)** — the base DN to search under; the entire subtree beneath it is searched.
* **Ldap Domain (`ldapdomain`)** — the domain suffix appended to logins with no `@`. The key used to route a sign-in to the right server when more than one directory is configured.
* **Login Attributes (`ldaploginattr`)** — one or more directory attributes used as login identifiers (for example `sAMAccountName`, `UserPrincipalName`, or `uid`).
* **Group Identifier (`ldapgroupid`)** — one or more attributes read from each user entry and merged into that user's cached group list (for example `memberOf` or `member`).
## Examples
Open **Configure → Application Setup → Integrate LDAP → LDAP servers**. Each row carries the
connection fields plus **Ldap Domain**, **Ldap Basedn**, **Login Attributes**, and **Group
Identifier** shown here (the Ldap Password row is redacted from this capture). **Ldap Basedn**
is a distinct field from **Ldap Domain** — enter it in LDAP format, for example `dc=domain,dc=local`
or, for a domain like `test1.testdomain1.com`, `dc=testdomain1,dc=com`.
![SafeSquid console showing an LDAP servers row with Login Attributes and Group Identifier fields, Group Identifier circled]()
### Active Directory
**Config:** domain corp.example.com, login attributes sAMAccountName, group identifier memberOf.
**Result:** Cache keys like [JDOE@CORP.EXAMPLE.COM](mailto:JDOE@CORP.EXAMPLE.COM); group strings for LDAP Profiles after sync.
### Bare username
**Config:** default domain corp.example.com; user logs in jane.
**Result:** Lookup [JANE@CORP.EXAMPLE.COM](mailto:JANE@CORP.EXAMPLE.COM) in maps.
### Granting access by cached group membership
**Config:** an Access restrictions Allow-list entry sets LDAP Profiles to the exact group string from the user's `memberOf` values (spaces, not commas).
**Result:** the entry matches on the pass that re-checks Access restrictions with credentials present, once the user's identity is known from a prior authentication or from Kerberos/SSO.
### Section off
**Config:** global Enabled off.
**Result:** Maps cleared, every server connection closed, and auth returns incomplete. LDAP sign-in and LDAP Profiles matching behave as though no directory were configured, until the section is re-enabled **and a sync completes**.
## How to verify
1. Open **LDAP Entries** after cache thread runs. Its **Refresh** option forces a re-sync instead of waiting for the next cycle. The page waits a few seconds, then reloads.
2. Enable LDAP + SECURITY logs.
3. Sign in; confirm LDAP profile application in Detailed logs.
4. Cross-check the group strings offered in Access restrictions' LDAP Profiles picker against LDAP Entries. They must match exactly, spaces rather than commas.
5. If a server never appears to sync, re-check Ldap Basedn, Ldap Domain, and Login Attributes — any one missing makes the entry silently invalid — and, on a multi-node deployment, that Host Name matches this appliance.
## Next steps
* **[Authentication](/configuration/start_here/authentication)** - choose how SafeSquid identifies users, including Kerberos SSO and system authentication, so Access Profiles and logs can name them.
* **[Access Profiles](/configuration/restriction_policies/access_profiles)** - decide what each user can fetch by combining time, request type, response type, category, and group labels into ordered allow and deny rules.
# Network settings
Source: https://docs.safesquid.com/configuration/application_setup/network_settings_and_listeners
Set the sockets clients connect to and the source IP SafeSquid uses for outbound connections to origin servers.
# Set Network Settings for Clients and Outbound Traffic
The **Network** section defines client listen sockets and outbound source IP selection for origin connections.
The console splits this section into two tabs, and they are independent of each other: **Listen**
binds the sockets clients connect to, **Interface** picks the source IP SafeSquid uses when it
connects onward.
These are infrastructure-plumbing settings, not a security control in themselves: Listen decides
where clients may knock, and Interface decides which door SafeSquid walks out of. *Who* is
allowed in, and what they may do, belongs to
[Access restrictions](/configuration/application_setup/access_restrictions), which references the
Listen sockets defined here through its own **Interface** match field. Nothing can reach SafeSquid
at all unless a Listen entry is bound.
## Core mechanics
### Listen — startup bind
Every enabled Listen row with `port != -1` binds at startup. If no enabled row matches startup.ini `LISTEN_IP` and `LISTEN_PORT`, an additional fallback bind runs on those defaults. This fallback is extra, it does not replace or disable any entry you configured. It only fires when nothing in your list already covers that address. Restart required after Listen changes.
## Listen fields
Open **Configure → Application Setup → Network settings → Listen**.
![SafeSquid console showing Network settings Listen rows including an SSL_TRANSPARENT binding, the Edit Policies icon on the first row circled]()
* **IP / Port** — Bind address and client port. Blank IP binds every address dual-stack where IPv6 is available; `0.0.0.0` binds every IPv4 address; `::` binds every IPv6 address. A specific address binds only that one.
* **Bindings** — `SSL_TRANSPARENT`, `CAPTIVE_PORTAL` implemented; `SSL_AUTHENTICATION` / `SSL_BRIDGE` have no effect.
## Examples
### Single proxy port
**Config:** Listen enabled, blank IP, port 8080.
**Result:** All interfaces accept on 8080 after restart; Access controls who may connect.
### Separate management listener
**Config:** entry A Enabled, IP `0.0.0.0`, Port `8080` for regular users; entry B Enabled, IP
`127.0.0.1`, Port `8080` for administration.
**Result:** after a restart both sockets are open, and an Access restrictions entry matching
Interface `127.0.0.1:8080` can grant the Web interface right on the loopback listener while
entries matching `0.0.0.0:8080` grant proxy rights — separating administrative access from
ordinary browsing by which socket the connection arrived on.
## How to verify
1. Restart after Listen changes.
2. `curl -x http://APPLIANCE:8080 http://example.com/`
3. Enable NETWORK logs; confirm the bind lines.
4. Match listen socket in Access **Interface** for CONFIG vs PROXY tests.
## Core mechanics
### Interface — first match wins
Outbound walks Interface rows top-down: skip disabled; skip empty Source IP after load. Skip when destination is in **Excluded Destination IPs**; require a profile match (connection profiles plus hostname/service tags). The first match picks a source IP from the row's list, keyed by client ID. If no row survives all the gates, SafeSquid sets no source IP at all and the connection uses whatever the operating system's own routing would normally choose.
### Source IP on host only
Non-local Source IPs are dropped silently at load. If all IPs are dropped, the row is skipped at runtime.
```mermaid theme={null}
flowchart TB
outbound[Outbound TCP connect] --> walk[Walk Interface list top-down]
walk --> gate{"Row disabled, empty Source IP, destination in Excluded Destination IPs, or profile mismatch?"}
gate -->|Skip| more{More rows?}
gate -->|Pass| bind["Bind source IP from row's list, keyed by client ID - stop"]
more -->|Yes| walk
more -->|No| noBind[No Interface row matched - no bind from this section]
```
## Interface fields
Open **Configure → Application Setup → Network settings → Interface**. The live row's outbound
address field is labeled **IP**, not Source IP as referenced below.
![SafeSquid console showing a Network settings Interface row with the ALTERNATE OUTBOUND IP profile, the Edit Policies icon circled]()
* **Profiles** — Blank matches all. A value prefixed with `!` applies the entry when that value is absent instead of present. Typical tag: `ALTERNATE OUTBOUND IP`.
* **Excluded Destination IPs** — Hyphen ranges; destination in list skips row (CIDR not supported). This field excludes destinations, it does not restrict the entry to them. Blank excludes nothing.
* **Source IP** — Comma-separated local addresses; only host IPs kept; rotated by client id.
## Examples
### Excluded destination
**Config:** Source IP 10.0.0.5, dest\_ips 10.0.0.0-10.255.255.255.
**Result:** Outbound to 10.x skips row; public destinations may match and bind 10.0.0.5.
### Source IP not on host
**Config:** Source IP 198.51.100.99 not assigned to appliance.
**Result:** IP ignored at load; row skipped — no outbound bind from this row.
### Send specific traffic out a second IP
**Config:** an Interface entry with Profiles `ALTERNATE OUTBOUND IP` and Source IP
`203.0.113.5` (an address actually configured on the appliance), with an Access Profiles entry
elsewhere adding that same profile.
**Result:** matching connections bind outbound to `203.0.113.5`; everything else falls through
to a lower entry or to OS routing.
## How to verify
1. Enable NETWORK logs; confirm the `interface_select` lines.
2. Confirm the chosen source IP on the origin side, not only in the log.
## Next steps
* **[Access restrictions](/configuration/application_setup/access_restrictions)** - define who can connect through SafeSquid, whether they must authenticate, and which proxy features they get, using ordered first-match rules.
# Proxy chain
Source: https://docs.safesquid.com/configuration/application_setup/proxy_chain
Route requests through upstream proxies, siblings, or CARP clusters, and understand how SafeSquid picks the next hop.
# Route Requests Through a Proxy Chain
```mermaid theme={null}
flowchart TB
req[Request] --> disabledCheck{Forwarding disabled or Access Bypass Forward set?}
disabledCheck -->|Yes| direct[Send direct]
disabledCheck -->|No| walk[Walk Forwarding proxies top to bottom]
walk --> row{"Enabled row matches, non-self Proxy?"}
row -->|Blank Proxy on match| stop[Stop collection immediately]
row -->|Non-blank Proxy| add[Add to candidate list]
add --> more{More rows?}
more -->|Yes| walk
more -->|No| connectCheck{CONNECT request?}
stop --> connectCheck
connectCheck -->|Yes| skipSel["Skip ICP/CARP selection logic"]
connectCheck -->|No| select["Select peer: CARP hash, ICP priority, or random tie-break"]
skipSel --> send["Send through selected peer, or direct if no candidate remains"]
select --> send
```
## What does this section do?
The `Forward` section configures upstream proxy routing, enabling SafeSquid to chain requests to parents, siblings, or Cache Array Routing Protocol (CARP) clusters.
It is infrastructure routing, not a security control. It decides where a request goes next on its way out, not whether it is allowed.
## Core Mechanics (C++ Source Validation)
CARP hash, blank Proxy stop, ICP peer selection.
* **CARP Hashing**: When routing requests through an array of proxies, the routing engine performs a deterministic 32-bit bitwise rotation hash combining the requested URL and the peer’s hostname. The peer generating the highest hash score receives the request.
* **Self-Resolution (Loop Prevention)**: If SafeSquid calculates that its *own* hostname generates the highest CARP hash (`op >= hp`), it drops the forwarding requirement and resolves the request directly.
* **Cache Coordination**: When a request is forwarded to another CARP array member, SafeSquid sets `CONNECTION_NOCACHE`. This ensures the object is only cached on the designated CARP owner, creating a single, distributed logical cache without duplication.
## Schema Fields
### Global Fields
* **Enabled (enabled)**: Toggles proxy forwarding globally.
* **Enable CARP (carp)**: Enables Cache Array Routing Protocol for load balancing across peers.
* **CARP hash size (carphashsize)**: Determines the hash bucket size for CARP distribution.
- **CARP hash size semantics**: `0` uses the full hash range, matching the behavior of other CARP-compatible proxies when every peer in the array also uses `0`. A non-zero value increases the chance that different URLs land on the same peer — more cache overlap across peers. Every peer in the array must be configured with the same non-zero value for consistent results.
### Rule-Based Fields (Per Connection Tuning)
* **Enabled (enabled)**: Toggles the rule.
* **Comment (comment)**: User description.
* **Profiles (profiles)**: The trigger condition. Limit this entry to connections that already carry these Access Profile tags.
- **Profiles negation**: a profile prefixed with `!` applies the entry when that profile is absent.
- **Proxy (proxy)**: The IP address or hostname of the upstream proxy server.
- **User name (username)**: The username to authenticate with the upstream proxy.
- **Password (password)**: The password to authenticate with the upstream proxy.
- **Domain (domain)**: The NT domain to present when the upstream proxy uses NTLM authentication. Not a URL filter.
- **Port (port)**: The TCP port of the upstream proxy server.
- **ICP peer type (icptype)**: Defines the relationship with the peer (e.g., Parent, Sibling).
- **ICP port (icpport)**: The UDP port used for ICP queries.
- **Type (type)**: The type of the upstream proxy: `HTTP`, `SOCKS4`, `SOCKS5`, or `CONNECT`.
- **Applies to (which)**: The request types forwarded through this proxy: HTTP, FTP, and/or CONNECT (HTTPS).
## Important entry fields
* **Profiles** — Limit the row with Access Profile tags. Blank matches all profiles.
* **Proxy** — Upstream hostname or IP. Blank on a matching row **stops candidate collection** without forwarding. Rows whose Proxy equals this instance hostname or System configuration **Proxy hostname** are skipped (shared-config safety).
* **Type** — **HTTP** (standard proxy), **SOCKS4** / **SOCKS5**, or **CONNECT** tunnel. Port defaults to `3128` for HTTP/SOCKS and `443` for CONNECT when Port is 0.
* **Applies to** — Protocol flags: HTTP, FTP, CONNECT. Row is skipped when the connection protocol does not match any selected flag.
* **ICP peer type / ICP port**. When global CARP is off: **NONE** gives fixed priority 1; **PARENT** forwards on ICP miss; **SIBLING** forwards only on ICP HIT. UDP ICP uses the ICP port on this row; global ICP listen port and timeout come from [Caching](/configuration/application_setup/accelerators/caching).
- **ICP eligibility** — only Type `HTTP` is eligible for ICP peer selection.
- **User name / Password / Domain** — Upstream proxy authentication when the selected peer requires it. **Domain** applies only to NTLM.
**Blank Proxy stops collection.** A matching row with empty Proxy ends the scan — lower rows are not added as candidates. Place intentional “direct” stop rows carefully.
## Processing order
1. If forwarding is disabled, or Access **Bypass → Forward** is set, skip.
2. Walk Forwarding proxies top to bottom; add each enabled matching row with a non-self Proxy to the candidate list.
3. Blank Proxy on a matching row stops collection immediately.
4. CONNECT requests skip ICP/CARP selection logic used for plain HTTP.
5. Select one peer: CARP hash among candidates, or ICP priorities, or random tie-break.
6. Send the request through the selected peer, or direct if no candidate remains.
`startup.ini` may append implicit upstream rows from the proxy’s IP detection / port when set — not shown in the Web UI but affects runtime.
## Examples
Open **Configure → Application Setup → Proxy chain → Forwarding proxies**. Row fields are Enabled,
Comment, Profiles, Proxy, Port, ICP peer type, ICP port, Type, and Applies to.
![SafeSquid console showing a Forwarding proxies row with an upstream Proxy and Port, the Edit Policies icon circled]()
### 1 — All HTTP through one upstream
* Enabled: on
* Row: Proxy `upstream.example.com`, Port `3128`, Type HTTP, Applies to HTTP + CONNECT
**Result:** matching HTTP and CONNECT traffic uses that upstream. Access Bypass Forward sends affected users direct instead.
### 2 — Profile-specific upstream with direct stop
* Row 1: Profiles `USE PARENT PROXY`, Proxy `parent.internal:8080`
* Row 2: Profiles blank, Proxy blank
**Result:** connections with the profile match row 1 and forward to the parent. Others match row 2, collection stops at blank Proxy, and traffic goes direct.
### 3 — CARP among two peers
* Enable CARP on; two rows with different Proxy hosts, both match profiles/protocols
**Result:** for each URL, CARP picks one peer (or local handling if this proxy wins the hash). Non-selected paths do not forward that request.
## How to verify
1. Enable FORWARD in `LOG_LEVEL`; look for native `forwarding:` lines.
2. From a test client, confirm upstream sees traffic from SafeSquid (or from your upstream auth logs).
3. Enable **Trace Entry** on one Forwarding proxies row to see candidate collection.
4. Detailed logs may show forward-related status when policies apply.
5) If a request that should be forwarded goes direct instead, look for a blank-Proxy row positioned above the one you expected to match. It stops candidate collection silently.
6) For a CARP setup, confirm every peer in the array uses the same CARP hash size.
## Next steps
* **[Caching](/configuration/application_setup/accelerators/caching)** - control in-memory HTTP caching in SafeSquid: set refresh rules, freshness limits, and object size limits for cached content.
# SSqore
Source: https://docs.safesquid.com/configuration/application_setup/ssqore
Turn on SSqore cloud categorization so Access Profiles can match requests by website category.
# Turn On SSqore Categorization
**SSqore** categorizes websites by the likely nature of their content. It queries SafeSquid's Content Categorisation Service (CCS) and adds category names to the connection so [Access Profiles](/configuration/restriction_policies/access_profiles) and filters can match on them.
SSqore has globals only — no policy list. See [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds) for CCS connectivity and offline behaviour.
## Global settings
Open **Configure → Application Setup → SSqore**. The entire configurable surface is two toggles —
Enabled and Heuristic.
![SafeSquid console showing SSqore Global settings with Enabled set to TRUE, the Edit Policy icon circled]()
* **Enabled** — When off, URL categorization is skipped and no CCS categories are added to connections. When on, host names are looked up and categories are merged into the connection profile list for policy matching.
* **Heuristic** — Stored in configuration but **not read** by the current build. Toggling Heuristic does not change URL lookup behaviour today.
## How categorization works
SSqore is the last-resort cloud tier: it runs only if the site is still uncategorized after local [Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites) entries and DNS category feeds have already been checked.
1. During request profiling, SSqore first checks a fast in-memory cache of recently-categorized destinations, then a second, larger on-disk cache of previously-seen results. Only on a double miss does it perform a live lookup against CCS for the request host (and referer host where applicable), caching the result for next time.
2. Returned category names are added to `website_categories` / connection profiles used by Access Profiles and other sections. The result is always a Category **label** — SSqore never returns a numeric score, a risk rating, or a confidence percentage. Whatever filtering decision follows is entirely up to how an Access Profiles entry is written to match on that label.
3. Results are cached under `/var/lib/safesquid/ssqore/cache` to reduce repeat lookups.
4. URLs that cannot be categorized may be queued as uncategorized for later retry.
5. When SSqore is disabled, categorization hooks exit without adding categories.
6. If the appliance's subscription has expired, SSqore categorization is skipped for that connection, the same way other subscription-dependent labeling features are gated.
**Code quirk — Heuristic unused:** The Heuristic global is persisted in config XML but the runtime module does not consult `heuristic` when calling CCS. Enable/disable behaviour is controlled only by the Enabled switch.
## Using categories in policies
Access Profiles Secondary Policies typically match SSqore category tags (for example block Social Networking). Categories appear as profile strings on the connection after lookup — design profiles to reference the exact category names CCS returns.
Custom or local categories may also come from the [Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites) tool and DNS category zone settings in startup.ini. SSqore is the cloud lookup path.
## Examples
### 1 — Enable cloud categorization
* Enabled: on
* Valid subscription and network path to CCS (see feeds documentation)
**Result:** browsing adds category tags to each connection; Access Profiles can ALLOW or DENY by category.
### 2 — Offline appliance
* Enabled: on
* No CCS reachability
**Result:** lookups fail or use cache only; uncategorized hosts may receive Uncategorized Web-Sites or no new categories until connectivity returns.
## Recommended practice
* Keep SSqore enabled when Access Profiles depend on cloud categories.
* Do not rely on Heuristic until wired in code — treat it as a stored placeholder.
* Monitor subscription and feed status under Support / feeds documentation.
## How to verify
1. Enable CATEGORY log level; look for `SSqoreSection::` and category assignment lines.
2. Open Detailed logs for a browsed URL; confirm category tags on the connection.
3. Test an Access Profile that matches a known SSqore category (allow or deny).
## Next steps
* [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds)
* [Access Profiles](/configuration/restriction_policies/access_profiles)
* [Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites)
* [Subscription](/configuration/infrastructure_and_access/subscription)
* [Logging and troubleshooting](/configuration/start_here/logging)
# System configuration
Source: https://docs.safesquid.com/configuration/application_setup/system_configuration
Set the global hostname, connection pool, debug headers, CONNECT port rules, and per-connection compression and buffering policy.
# Set Global System Configuration
The **General** section sets global hostname, connection pool, debug headers, and per-connection compression/buffering policy rows.
## Core mechanics
### First matching policy row
Each getter walks **Compression and buffering policies** top-down. The first enabled row whose `profiles` match wins. Empty profiles match all. No match → built-in defaults.
That one matching entry supplies every timing, buffering, and compression value for the connection — values are never mixed across entries. No entry below it is consulted. It is strictly first-match, not cumulative.
### CONNECT ports (cportrange)
The CONNECT port check applies only when a row matched. Port must be in the row list or CONNECT is blocked. When no row matched, all CONNECT ports are allowed (unless blocked elsewhere).
**A policy list with no catch-all leaves CONNECT unrestricted.** If every Compression and buffering policies row is scoped to a narrow Profiles value, or the list has no catch-all row at all, CONNECT is completely unrestricted for any connection that matches nothing. If you need CONNECT restricted for all traffic, keep an always-matching row (blank Profiles) last, with the CONNECT ports you intend to enforce.
### Compression and chunked buffering
`compressin` zero → identity-only upstream Accept-Encoding; non-zero → full encodings (TRUE and AUTO behave the same today). `bufferchunked`: 0 never, 2 always, 1 encoded-only when Content-Encoding is identity.
### Buffer and compression caveats
`maxdbuffer` only applies when Content-Length is known and the body is not chunked. A chunked or Content-Length-less response streams through without full buffering regardless of the configured size. `bufferwait` is the interval between re-sends of the "downloading" holding page while a large response is still buffering. Compress outgoing is effectively always on for SafeSquid's own Web interface, regardless of what the matched entry says. Only traffic to external origins honours the matched entry's Compress outgoing setting.
```mermaid theme={null}
flowchart TB
conn[Connection with profiles] --> walk[Walk Compression and buffering policies top-down]
walk --> row{Row enabled and profiles match? - blank profiles matches all}
row -->|Yes| apply["Apply this row's timeouts, buffers, cportrange, compression - stop"]
row -->|No| more{More rows?}
more -->|Yes| walk
more -->|No| defaults[Use built-in defaults - CONNECT ports unrestricted]
```
## Section fields
The console splits this section into two tabs. Connection pool size and timeout are **Global**
fields, not a tab of their own — the pool view is a read-only panel reached from Global.
## Global fields
Open **Configure → Application Setup → System configuration → Global**.
![SafeSquid console showing System configuration Global fields with Send Debugging Headers To set to CLIENT, the Edit Policy icon circled]()
* **Proxy hostname (`hostname`)** — Identity in Via and Kerberos scripts; blank uses system hostname. Setting it to your organization's single LDAP domain name lets users log in without typing the domain themselves.
* **Connection pool size / timeout (`poolsize` / `pooltimeout`)** — Resizes upstream `serverpool` immediately on config update. When the pool is full the oldest pooled connection is dropped to make room. The idle clock resets each time a pooled connection is reused.
* **Send Debugging Headers To (`dheaders`)** — CLIENT, SERVER, BOTH, or NONE — see [Debug headers](/configuration/start_here/debug_response_headers).
* **Dynamic Categorization (`catreferer`)** — Referer categories applied to dependency requests. So a permitted page's sub-resources render instead of showing broken pieces.
### Connection pool panel
A read-only Web UI panel showing the connections currently held open in the pool, or awaiting reuse. Useful for confirming **Connection pool size** and **Connection pool timeout** are sized correctly under real load.
## Entry fields
* **Enabled (`enabled`)** — disabled entries are skipped during the top-to-bottom walk.
* **Comment (`comment`)** — administrator note; not evaluated.
* **Profiles (`profiles`)** — blank matches every connection; a profile prefixed with `!` applies the entry when that profile is absent.
* **Connection timeout (`ctimeout`)** — seconds allowed for the outbound connection to the origin server and its I/O before timing out.
* **Header timeout (`timeout`)** — seconds allowed for the client to finish sending its request headers.
* **Keepalive timeout (`keeptimeout`)** — seconds an idle client connection is kept open for reuse.
* **Maximum download buffer size (`maxdbuffer`)** — largest response body SafeSquid will fully buffer for inspection.
* **Maximum upload buffer size (`maxubuffer`)** — largest client upload SafeSquid will buffer for inspection.
* **Buffer wait time (`bufferwait`)** — seconds between re-sends of the "downloading" holding page while a large response is still buffering.
* **CONNECT ports (`cportrange`)** — ports allowed for HTTP CONNECT (tunneled HTTPS) when this entry matches. For example: `443,563`.
* **Always compress mimetype (`encodemime`)** — comma-separated regular expressions matched against the response's Content-Type.
* **Compress outgoing (`compressout`)** — gzip-compress eligible responses toward the client.
* **Compress incoming (`compressin`)** — `FALSE`, `TRUE`, or `AUTO`; controls the Accept-Encoding SafeSquid advertises upstream.
* **Buffer Chunked Responses (`buffer_chunked`)** — `NEVER`, `ENCODED`, or `ALWAYS`.
* **Add X-Forwarded-For header (`xforwardedfor`)** — when on, upstream requests include the client's address in `X-Forwarded-For`.
* **Add Via header (`via`)** — when on, upstream requests include a `Via` header naming this proxy hop.
## Examples
Open **Configure → Application Setup → System configuration → Compression and buffering
policies**. Row fields include Connection/Header/Keepalive timeout, Maximum download/upload buffer
size, Buffer wait time, CONNECT ports, and the compression fields.
![SafeSquid console showing a Compression and buffering policies row with CONNECT ports and buffer size fields, the Edit Policies icon circled]()
### CONNECT HTTPS only
**Config:** First matching row cportrange `443` only.
**Result:** CONNECT to 443 allowed; other ports blocked with security-restrictions template.
### Profile-specific buffering
**Config:** Row 1 profiles `text-filter`, maxdbuffer 128K above catch-all maxdbuffer 0.
**Result:** Text-filter connections buffer up to 128K. Others stream without full download buffer — and a streamed response never reaches the downloaded-body scanners (SqScan, Clam antivirus, Image analyzer, Text analyzer, ICAP). See [Architecture and request pipeline](/configuration/start_here/architecture) for the verified buffered-vs-streamed scanning test.
### No row match
**Config:** All policy rows disabled for connection.
**Result:** CONNECT port check allows any port; default timeouts apply.
### A catch-all placed first blocks a specific entry
**Config:** Entry 1 (top) — Profiles blank, CONNECT ports `80,443,21,1025-65535`. Entry 2 (below) — Profiles `text-filter`, Maximum download buffer size `128M`.
**Result:** every connection matches entry 1 first, because it has no Profiles restriction — entry 2 never applies to anything. The fix is to move entry 2 above entry 1, so `text-filter` connections get its buffer size before the catch-all claims them.
## How to verify
1. Test CONNECT to allowed and blocked ports.
2. Enable Trace Entry on a policy row; check native logs.
3. Debug headers CLIENT in browser devtools when enabled.
## Next steps
* **[Debug response headers](/configuration/start_here/debug_response_headers)** - turn on X-SafeSquid debug headers to see which profiles, categories, and filters applied to a request.
* **[Architecture and request pipeline](/configuration/start_here/architecture)** - follow a request through SafeSquid from admission and identity, through protocol fork and enforcement, to fetch and response delivery.
# WCCP
Source: https://docs.safesquid.com/configuration/application_setup/wccp
Understand how WCCP router redirection works with SafeSquid, and what to confirm on your build before relying on it.
# Check WCCP Redirection Before You Rely on It
WCCP works with WCCP routers to redirect traffic to SafeSquid without setting a proxy in each browser. The router intercepts traffic and hands it to SafeSquid, so clients need no proxy configuration. The router or switch, not SafeSquid, decides which packets get redirected, based on the service group both sides have agreed on — SafeSquid's role is to register itself with the router(s) as willing to serve one or more service groups, describe which traffic it wants redirected, and accept and process the redirected packets.
**Confirm WCCP redirection works on your build before relying on it.** Legacy SafeSquid documentation states WCCP redirection is broken and recommends explicit proxy configuration instead. That claim could not be confirmed or refuted against build `2026.0627.1344.3` — the console exposes the section normally. But a working router is needed to test redirection end to end.
**Missing:** the functional status of WCCP redirection in the shipping build. Test redirection in a lab with a real WCCP router before committing to it in production, and keep an explicit-proxy or PAC fallback ready. Escalate to engineering rather than treating the section's presence in the console as proof it works.
## Globals / subsections
**Enabled** (global master switch, `FALSE` by default) and **WCCP policies** (the policy rows).
## Processing
All enabled WCCP policies can be used for router communication.
Traffic selection is described two ways at once: **Application Protocol** tells SafeSquid which protocols it expects (HTTP, HTTPS, FTP, SFTP), while **Ports** further restricts redirection to specific TCP ports or ranges. Both need to reflect what you actually intend to intercept, or traffic the router captures may not be what SafeSquid expects on this entry.
## Schema Fields
### Global fields
* **Enabled (enabled)** — Master switch for WCCP router communication.
### Policy rows
* **Enabled (enabled)** — Enable or disable this policy.
* **Comment (comment)** — Explains the entry's purpose for future readers.
* **Proxy host (proxyhost)** — Regex matching the proxy hosts this entry applies to. Useful when one configuration file is shared between several proxy servers.
* **WCCP Version (wccp\_version)** — `WCCPV1` or `WCCPV2`.
* **Router IP Address (router\_ip)** — Router addresses SafeSquid interacts with for transparent redirection. WCCP v1 allows a single router per service group; v2 allows multiple.
* **Application Protocol (traffic\_capture)** — Traffic type the routers redirect: `HTTP`, `HTTPS`, `FTP`, `SFTP`. `HTTP` and `HTTPS` are on by default; `FTP` and `SFTP` are off by default.
* **Service Type (service\_type)** — `WELLKNOWN` (predefined, needs no service definition) or `DYNAMIC` (you define the service group with a service ID and parameters).
* **Service Group ID (service\_id)** — Service ID of the service group. **Must be between 97 and 255.**
* **Service Group Name (service\_name)** — Name of the service group.
* **Security (security)** — `NOSECURITY` or `MD5SECURITY` for packet authorization. `NOSECURITY` needs no password.
* **Encrypted Password (enc\_pwd)** — Encrypted password for packet authentication. Required when Security is `MD5SECURITY`.
* **Acceptable Forward Method (forward\_method)** — How the router transfers packets to SafeSquid: `GRE` (default) or `L2`. Layer 2 requires supporting network architecture. SafeSquid negotiates with the router for a supported method if its preferred one isn't supported.
* **Acceptable Assignment Method (assignment\_method)** — Method used when SafeSquid becomes the designated proxy: `HASH` or `MASK` (default, confirmed live on build `2026.0627.1344.3` — a brand-new, unsaved policy entry pre-fills `MASK`).
* **Acceptable Packet Return Method (packet\_return\_method)** — How SafeSquid returns packets to the router: `GRE` (default) or `L2`.
* **Ports (portrange)** — Comma-separated list of ports or port ranges this entry applies to. WCCP v2 allows up to 8 ports.
* **Network Protocol (network\_protocol)** — `TCP` or `UDP`. SafeSquid informs the router of this selection. Both `TCP` and `UDP` are enabled by default.
* **Webcache IP Address (webcache\_ip)** — SafeSquid addresses that interact with the WCCP routers. Must be an address SafeSquid is genuinely listening on — this is the address the router actually redirects traffic to.
## Important entry fields
* **Service Group ID** — Values outside 97–255 are invalid. Coordinate the ID with the network team so it matches the router's service group.
* **Security / Encrypted Password** — Set both together. `MD5SECURITY` without a password fails packet authentication.
* **Acceptable Assignment Method / Acceptable Packet Return Method** — Do not select `GRE` as the return method when the assignment method is `L2`.
* **Acceptable Forward Method / Acceptable Packet Return Method** — Configured independently and don't have to match — but a common misconfiguration is selecting one method as the assignment/forward choice while still expecting the other as the return method, when the router's own capabilities don't actually support that combination. Confirm supported forwarding and return methods with the router's own documentation and the network team.
* **Router IP Address / Webcache IP Address** — Both sides of the relationship. The router list must match the service group configured on the router itself.
## Examples
### A standard well-known HTTP/HTTPS redirection
Enabled on, WCCP Version v2, one router address, Application Protocol HTTP and HTTPS, Service Type WELLKNOWN, Security NOSECURITY, default forward/assignment/return methods, Network Protocol TCP, Webcache IP Address the appliance's client-facing address. The shape of the most common single-router deployment.
### A custom dynamic service group with authentication
Service Type DYNAMIC, Service Group ID `98` (agreed in advance with the network team and matched on the router), Service Group Name `SafeSquid-Web`, Security MD5SECURITY with an Encrypted Password matching the router's secret, two routers listed under WCCP v2. Needed whenever the well-known service group doesn't fit — for example redirecting only a specific port range.
### Restricting to specific ports
Ports `8081,9000-9010` alongside Application Protocol HTTP. Only traffic on those ports is what SafeSquid told the router it wants for this entry. Standard port 80 would need a separate entry or need to be added to this entry's Ports list.
## How to verify
The checks below confirm the configuration is complete, not that transparent redirection is actually working end to end — see the reliability warning above.
1. Confirm the global Enabled switch and the entry's own Enabled switch are both on.
2. Confirm the Service Group ID (dynamic service) and any Encrypted Password (MD5 security) exactly match what's configured on the router side. SafeSquid does not surface a clear mismatch error in the Web UI.
3. Work with the network team to confirm, from the router or switch's own status output, that it has actually formed the service group and is redirecting matching traffic.
4. Once redirected traffic is confirmed arriving, check Detailed logs for those transactions the same way as explicitly-proxied traffic.
5. Re-confirm the whole chain after any router firmware change, network re-addressing, or SafeSquid version update.
## Notes
Coordinate service group IDs and passwords with the network team. The **Enabled** global is `FALSE` on a default appliance, so WCCP does nothing until it is switched on. Most WCCP failures come from the two sides of the negotiation (router configuration and this Web UI section) drifting out of agreement, not from either side being wrong in isolation.
## Next steps
* [network](/configuration/application_setup/network_settings_and_listeners)
* [integrations](/configuration/start_here/integrations)
* [Architecture](/configuration/start_here/architecture)
* [Logging](/configuration/start_here/logging)
# Application Signatures
Source: https://docs.safesquid.com/configuration/custom_settings/application_signatures
Legacy reference: how application signatures tag HTTP requests (such as Webmail or BitTorrent) for Access Profiles. This section is not in the current Configure console.
# Tag Requests With Legacy Application Signatures
**This section does not appear in the Configure console.** Verified 2026-09-04 against `http://safesquid.cfg`, build `2026.0627.1344.3`: the section is absent from the console's own section registry, not merely hidden from the menu. It is kept here as legacy and reference material, not a current UI path. Confirm against your own build before pointing an administrator at it.
The **Application Signatures** section tags each HTTP request with application signature strings (for example Webmail, BitTorrent, Chrome). Other sections match those tags with exact string compare — especially [Access Profiles](/configuration/restriction_policies/access_profiles) (Request Types field) and [Request Types](/configuration/custom_settings/request_types).
Vendor signature databases download on the appliance update schedule. See [startup.ini](/configuration/start_here/startup_ini) UPDATE settings, [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds), and [Subscription](/configuration/infrastructure_and_access/subscription) (expired subscription skips all signature processing).
## Core mechanics
### Processing order
1. If `SUBSCRIPTION_EXPIRED` is set, processing is skipped entirely for that connection.
2. Prior application-signature and request-type tags are cleared.
3. Built-in tags may be added: `IPV4 Host`, `IPV6 Host`, `Cross Site Request`.
4. **Application Signatures List** is walked top to bottom. **Every** enabled rule whose tests pass may add or remove tags — there is no first-match stop.
5. Tags from earlier rules in the same pass are visible to later rules via the **Application signatures** prerequisite field.
6. Final tags are copied to `request_types` and logged as application signatures.
```mermaid theme={null}
flowchart TB
conn[Connection enters the signature stage]
sub{"SUBSCRIPTION_EXPIRED set?"}
skip[Skip signature processing entirely for this connection]
clear[Clear prior application-signature and request-type tags]
builtin["Add built-in tags where they apply — IPV4 Host, IPV6 Host, Cross Site Request"]
row[Take the next enabled row of the Application Signatures List]
filters{"Row filters pass? Application signatures, then Method and Protocol, then Mime type, then port, post size, File, host and referer, User Agent, X-Forwarded-For, Request header pattern"}
tag[Add Added application signatures and category tags; remove Removed application signatures]
more{More rows left?}
copy["Copy final tags to request_types and log them"]
conn --> sub
sub -->|Yes| skip
sub -->|No| clear --> builtin --> row --> filters
filters -->|Any filter fails| more
filters -->|All pass| tag --> more
more -->|Yes — no first-match stop| row
more -->|No| copy
```
Tags added by an earlier row are visible to later rows through the **Application signatures**
prerequisite field, which is why the walk is cumulative rather than first-match.
### Global Enabled quirk
The section global **Enabled** switch is stored in configuration but request-time matching checks only each rule's own **Enabled** flag. Per-rule Enabled off skips that row; global off does not stop the signature loop by itself.
### Inner filter order (per row)
For each enabled row, filters run in fixed order; any failure skips to the next row:
1. **Application signatures** — prerequisite tags (exact / `!` match, same engine as Access Profiles).
2. **Method**, **Protocol** — exact; missing header when field set → skip row.
3. **Mime type** — regex on request `Content-Type`.
4. **Port range list**, post data size gates, **File**, host/referer regex fields, **User Agent**, **X-Forwarded-For**, **Request header pattern**.
5. On match: add **Added application signatures** and **category** tags; remove listed **Removed application signatures**.
**Post data size:** when `Content-Length` is present, the rule is *skipped* when `content_length > minimum` or `content_length < maximum` (optional fields must be active). No Content-Length → min/max checks are not applied.
**URL commands** are loaded from configuration but not evaluated — leave blank.
### Application Categories List
Category definition rows are saved to the local dev XML for UI autocomplete. Runtime category tags come from the **category** field on Application Signatures List rules, not from the Categories list alone.
Application Categories List **Enabled** off means the category definition is not loaded into the in-memory category list on the next configuration reload. Neither On nor Off applies a category to live traffic by itself. That still requires an Application Signatures List entry whose **category** field references the same name.
## Schema fields
Each Application Signatures List entry field, its internal name, and what it actually tests:
| Field | Internal name | Tests |
| - | - | - |
| Application signatures | `app_signatures` | Prerequisite — signature(s) already present (or, with `!`, absent) before this entry's other conditions are checked |
| Method | `method` | Request's HTTP method, exact match |
| Protocol | `protocol` | Request's protocol (`HTTP`, `HTTPS`, `FTP`), exact match |
| Mime type | `mime` | Regex against the request's Content-Type header |
| Port range list | `portrange` | Request's destination port against the listed port(s)/range(s) |
| Minimum Post Data Size | `postdata_min_length` | Content-Length ceiling — see the Post data size warning above |
| Maximum Post Data Size | `postdata_max_length` | Content-Length floor — see the Post data size warning above |
| File | `file` | Regex against the URL path |
| Registered Domain | `registered_domain` | Regex against the request host's registered domain |
| Host Name | `hostname` | Regex against the request's fully-qualified hostname |
| Referer Domain Name | `referer_domain` | Regex against the referrer's registered domain |
| Referer Host Name | `referer_host` | Regex against the referrer's fully-qualified hostname |
| Referer | `referer` | Regex against the full Referer header |
| User Agent | `user_agent` | Regex against the User-Agent header |
| X-Forwarded-For | `xforwardedfor` | Regex against the X-Forwarded-For header |
| Request header pattern | `requestheader` | Regex against the raw request headers |
| Added application signatures | `add_app_signatures` | Signature values added to the connection on match |
| Removed application signatures | `remove_app_signatures` | Signature values removed from the connection on match, applied after additions |
| category | `group` | Category values added to the connection's signatures on match, same mechanism as Added application signatures |
| Comment | `comment` | Administrator note; not read by the matching engine |
| Enabled | `enabled` | When off, this entry is skipped in the top-to-bottom pass |
Removals are applied **after** additions on the same matching entry. An entry that both adds and removes the same signature name ends with it removed.
Where a tested value is absent from the request (for example, no Referer header when a Referer-based field is set), the entry is skipped.
## Examples
### Tag webmail from vendor rule
Vendor database row matches host and User-Agent; adds `Webmail`.
**Result:** Access Profiles matching Request Types or application signature `Webmail` apply webmail policy.
### Custom rule on top of vendor tags
* Prerequisite `Webmail`, Host Name `mail\.partner\.com`
* Added application signatures `Partner-Webmail`
**Result:** only partner webmail gets the extra tag; generic webmail keeps `Webmail` only.
### Category tag for reporting
On match, **category** `SocialMedia` is added to application signatures (same tag list).
**Result:** policies and logs can match category name `SocialMedia` without a separate Categories list row.
## How to verify
1. Check the module load status for application signature load/download state.
2. Reproduce a request; read Detailed logs column `application_signatures`.
3. Enable **Trace Entry** on a rule where available; confirm tags in Native PROFILE logs.
4. Debug header `X-SafeSquid-Application-Signatures` when Send Debugging Headers To includes CLIENT — see [Debug response headers](/configuration/start_here/debug_response_headers).
## Next steps
* [Request Types](/configuration/custom_settings/request_types)
* [Access Profiles](/configuration/restriction_policies/access_profiles)
* [Subscription](/configuration/infrastructure_and_access/subscription)
* [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds)
* [Logging and troubleshooting](/configuration/start_here/logging)
# Categorize Web-Sites
Source: https://docs.safesquid.com/configuration/custom_settings/categorize_web_sites
Override website categories locally: search a host, edit its categories, or bulk-assign categories from a file.
# Override Website Categories Locally
**Categorize Web-Sites** is a Web UI application for local website category overrides. Categories assigned here feed the in-memory categorisation used on the request path together with cloud feeds (SSqore / DNS zone). Use it when vendor categories are wrong or when you need internal-only category names in [Access Profiles](/configuration/restriction_policies/access_profiles).
## Subsections
* **CATEGORY EDITOR** — Search, edit, bulk upload, and refresh local category assignments.
## What you can do
* **Search for category** — enter a hostname or domain; view categories currently assigned to that site.
* **Modify** — add, remove, or change category links for the searched site (saved through the category manager CGI).
* **Upload websites file** — bulk-assign categories to many hosts from a text file plus selected category names.
* **Update from database** (refresh control) — reload category metadata counts and timestamps from the backend store.
Open **Configure → Custom Settings → Categorize Web-Sites**. The single **CATEGORY EDITOR**
subsection holds Search for category, Upload websites file, and the Update from database refresh
control, alongside Total categories / Last changes by / Last update time.
![SafeSquid console showing the Categorize Web-Sites Category Editor with the Search for category box circled]()
Cloud categorisation also comes from [SSqore](/configuration/application_setup/ssqore) and DNS zone feeds (see [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds) and [startup.ini](/configuration/start_here/startup_ini) `DNS_CAT_ZONE`). Local overrides in this editor take precedence for matching needles on the hot path.
## How categories are used in policy
1. During categorisation, SafeSquid resolves categories for the request host (and related lookup paths).
2. Category names appear on the connection and in logs (`categories` column).
3. [Access Profiles](/configuration/restriction_policies/access_profiles) can match **Categories** to ALLOW or DENY.
4. [Request Types](/configuration/custom_settings/request_types) Domains and Urls can set **Bypass DNSBL and Categorization** to skip DNS Blacklist and categorisation for specific hosts.
## Examples
### 1 — Fix miscategorised partner site
1. Search `partner.example.com`.
2. Remove incorrect category; add `Business-Partners`.
3. Click Modify; confirm success message.
**Result:** subsequent requests classify the host with your local categories; Access Profiles matching `Business-Partners` apply.
### 2 — Bulk onboard internal domains
1. Prepare a text file listing internal hostnames.
2. Upload file; select category `Internal`.
3. Search one listed host to verify categories.
**Result:** all listed hosts share the assigned local category without editing each site individually.
## How to verify
1. Search the site again after modify; categories shown should match your edit.
2. Reproduce a browser request; check Detailed logs `categories` column.
3. Confirm Access Profiles DENY/ALLOW on category names behaves as expected.
## Next steps
* [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds)
* [SSqore](/configuration/application_setup/ssqore)
* [Access Profiles](/configuration/restriction_policies/access_profiles)
* [DNS Blacklist](/configuration/real_time_content_security/dns_blacklist)
* [Architecture](/configuration/start_here/architecture)
* [Logging](/configuration/start_here/logging)
# Content Signatures
Source: https://docs.safesquid.com/configuration/custom_settings/content_signatures
Legacy reference: how custom content signatures map MIME types in SafeSquid. This section is not in the current Configure console.
# Map MIME Types With Legacy Content Signatures
**This section does not appear in the Configure console.** Verified 2026-09-04 against `http://safesquid.cfg`, build `2026.0627.1344.3`: the section is absent from the console's own section registry, not merely hidden from the menu. It is kept here as legacy and reference material, not a current UI path. Confirm against your own build before pointing an administrator at it.
The **Content Signatures** section maintains the content-signature database and libmagic MIME detection used across SafeSquid. It helps identify actual file types, bypassing deceptive file extensions — but live connection tagging for policy uses [Response Types](/configuration/custom_settings/response_types) in the current build.
Custom rows are merged into `content4.xml` under `/var/lib/safesquid/content_signatures/`. Tag names still appear in DLP and UI pickers even when the request-time hooks are inactive.
## Core mechanics
### What runs at runtime today
1. On config load and on scheduled update, SafeSquid may download vendor `content4.xml` and reload the merged database.
2. Custom rows from the Web UI are saved to the dev copy of `content4.xml` when the section is displayable.
3. The internal MIME engine uses the libmagic database from this directory for body type detection (also used by DLP, logging, and Response Types).
4. The request-time hooks are **not implemented** — list rows do not add or remove connection tags at request time in the current build.
For live response labelling by MIME or extension, use [Response Types](/configuration/custom_settings/response_types). Content Signatures rows still matter for database maintenance, autocomplete in other sections (for example DLP), and libmagic setup.
### Global Enabled
When off, the section reports itself disabled — signature database download/reload and MIME library setup are affected. List rows are still persisted even when the request-time hooks are inactive.
### Subsections
* **Content Signatures List** — MIME regex rows plus tags to add. Stored in config; not applied on connections at request time today.
* **Content Categories List** — Category names for autocomplete and grouping in signature rows.
* **Content File Extensions** — Extension regex rows plus extension tags. The matching request-time hook is not implemented.
### Legacy UI options
Selectors such as **Transfer Encoding Chunk**, **multi-part byte-range**, and **Trace Entry** under Content Signatures are not bound to any template field in this tree. They have no effect here (the same labels on Response Types do affect matching).
## Schema fields
None of the fields below are matched against live traffic in the current build — see the warnings above.
### Global
* **`enabled`** — master switch for signature database download/reload and MIME-detection library setup. Entries you add are saved regardless of this setting.
### Content Signatures List
* **`enabled`** — off skips the entry on save or reload.
* **`comment`** — administrator note.
* **Mime type (`valueField`)** — a regex such as `^text/html` or `^image/`; blank represents all MIME types.
* **`add_content_signatures`** — the signature value(s) this entry defines.
* **category (`group`)** — category value(s) associated with this entry.
### Content Categories List
* **`enabled`**, **`comment`**, **`add_content_category`** — same fields as above, applied to a category definition rather than a signature.
### Content File Extensions
* **`enabled`**, **`comment`** — same fields as above.
* **File Extension (`valueField`)** — a regex. Comma-separated patterns are combined as an OR, the same convention Response Types uses; blank represents all extensions.
* **`add_file_extensions`**, **`group`** — the extension value(s) this entry defines, and its category.
A category name does **not** require a matching entry in Content Categories List to be usable. That list exists only to populate autocomplete pickers.
## Examples
### Maintain a custom MIME tag for DLP autocomplete
* Content Signatures List: Mime type `^application/x-custom`, Added Content Signatures `CustomApp`
**Result:** tag name appears in DLP and UI pickers. Connection tags are not added automatically — pair with a Response Types row if policy must match live traffic.
### Policy on detected downloads (use Response Types)
* Response Types: Content type `^application/zip`, Added Response Types `archive-download`
**Result:** live traffic is tagged using response headers and libmagic-detected type; Access Profiles can match `archive-download`.
## How to verify
1. Check module stats / Reports for content signature load or download status.
2. After editing rows, confirm `content4.xml` under `/var/lib/safesquid/content_signatures/` updates.
3. For live tagging, verify `response_profiles` in Detailed logs, not content signature hooks.
## Next steps
* [Response Types](/configuration/custom_settings/response_types)
* [DLP](/configuration/real_time_content_security/dlp)
* [Application Signatures](/configuration/custom_settings/application_signatures)
* [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds)
* [Logging and troubleshooting](/configuration/start_here/logging)
# External applications
Source: https://docs.safesquid.com/configuration/custom_settings/external_applications
Pipe HTTP payloads to external scripts or binaries for custom authentication, logging, or content modification, and understand the trust it requires.
# Pipe HTTP Payloads to External Applications
```mermaid theme={null}
flowchart TB
walk[Walk enabled rows top to bottom] --> match{Profiles and Applies to and session mode match?}
match -->|No| next[Next row]
match -->|Yes| exec[Pipe or File body to Executable]
exec --> parse{stdout parses as well-formed HTTP header?}
parse -->|No| next
parse -->|Yes| extract[Extract X-username and X-profiles on any exit code]
extract --> exit{Exit code}
exit -->|0| replace[Replace request or response content and stop]
exit -->|Non-zero| preserve[Preserve original content]
```
## What does this section do?
The `External` section allows SafeSquid to pipe HTTP payloads to external scripts or binaries for custom authentication, logging, or content modification.
This is a genuine extension point into content not otherwise controlled from the Web UI, so treat every referenced executable as trusted code running with SafeSquid's own privileges. It sees live request and response traffic and, depending on how it exits, can replace that traffic outright or inject a username and additional Access Profiles into the connection.
## Core Mechanics (C++ Source Validation)
Exit code 0 replaces content; non-zero preserves + metadata.
* **Execution Pipeline**: SafeSquid buffers the requested HTTP components (Request Header, Response Header, or Body) into a `Filebuf` and pipes it via standard input to the executable defined in `Exec`.
* **Exit Code Logic**: The behavior of SafeSquid depends strictly on the external parser’s exit code:
* **Exit Code 0**: The original HTTP payload is *replaced* entirely by the standard output (stdout) of the script.
* **Non-Zero Exit Code**: The original HTTP payload is preserved. But any stdout returned by the script is parsed by SafeSquid to extract intelligence (e.g., dynamically adding Profiles, setting usernames).
* **Authentication Bypass**: If the connection flag `EXTERNAL_AUTH` is present, only parsers with `Per Session` set to `TRUE` will be invoked.
**`X-username`/`X-profiles` extraction is not conditional on a non-zero exit.** SafeSquid scans the program's output for those two headers and acts on them whenever the output parses as a well-formed HTTP header, on any exit code, including 0. `X-profiles` values already present on the connection are not duplicated.
## Schema Fields
### Global Fields
* **Enabled (enabled)**: Turn External applications on or off for all connections (unless bypassed).
### Rule-Based Fields (Per Connection Tuning)
* **Enabled (enabled)**: Skip this row when disabled. Walk continues until one row fully replaces content (exit 0).
* **Comment (comment)**: Notes for operators. Shown only in configuration.
* **Profiles (profiles)**: Apply only when the connection has one of these profiles. Blank = all connections.
* **Executable (exec)**: Command line: program path plus arguments (space-separated). Relative paths use PATH . With File delivery, the temp file path is appended as the last argument. Empty command skips the row.
* **Type (type)**: Pipe — body on STDIN. File — body written to a temp file; path passed as last argument.
* **Applies to (flags)**: Run on client requests ( PROCESS\_REQMOD ), server responses ( PROCESS\_RESPMOD ), or both. Request row returning a response header can answer the client without contacting the origin.
* **Run once per session (persession)**: Yes — row runs only on external auth pass; skipped on normal req/resp mod. Stops re-auth after non-zero exit ( SESSION\_EXTERNALONCE ). No — row runs on req/resp mod, not on auth pass.
* **Send header (sendheader)**: Prepend raw request and/or response header blocks before the body sent to the executable. Request header is sent first when both are selected. Response option applies only on response processing.
## How SafeSquid processes the list
1. On request modification, response modification, or external authentication (depending on row flags), SafeSquid walks enabled rows top to bottom.
2. Row must match profiles, Applies to flags, and Run once per session mode (see below).
3. Input is built from optional raw request/response headers plus body (Pipe on STDIN, or File with path as last argument).
4. **Exit code 0** — stdout is parsed as HTTP. Request or response header (and body if present) replaces the original; walk stops for that pass.
5. **Non-zero exit** — original content is preserved; stdout may still supply `X-username` or `X-profiles` for auth intelligence.
6. Run once per session **Yes**: row runs only on external auth pass. A non-zero exit marks the session to avoid re-authentication loops.
## Important entry fields
* **Profiles** — Apply only when the connection has one of these profiles. Blank = all connections.
* **Executable** — Command line: program path plus arguments (space-separated). Relative paths use `PATH`. With File delivery, temp file path is appended last. Empty command skips the row.
* **Type** — **Pipe** — stream body on STDIN. **File** — write body to a temp file; pass path as last argument.
* **Applies to** — **REQUESTS** — outgoing request modification (output may replace request or return a complete response to the client). **RESPONSES** — response modification.
* **Run once per session** — **Yes** — external auth pass only; skipped on normal req/resp mod. **No** — req/resp mod only; skipped on auth pass.
* **Send header** — Prepend raw request and/or response header blocks before the body sent to the executable. Request header is sent first when both are selected.
## Examples
Open **Configure → Custom Settings → External applications**. **Global** holds the master Enabled
switch; **Application policies** holds the rule rows (Executable, Type, Applies to, Run once per
session, Send header) once at least one row is added.
![SafeSquid console showing the External applications Global tab with the Enabled toggle set to FALSE, the Edit Policy icon circled]()
### 1 — Sanitize HTML responses
* Executable: `/opt/safesquid/bin/sanitize.pl`
* Type: Pipe, Applies to: RESPONSES
**Result:** on exit 0 with a valid HTTP response header and body on stdout, SafeSquid replaces the server response. On non-zero exit the original response is kept.
### 2 — External auth assigns username
* Run once per session: **Yes**
* Executable returns headers including `X-username: jane@corp.com` (exit code may be non-zero)
**Result:** connection username is set from stdout. If exit is non-zero, content is not replaced but auth metadata may still apply; session flag prevents repeated auth passes.
### 3 — Request filter returns block response
* Applies to: REQUESTS
* Script exit 0 with full HTTP response header (403) and optional body
**Result:** client receives the script's response without contacting the origin; walk stops at this row.
### 4 — First matching row wins
* Row 1 (top): broad profile match, Executable empty — skipped
* Row 2: Profiles `Developers`, valid script, exit 0
**Result:** Developer connections hit row 2 and replace content. Others continue down the list until a row matches and succeeds or the list ends.
## How to verify
1. Run the executable manually with sample stdin/file input and confirm exit code and HTTP header format.
2. Enable EXTERNAL in `LOG_LEVEL` for native lines showing parser path, exit code, and parse failures.
3. Reproduce from a client with matching profiles and inspect response or auth outcome.
4. Check whether `X-username` / `X-profiles` appear in logs when using non-zero exit auth helpers.
5) Confirm whether unexpected profile or username changes are coming from an entry you assumed only ran on failure — extraction is not exit-code-conditional. So it can happen on exit 0 too.
6) If a REQUESTS entry is meant to answer the client directly, confirm its script returns a complete HTTP *response* header (not a request header) on exit code 0. The wrong header type parses differently and won't produce the intended short-circuit.
## Next steps
* **[Authentication](/configuration/start_here/authentication)** - choose how SafeSquid identifies users, including Kerberos SSO and system authentication, so Access Profiles and logs can name them.
* **[Content modifier](/configuration/real_time_content_security/content_modifier)** - rewrite HTTP headers and bodies with PCRE search-and-replace to inject cookies, strip sensitive header values, or change response content.
# Request Types
Source: https://docs.safesquid.com/configuration/custom_settings/request_types
Label HTTP requests with tags that Access Profiles and other filters match on, based on what the client asked for.
# Label Requests With Request Types
The **Request Types** section labels HTTP requests with tags consumed by [Access Profiles](/configuration/restriction_policies/access_profiles) and other filters. It does not block traffic.
Request Types only ever inspects the **request** side — what the client sent. It has no visibility into what the destination returns; that is Response Types. So it can tell you what destination and what kind of activity a client is attempting. But never what was actually delivered, and it must not be relied on for that.
## Core mechanics
### Browsing vs. activity tagging
A Request Types entry can gate on a label an earlier Request Types entry already applied, and inspect the URL path to add a narrower label only when a specific activity is detected within that already-tagged destination — for example separating "browsing and searching a video site" from "actually playing a video on it", by testing whether the path contains the internal call the site's player fires only on playback. Access Profiles can then allow the broad label while denying the narrow one. This is the capability a flat site-category allow/deny cannot express.
### Processing order
The section does not evaluate any entry at all if the connection has no host to test against.
1. Application Signatures (unless subscription expired).
2. **Domains and Urls** — substring match; every matching row applies.
3. **Request Types** rows — all gates must pass; every match applies. Where two entries act on the same label, whichever runs later wins. An entry lower in the list can remove a label an entry above it just added.
```mermaid theme={null}
flowchart TB
req[Request with host] --> sig{Application Signatures active and subscription valid?}
sig -->|Yes| tagSig[Tag matching signature]
sig -->|No| domains[Walk Domains and Urls rows]
tagSig --> domains
domains --> domMatch{Host or Referer substring matches?}
domMatch -->|Yes| domApply[Apply row and add tags with optional DNSBL and categorization bypass]
domMatch -->|No| domNext[Next row]
domApply --> reqTypes[Walk Request Types rows]
domNext --> reqTypes
reqTypes --> gateAll{All configured gates on row pass?}
gateAll -->|Yes| tagReq[Add or remove Request Types tags]
gateAll -->|No| reqNext[Next row]
```
### Domains and Urls
Tab-prefixed host+path substring find — not regex. Empty domain list or empty add/remove → row skipped. **Match:** Host, Referer, or Both.
### Smart TLD
When Host Name regex misses and Smart TLD is on, same regex retried against site name (host without public suffix).
**urlcommand field:** parsed in configuration but never evaluated at runtime. Use **Protocol** or **File** instead.
**Minimum/Maximum Post Data Size:** when `Content-Length` is present, the rule is *skipped* when `content_length > minimum` or `content_length < maximum` (optional fields must be active). No Content-Length → min/max checks are not applied. Given how easily this reads backwards, prefer **Method**, **Content type**, and **File** for production rules and treat these size fields as a secondary refinement. `0` disables each test.
## Schema Fields
### Global
* **Enabled** (`enabled`) — off means no labels are added or removed here at all and neither entry list is evaluated.
### Domains and Urls entry
* **Enabled** (`enabled`), **Comment** (`comment`) — standard entry controls.
* **Domains and URLs** (`hosts`) — a list of needles separated by comma, space, tab, newline, or semicolon, searched as plain substrings against host/TLD plus path — not a regular expression, not a wildcard. Do not include a scheme prefix or a `*`.
* **Match** (`where`) — Host, Referer, or Both.
* **Added / Removed Request Types** — labels applied when a needle matches.
* **Bypass DNSBL and Categorization** — skips DNS Blacklist checking and website categorization for a matching connection. When more than one matching Domains and Urls entry sets this differently, the last matching entry's setting takes effect.
An entry with an empty needle list, or with neither Added nor Removed Request Types set, is skipped — it can never match.
### Request Types entry
* **Enabled** (`enabled`), **Comment** (`comment`), **Trace Entry** — standard entry controls.
* **Request Types** — the input gate; supports `!` negation, blank ignores the gate.
* **Method** — an exact match, not a regular expression; multiple selected methods are OR'd.
* **Protocol** — also exact, also OR'd.
* **Content type** — a regular expression; commas act as alternation.
* **Port range list** — comma list of ports and/or hyphenated ranges; not CIDR.
* **Minimum / Maximum Post Data Size** — see the Warning above for how these two actually compare.
* **File** — a regular expression against the URL path.
* **Host Name** — a regular expression against the host.
* **Smart TLD** — retries the Host Name expression against the host with its public suffix stripped; see above.
* **Referer**, **User Agent**, **X-Forwarded-For** — a regular expression against that request header.
* **Request header pattern** — a regular expression against the raw request headers.
* **Added / Removed Request Types** — Removed runs after Added on the same entry.
Content type, File, Referer, User Agent, X-Forwarded-For, and Request header pattern each cause the entry to be **skipped** when the field is set but the thing it tests is absent. That is why an entry can appear never to fire.
## Examples
Open **Configure → Custom Settings → Request Types**. Three sub-tabs: **Global**, **Domains and
Urls**, and **Request Types** — the row list shown here, with Request Types (input gate),
Minimum/Maximum Post Data Size, Smart TLD, and Added Request Types per row.
![SafeSquid console showing Request Types rows tagging uploads by size, the Edit Policies icon on the first row circled]()
### Uncachable query URLs
**Config:** File `(cgi-bin|\?)`, add `uncachable_req`.
**Result:** URLs with query string tagged; cache policies can skip storage.
### CONNECT method
**Config:** Method CONNECT, add `uncachable_req`.
**Result:** tunnel requests tagged.
### Skip categorization
**Config:** Domains needle `partner.example`, Bypass DNSBL and Categorization on.
**Result:** matching host bypasses DNSBL and category lookup.
## How to verify
1. **Trace Entry** on one row; native logs show Added/Removed tags.
2. Detailed logs `request_profiles` column — confirm which labels actually landed, in case an earlier or later entry altered what you expected.
3. If an entry using the post-data size fields behaves unexpectedly, re-check which direction each field filters before assuming the entry is broken.
4. To confirm a browse-vs-activity pair, test both a plain destination request and one matching the specific-activity pattern, confirming only the second picks up the narrower label.
## Next steps
* **[Access Profiles](/configuration/restriction_policies/access_profiles)** - decide what each user can fetch by combining time, request type, response type, category, and group labels into ordered allow and deny rules.
# Response Types
Source: https://docs.safesquid.com/configuration/custom_settings/response_types
Label HTTP responses by their real content type, such as executable, archive, or image, so Access Profiles can block by actual file type.
# Label Responses With Response Types
The **Response Types** section labels HTTP responses for [Access Profiles](/configuration/restriction_policies/access_profiles) and content filters. It does not block by itself.
This is the only section that can answer whether a response is actually an executable, an archive, or an image — Request Types, which only ever sees the outbound request, cannot determine that, because the true nature of a response is only knowable once the destination has replied. A security administrator who wants to block downloads by actual file type, not by what the URL merely suggests, depends on this section for that label.
## Core mechanics
### Two-pass evaluation
1. On response headers — response profiling runs with no body buffer.
2. On buffered body — hook runs again with detected MIME and size.
Every matching enabled row applies; no first-match stop.
```mermaid theme={null}
flowchart TB
headers[Response headers received] --> pass1[First pass profiles response with no body buffer]
pass1 --> buffer[Body buffered with detected MIME and size]
buffer --> pass2[Second pass profiles again with detected MIME and size]
pass2 --> walk[Walk enabled rows top to bottom]
walk -.-> quirk[Multipart and byterange controls in the UI have no effect in the code]
walk --> gate{Content size and MIME and extension gates pass?}
gate -->|Yes| tag[Add or remove Response Types tags]
gate -->|No| next[Next row]
```
The **multipart** and **byterange** controls appear in the row form but are reported by the
legacy documentation as having no effect in the code — they are stored and never read. Do not
build a policy that depends on either one.
**Missing:** this is a legacy-source claim that has not been reproduced by a live test on the
current build, unlike the comparable Speed Limits **Action** field. Treat it as a reason to
avoid depending on these two controls, not as a confirmed defect, and escalate to the SME
before quoting it to a customer.
### Content size
Non-zero min/max tested against body buffer size when present, and against Content-Length when CL flag set. Zero disables each test.
### MIME and extension
MIME regex tries response Content-Type header, then detected body type. Extension regex tries URL (query stripped), then attachment filename.
## Schema Fields
### Global
* **Enabled** (`enabled`) — off, no labels are added or removed here at all.
### Response Types entry
* **Enabled** (`enabled`), **Comment** (`comment`) — standard entry controls.
* **Trace Entry** (`profile_tracing`) — logs each label this entry adds or removes.
* **Response Types** (`res_types`) — gates on a label an earlier entry already applied; supports `!` negation, blank ignores the gate.
* **Content type** (`mime`) — tried against the actual Content-Type header first, then against a body-detected type if that doesn't match. Skipped if neither is available.
* **File Extension** (`file_extension`) — tried against the request URL path with the query string removed first, then against the response's attachment filename from a Content-Disposition header.
* **Transfer Encoding Chunk** (`transfer_encoding_chunk`) — YES applies only to a chunked response, NO only to non-chunked, ANY ignores chunking.
* **Minimum / Maximum Content Size** — see [Content size](#content-size) above.
* **Response header pattern** (`responseheader`) — a regular expression against raw response headers; skipped if raw headers are unavailable.
* **Added / Removed Response Types** (`add_res_types` / `remove_res_types`) — Removed runs after Added on the same entry.
A Response Types-driven DENY in Access Profiles blocks the download by exactly the same mechanism as a request-side DENY — the same HTTP 451 block — not a weaker or partial block. This holds even in a buffered-response configuration, where SafeSquid may already have retrieved the full body from the destination before the client-side block is applied.
## Examples
Open **Configure → Custom Settings → Response Types**. Row fields are Enabled, Comment, Trace
Entry, **Content type** (the MIME-pattern field referenced below), Transfer Encoding Chunk,
Minimum/Maximum Content Size, and Added Response Types.
![SafeSquid console showing Response Types rows with the Content type regex field, the Edit Policies icon on the first row circled]()
### Text for keyword filter
**Config:** MIME `(^text/|script$)`, add `text_res`.
**Result:** HTML/JS/text responses tagged.
### Images
**Config:** MIME `^image/`, add `image_res`.
**Result:** image Content-Types tagged for image filter policies.
### Large images
**Config:** MIME `^image/`, min size 1048576, add `large-image`.
**Result:** skipped below 1 MiB; tagged at or above threshold.
## How to verify
1. **Trace Entry**; fetch test URL; check native logs.
2. Detailed logs — `response_profiles`, `download_content_types`.
3. To confirm a Response Types DENY blocks as strongly as a request-side DENY, trigger one against a large download and verify the client's transfer is cut off with the HTTP 451 page, even though SafeSquid may have already retrieved some or all of the body from the origin in a buffered configuration.
## Next steps
* **[Access Profiles](/configuration/restriction_policies/access_profiles)** - decide what each user can fetch by combining time, request type, response type, category, and group labels into ordered allow and deny rules.
# Suggested Profiles
Source: https://docs.safesquid.com/configuration/custom_settings/suggested_profiles
Legacy reference: the autocomplete catalog of ready-made profile names in the Web UI. This section is not in the current Configure console.
# Pick From Suggested Profile Names
**This section does not appear in the Configure console.** Verified 2026-09-04 against `http://safesquid.cfg`, build `2026.0627.1344.3`: the section is absent from the console's own section registry, not merely hidden from the menu. It is kept here as legacy and reference material, not a current UI path. Confirm against your own build before pointing an administrator at it.
**Suggested Profiles** is a curated catalog of ready-made names and short descriptions that the Web UI offers as autocomplete suggestions across Profiles-style fields throughout the product. It is a **UI-only** naming aid — no C++ section loads this configuration at runtime.
This section's catalog is not limited to cookie policy. It provides fourteen separate suggestion lists that feed autocomplete for Profiles-style fields across Access Profiles, Access restrictions, HTTPS Inspection, ClamAV, Text analyzer, Redirect, Image analyzer, DLP, Time Profiler, Cookie Filtering, Header Filtering, Elevated Privacy, Speed Limits, Network, and Request Types. Cookie profile tags — the only catalog documented in Subsections and Entry fields below — are one of the fourteen. See "The fourteen suggestion catalogs" below for the full set.
To enforce cookie behaviour, configure [Cookie filter](/configuration/restriction_policies/privacy_control/cookie_filter) and reference the same tag names in [Access Profiles](/configuration/restriction_policies/access_profiles) where `cookie_profiles` is used.
## What it does and does not do
Does:
* Populate autocomplete suggestions for Profiles-style fields across all fourteen catalogs below — Access Profiles, Access restrictions, HTTPS Inspection, ClamAV, Text analyzer, Redirect, Image analyzer, DLP, Time Profiler, Cookie Filtering, Header Filtering, Elevated Privacy, Speed Limits, Network, and Request Types.
* Document, in each suggestion's own description, which Web UI field and which kind of entry is expected to produce or consume that name.
Does not:
* Enforce anything on its own — it appears nowhere in the request-processing path. Enforcement always comes from the section whose entries you configure using these names.
* Restrict you to only these names — every Profiles-style field elsewhere accepts free text. This catalog is a convenience, not a whitelist.
* Require every suggested name to be used — an unused suggestion has no effect of any kind.
## Subsections
* **Default Policies** — Suggested starting entries under **Suggested cookie profile tags**. Each row defines an example tag name (for example `READ ONLY`) for the Web UI picker.
## Entry fields
* **Enabled** — UI-only row visibility in the suggested list. Does not affect proxy behaviour.
* **Comment** — Label shown in the Cookie Filtering profile-tag picker.
* **Suggested cookie profile tags** — Example tag name for the dropdown. Pair with deny rows under Cookie filter and Access Profiles `cookie_profiles`.
## The fourteen suggestion catalogs
Each catalog is tied to one Web UI field elsewhere in the product. Fields accept free text — the catalog is a naming convention, not a whitelist. An unused suggestion has no effect of any kind.
### Network Settings (`network_settings_profiles`)
Feeds: the Access Profiles field on **Network → Interface** entries.
* **ALTERNATE OUTBOUND IP** — pair with a Network Interface entry so outbound connections for matching traffic bind to a specific source IP (or rotate among several), instead of the default outbound address.
### HTTPS Inspection (`https_inspection_profiles`)
Feeds: the Profiles field on **HTTPS Inspection → Scan policies** entries.
* **BYPASS SSL INSPECTION** — pair with a scan policy entry that has deep scanning off, so matching HTTPS connections are tunneled through untouched.
* **BYPASS SELF-SIGNED CERT ERROR** — pair with a scan policy entry configured to tolerate self-signed certificate errors.
* **BYPASS NO ISSUER CERT LOCALLY ERROR** — pair with a scan policy entry configured to tolerate an incomplete or locally-untrusted certificate chain.
### ClamAV (`clamav_profiles`)
Feeds: the Profiles field on **Clam antivirus** policy entries.
* **BYPASS CLAMAV SCANNING** — keep this profile off scan entries (or exclude it explicitly) so matching connections are not scanned.
* **ENFORCE CLAMAV SCANNING** — pair with a Clam antivirus entry so matching connections' buffered uploads and downloads are sent to the antivirus engine. A positive detection blocks with that entry's template.
### Text Analyzer (`text_analyzer_profiles`)
Feeds: the Profiles field on **Text analyzer** keyword-scoring entries.
* **BYPASS TEXT FILTER** — keep this profile off keyword-scoring entries (or exclude it explicitly) so matching connections' response bodies are not scored for keyword content.
### Redirect (`redirection_profiles`)
Feeds: the Profiles field on **Redirect** entries.
* **ENFORCE BING SAFE SEARCH** — pair with a Redirect entry matching Bing search requests, rewriting or redirecting to the safe-search variant.
* **ENFORCE GOOGLE SAFE SEARCH** — same idea for Google search requests.
* **ENFORCE YOUTUBE SAFESEARCH** — same idea for YouTube search requests.
* **ENFORCE YAHOO SAFE SEARCH** — same idea for Yahoo search requests.
* **ENFORCE DUCKDUCKGO SAFE SEARCH** — same idea for DuckDuckGo search requests.
### Image Analyzer (`image_analyzer_profiles`)
Feeds: the Profiles field on **Image analyzer** entries.
* **BYPASS IMAGE FILTER** — pair with an image-analyzer entry that has scanning bypassed, so matching image responses skip buffering and content scoring.
* **ENFORCE PARANOID IMAGE SCAN** — pair with an image-analyzer entry with scanning enabled and a strict threshold, so matching image responses at or above the threshold are blocked (or blurred in a debug/testing mode).
### DLP (`dlp_profiles`)
Feeds: the Profiles field on **DLP** entries.
* **ALLOW ALL UPLOADS** — pair with a DLP entry set to Allow for a broad upload pattern.
* **BLOCK UPLOADS** — pair with a DLP entry set to Deny (or DO NOT BYPASS) for a broad upload pattern.
* **ALLOW SPREADSHEET DOCUMENT UPLOAD** — pair with a DLP Allow entry whose upload content-type pattern matches spreadsheet formats.
* **ALLOW WORD DOCUMENT UPLOAD** — pair with a DLP Allow entry matching word-processor document formats.
* **ALLOW POWERPOINT DOCUMENT UPLOAD** — pair with a DLP Allow entry matching presentation document formats.
* **ALLOW PDF FILE UPLOAD** — pair with a DLP Allow entry matching PDF uploads.
* **ALLOW ZIP FILE UPLOAD** — pair with a DLP Allow entry matching archive/compressed-file uploads.
* **ALLOW IMAGE FILE UPLOAD** — pair with a DLP Allow entry matching image uploads.
* **ALLOW BASIC TEXT POSTS** — pair with a DLP Allow entry matching plain textual content types (JSON, HTML, plain text, or XML form submissions).
### Time Profiler (`time_profiler_profiles`)
Feeds: **Time Profiler** entries, and in turn any Time Schedule matching in Access Profiles or Speed Limits.
* **LUNCH** — a Time Profiler entry with the matching clock window adds this profile during that window. Other sections' Time Schedule fields match on it like any other Profiles field.
* **OFFICE WORKING HOURS** — same mechanism, for a working-hours window.
### Cookie Filtering (`cookie_profiles`)
Feeds: **Cookie filter** deny entries, and the matching field elsewhere. This is the catalog documented in Subsections and Entry fields above.
* **READ ONLY** — pair with a Cookie filter deny entry so that, when this profile is present and the entry's domain/path/expiry conditions match, outbound cookies are blocked — the user retains no login state for that site.
### Header Filtering (`header_filter_profiles`)
Feeds: **Header Filtering → Insert** entries, and (for RBI) the block outcome on **Access Profiles** entries.
* **ENFORCE CORPORATE GOOGLE ACCOUNTS** — pair with a Header Filtering Insert entry adding the header Google Workspace uses to prefer your organization's accounts.
* **ENFORCE YOUTUBE RESTRICTED MODE** — pair with a Header Filtering Insert entry adding YouTube's restricted-mode header to requests toward YouTube.
* **MINIMAL CONTENT ACCESS** — pair with a Header Filtering Insert entry adding a strict Content-Security-Policy response header, tightly limiting what a page may load or execute.
* **STANDARD CONTENT ACCESS** — a less restrictive Content-Security-Policy than Minimal, permitting connections back to your own organization's domain while still restricting most other content sources.
* **FULL CONTENT ACCESS** — pair with a Header Filtering entry that removes the Minimal Content Access restriction once a connection is confirmed trusted.
* **DROP ORIGINAL CSP** — pair with a Header Filtering entry that strips a response's own Content-Security-Policy header before any of the profiles above apply. Without this, the browser merges the site's own policy with yours — usually a *more* restrictive result than intended.
* **RBI** — routes a connection into Remote Browser Isolation: an Access Profiles entry that denies the connection while adding this profile (typically paired with DROP ORIGINAL CSP) serves the isolated-browsing page instead of the standard block page. It is listed under Header Filtering as the closest fit, since it is really a routing profile rather than a header or content-policy transform.
### Elevated Privacy (`elevated_privacy_profiles`)
Feeds: the Profiles field on **Elevated Privacy** entries.
* **BYPASS ELEVATED PRIVACY** — pair with an Elevated Privacy entry set to a not-required privacy level, so matching connections get no cookie, referrer, or user-agent stripping on cross-site traffic.
* **ENFORCE LOW PRIVACY LEVEL** — pair with an Elevated Privacy entry set to its low level, which removes third-party cookie headers on cross-site requests and responses.
* **ENFORCE PARANOID PRIVACY LEVEL** — pair with an Elevated Privacy entry set to its strictest level: low-level behavior plus stripping Referer, Origin, and User-Agent on client requests — this can break content that depends on browser identification.
### Speed Limits (`speed_limits_profiles`)
Feeds: the Profiles field on **Speed Limits** entries.
* **RESTRICTED DOWNLOAD TRANSFER RATES** — pair with a Speed Limits entry that sets a non-zero Download rate. The lowest matching rate across all matching entries applies.
* **RESTRICTED UPLOAD TRANSFER RATES** — pair with a Speed Limits entry that caps upload bytes or other upload-side limits. Multiple matching entries can contribute stricter caps together.
### User/Group suggestions (`suggested_user_group`)
Feeds: **Add to User-Groups** on Access restrictions entries. This one list splits into three groupings in the Web UI:
**Suggested: User Group** (organizational roles):
* **ACCOUNTANTS** — finance and accounts-payable staff. Commonly paired with DLP Allow-Upload profiles for spreadsheets, word-processor documents, and PDFs, rather than default upload restrictions.
* **IT SUPPORT TEAM** — helpdesk and infrastructure staff. Commonly paired with bypass-style profiles (HTTPS Inspection, ClamAV, Elevated Privacy) so diagnostic traffic isn't altered.
* **HR TEAM** — Human Resources staff needing access to recruitment portals, background-check services, and personal data, balanced with stricter DLP controls on uploads.
* **C-SUITE** — top executives. Often exempted from generic content restrictions. But also the organization's highest-value phishing target — many deployments pair this with stricter anti-spoofing or header-filtering profiles rather than a blanket bypass.
* **DEPARTMENT HEADS** — mid-level managers: broader access than individual contributors, without the targeted-attack profile C-Suite gets.
* **MARKETING TEAM** — marketing/communications staff needing access to social media, advertising platforms, and analytics tools normally blocked by default.
* **LEGAL TEAM** — legal and compliance staff needing access to litigation research, e-discovery, and regulatory sites — frequently paired with elevated audit or trace-entry logging rather than a content bypass.
* **DEVELOPERS** — engineering staff needing access to code repositories, package registries, and developer documentation sites.
* **CONTRACTORS** — temporary or third-party staff, scoped more narrowly and monitored more closely — typically paired with stricter DLP and Elevated Privacy profiles than employees get.
* **BYOD USERS** — authenticated staff on personal devices — often paired with stricter DLP and content controls than a managed device gets.
**Suggested: Permissions Group** (browsing-activity permissions):
* **YOUTUBE USERS** — users exempted from the default YouTube restricted-mode policy.
* **PERMITTED PERSONAL GOOGLE ACCOUNT** — users allowed to sign in to a personal Google account on the corporate network, exempted from the corporate-accounts-only policy.
* **SOCIAL MEDIA PERMITTED** — users allowed access to social media platforms normally blocked for general staff.
* **GENERATIVE AI TOOLS PERMITTED** — users permitted to access generative-AI assistants where the organization otherwise restricts them. Kept as one durable category name rather than a specific product, since which tools are in use changes faster than policy should.
* **PERSONAL CLOUD STORAGE PERMITTED** — users allowed to upload to personal cloud-storage accounts — a common DLP exception weighed against exfiltration risk for everyone else.
**Suggested: System Access** (operational exemptions):
* **USER\_AUTHENTICATION\_BYPASSED** — for applications that cannot complete a proxy-authentication challenge. A default configuration typically grants this User-Group from an Access restrictions entry matching a bypass-authentication Access Profile, with System authentication off.
* **TUNNELLED\_UI\_ACCESS** — for administrators reaching the Web interface over a local loopback tunnel (for example, an SSH port-forward) rather than directly from a LAN address.
* **PROXY\_SLAVES** — for peer SafeSquid instances in a master/slave cluster, permitted configuration-only access to synchronize policy. Restrict the corresponding Access restrictions entry's IP Address field to the actual slave instances — never leave it open to any address.
### Request Type (`suggested_request_type`)
Feeds: the Request Types field on Request Types **Domains and Urls** entries, and Request Types matching elsewhere.
* **Taxation Regulatory Sites** — tax regulatory websites.
* **RBI ONLY** — hosts routed to Remote Browser Isolation instead of direct access. Add this Request Type to a Domains and Urls entry (and turn its DNS-blacklist check off, since the host list already reflects a manual risk judgment) to feed an RBI-routing Access Profiles entry.
* **Authorized Software Sources** — IT-approved software vendor or update sites, exempted from a Response Types download restriction that applies to everyone else.
## Examples
### READ ONLY cookie hint
* Suggested Profiles lists `READ ONLY`
* Cookie filter Deny row uses cookie profile tag `READ ONLY` for outbound cookies you want blocked
* Access Profiles assigns users the matching `cookie_profiles` tag
**Result:** the suggestion is only a naming aid. Effective block comes from Cookie filter + Access Profiles, not from Suggested Profiles alone.
### Naming a custom DLP exception consistently
**Config:** a DLP Allow entry for spreadsheet uploads uses the suggested Profiles value `ALLOW SPREADSHEET DOCUMENT UPLOAD` from the DLP catalog instead of an invented name. Separately, an Access Profiles entry adds that same profile to Accountants' connections.
**Result:** the two entries agree on the exact same name, so the DLP exception reliably applies to Accountants' connections. The suggestion itself did nothing — the DLP entry and the Access Profiles entry are what make it work.
### Onboarding a new CONTRACTORS User-Group
**Config:** an Access restrictions entry's Add to User-Groups field uses the suggested value `CONTRACTORS` (from Suggested: User Group) for connections matching a contractor LDAP group. Elsewhere, DLP and Elevated Privacy entries are configured to require the `CONTRACTORS` User-Group.
**Result:** any new contractor added to the matching LDAP group automatically picks up the stricter DLP and Elevated Privacy handling, because every entry involved agreed on the same User-Group name from the start.
## How to verify
1. Open the Profiles-style field on the section you're configuring (for example, Cookie filter's Deny row, or DLP's Profiles field) and confirm the suggested name you expect appears in its autocomplete list.
2. Remember that picking a suggestion changes nothing by itself — after selecting it, configure the entries on both the producing side (the entry that adds the profile or User-Group) and the consuming side (the entry that requires it).
3. Reproduce a request that should pick up the suggested name and check **Reports → Detailed logs** to confirm the profile or User-Group is actually present on that connection. For the cookie-filter case specifically: configure a Deny row and Access Profiles `cookie_profiles` with the same tag, then reproduce a request with matching cookies — Suggested Profiles alone produces no log lines.
## Next steps
* [Cookie filter](/configuration/restriction_policies/privacy_control/cookie_filter)
* [Access Profiles](/configuration/restriction_policies/access_profiles)
* [Architecture](/configuration/start_here/architecture)
# Templates
Source: https://docs.safesquid.com/configuration/custom_settings/templates
Configure the block pages and error bodies SafeSquid serves when it denies traffic or returns an error.
# Customize Block and Error Pages With Templates
The **Templates** section configures block pages and error bodies served when SafeSquid denies traffic or returns configured errors. Other sections never embed page content themselves. They ask Templates for a page by name (for example a block page named `blocked`). This section resolves the name to a file. That indirection is what lets you replace default block pages with branded versions without touching the sections that trigger them.
## Core mechanics
### Resolution order
1. Walk configured rows top-down.
2. Skip disabled or empty Name.
3. **Profiles** gate must pass (blank = any).
4. Case-insensitive Name match — **first match wins**.
5. Else built-in `PAGES[]` defaults.
6. Else log undefined template error.
```mermaid theme={null}
flowchart TB
walk[Walk configured rows top down] --> validRow{Row enabled and Name non-empty?}
validRow -->|No| walk
validRow -->|Yes| profiles{Profiles gate passes?}
profiles -->|No| walk
profiles -->|Yes| nameMatch{Name matches case-insensitively?}
nameMatch -->|No| walk
nameMatch -->|Yes| firstMatch[First match wins]
firstMatch --> type{Type}
type -->|FILE| cached[Serve preloaded file]
type -->|EXECUTABLE| run[Run executable for stdout response]
cached --> parsable{Parsable on?}
parsable -->|Yes| substitute[Substitute template variables]
parsable -->|No| send[Send as-is]
walk -->|No rows left| builtin{Built-in PAGES default exists?}
builtin -->|Yes| useDefault[Use built-in default]
builtin -->|No| error[Log undefined template error]
```
### FILE vs EXECUTABLE
* **FILE** — Preloaded at config load from Name path or File fallback. MIME blank → `application/octet-stream`.
* **EXECUTABLE** — Run at send time; stdout must be HTTP response (`ENABLE_EXTERNAL` required).
### Send
The block template uses the caller status or the row Response code. Adds `X-SafeSquid-Template` header. HTML built-ins may inject stylesheet.
## Schema Fields
Templates has no section-wide global setting — every field lives on the entry.
* **Enabled** — when off, this entry is ignored when SafeSquid resolves a template name.
* **Comment** — an operator note; does not affect matching or behavior.
* **Profiles** — blank matches every connection; when several entries share a Name, the first enabled entry whose Profiles match wins.
* **Name** — case-insensitive match against the requested name; a blank Name is always skipped.
* **File** — a relative path resolves under the templates directory.
* **Mime type** — blank defaults to a generic binary type for a FILE entry. For EXECUTABLE, Content-Type comes from the program's own response instead.
* **Response code** — zero means SafeSquid uses whatever status the triggering event supplied, or a built-in default if none was given — this makes explicit the zero-case behind the Send section's "caller status or row Response code" statement above.
* **Type** — FILE or EXECUTABLE; see FILE vs EXECUTABLE above for the behavior difference.
* **Parsable** — on: `%variable%` placeholders substituted with connection details before sending; off: bytes sent as-is.
## Routing a block into an isolated session
SafeSquid can route a denied user into an isolated browsing session instead of a dead-end block page. This is a three-part chain across three sections, with Templates supplying the final piece:
1. A curated domain list in Request Types marks isolation-worthy hosts with a dedicated Request Type. The built-in catalog's example is named **RBI ONLY**.
2. An Access Profiles entry matches that Request Type, sets Action to Deny, and additionally adds an isolation Profile (the built-in catalog's example is named **RBI**). The connection is still denied, but now carries a marker for special handling.
3. A Templates entry gated to that isolation Profile maps the block to a dedicated isolation-session page instead of the generic block page. This is the step that actually routes into the isolated session.
For the isolation page to render cleanly, pair the isolation Profile with one that strips the response's own Content-Security-Policy first (the built-in catalog's example is named **Drop Original CSP** — see [Header filter](/configuration/restriction_policies/privacy_control/header_filter), which documents the CSP-merge behavior), and give the isolation service's own domain its own Access Profiles entry allowing it through, or the isolated session itself gets blocked before it loads.
## Examples
Open **Configure → Custom Settings → Templates → Manage templates**. Row fields are Enabled,
Comment, Name, File, Mime type, Response code, Type, and Parsable — the built-in `blocked` and
`error` templates ship enabled by default.
![SafeSquid console showing the Manage templates list with the built-in blocked and error templates, the Edit Policies icon on the first row circled]()
### Branded block page
**Config:** Name `company-block`, FILE, Parsable on, code 403.
**Result:** Access Profiles Deny serves HTML with substituted variables.
### Profile-specific block
**Config:** two rows same Name `block`; row A Profiles `staff` above row B blank profiles.
**Result:** staff connections get staff template first.
### Falling back to a built-in default
**Config:** no entry configured for a name like `error`.
**Result:** SafeSquid serves its own compiled-in default page rather than failing with no response at all.
### Executable template
**Config:** Type EXECUTABLE, File pointing to a small server-side script, Parsable off.
**Result:** at send time SafeSquid runs the script and forwards whatever HTTP response it prints to standard output — useful for a block page that needs to look something up dynamically before rendering.
## How to verify
1. Trigger block referencing template name.
2. DEBUG + TEMPLATE native logs.
3. Check `X-SafeSquid-Template` response header.
4. Check native logs for "template not found" errors after a configuration change.
5. A file changed on disk after the configuration was last applied needs a configuration reload before a FILE entry picks up the change.
## Related sections
* Access Profiles — a Deny action invokes a block template by name.
* [Header filter](/configuration/restriction_policies/privacy_control/header_filter) — the Drop Original CSP pattern that keeps an isolation or block page's own CSP from merging incorrectly with the destination's.
# Time Profiler
Source: https://docs.safesquid.com/configuration/custom_settings/time_profiler
Tag connections with time labels from the appliance clock so Access Profiles can apply policy by weekday and time of day.
# Apply Policy by Time With the Time Profiler
The **Time Profiler** section tags connections with time labels from the appliance local clock. [Access Profiles](/configuration/restriction_policies/access_profiles) **Time Schedule** matches these tags. Every enabled entry that matches applies — this is not first-match-wins — and a later entry's condition can even depend on a label an earlier entry just added. Time Profiler runs early in request processing, before Request Types and Access Profiles. So its labels are already available by the time those sections evaluate the connection.
## Core mechanics
### Row gate order
1. **Time Profiles** prerequisite tags (`profile_find`).
2. **Weekday range** — always enforced (Sunday = 0 … Saturday = 6).
3. **Match mode** — ABSOLUTE timestamp window or ALL RANGES (month + day + minutes-from-midnight).
4. Add/remove time labels — Added Time profiles apply before Removed Time profiles on the same entry.
```mermaid theme={null}
flowchart TB
clock[Read appliance local time once] --> prereq{Time Profiles prerequisite tags present?}
prereq -->|No| skip[Row skipped]
prereq -->|Yes| weekday{Current weekday in configured range?}
weekday -->|No| skip
weekday -->|Yes| mode{Match mode}
mode -->|ABSOLUTE| abs{Timestamp within abs_from and abs_to?}
mode -->|ALL RANGES| all{Month and day and minute-of-day all in range?}
abs -->|Yes| apply[Add or remove time labels]
abs -->|No| skip
all -->|Yes| apply
all -->|No| skip
```
**Weekday active flag** is stored but not checked — weekday bounds always apply. Set explicit 0–6 or 1–5 ranges; template default 0 alone matches Sunday only.
**A backwards hour range matches nothing.** If the configured start hour is later than the end hour (for example 17 to 9, intending "evening through morning"), the resulting time-of-day window can end up empty rather than wrapping past midnight. The entry silently never matches. Split an overnight window into two entries instead: one from the start hour to 23:59, one from 00:00 to the end hour.
### Match modes
* **ABSOLUTE** — Single start/end timestamp from configured month, day, hour, minute fields.
* **ALL RANGES** — Current month, day-of-month, and time-of-day must each fall in inclusive windows.
## Schema Fields
### Global fields
* **Enabled** — off: no labels are added or removed for any connection, and downstream Time Schedule matching has nothing to see.
### Entry fields
* **Enabled (`enabled`)** — disabled entries are skipped entirely.
* **Comment (`comment`)** — an operator note describing why this entry exists.
* **Trace Entry (`profile_tracing`)** — logs each label this entry adds or removes to native logs.
* **Time Profiles (`timeprofiles`)** — a prerequisite gate on a label from an earlier entry; `!` negation supported; blank ignores it.
* **Month range**, **Day range**, **Weekday range**, **Hour range**, **Minute range** — inclusive bounds. Combine into one minutes-since-midnight window in ALL RANGES mode, or all five together build the single start/end timestamp in ABSOLUTE mode.
* **Time match mode** — see Match modes above.
* **Added Time profiles** / **Removed Time profiles** — labels attached or taken off the connection when this entry matches.
## Layering Time Profiles
Because every matching entry applies, a specific label can be built from a general one across several entries. An early entry adds a broad label like `weekend`, a later entry restricts itself to connections already carrying `weekend` in its own Time Profiles field and adds a narrower label like `weekend-evening` on top. This lets Access Profiles gate on the specific label without repeating the weekday/hour logic downstream.
## Examples
Open **Configure → Custom Settings → Time Profiler → Time profiles**. Row fields are Enabled,
Comment, Trace Entry, Month/Day/Weekday/Hour/Minute range, Time match mode, and Added Time
profiles.
![SafeSquid console showing Time profiles rows for office hours and lunch window, the Edit Policies icon on the first row circled]()
### Business hours
**Config:** Weekday Mon–Fri, hours 9–17, ALL RANGES, add `business-hours`.
**Result:** tag present weekdays 09:00–17:59 local time.
### Lunch window
**Config:** Weekday 1–5, hours 12–13, add `LUNCH_TIME`.
**Result:** Access Profiles can Allow/Deny based on lunch tag.
### Absolute maintenance window
**Config:** Time match mode ABSOLUTE, month/day/hour/minute fields set to a specific weekend's start and end, Added Time profiles `maintenance`.
**Result:** suited to a one-time exception rather than a recurring weekly pattern.
### Layering a narrower label on a broader one
**Config:** entry A adds `weekend` on weekend days. Entry B below it, gated on `weekend` as a prerequisite, adds `weekend-evening` during evening hours.
**Result:** Saturday-night traffic carries both labels.
## How to verify
1. Test inside and outside window with **Trace Entry**.
2. Detailed logs `time_profiles` column.
3. Confirm appliance timezone and clock.
## Next steps
* **[Access Profiles](/configuration/restriction_policies/access_profiles)** - decide what each user can fetch by combining time, request type, response type, category, and group labels into ordered allow and deny rules.
# Subscription
Source: https://docs.safesquid.com/configuration/infrastructure_and_access/subscription
See how subscription state decides whether SafeSquid treats the licence as valid and runs update feeds and signature modules.
# Check How Subscription State Affects SafeSquid
Subscription state controls whether the appliance considers its licence valid, and therefore whether update feeds and signature modules can run. It defines no proxy policy rows of its own. SafeSquid re-checks subscription validity on every request, not once at startup. This is a per-request check, not a one-time state.
This is the on-appliance side of licensing only — it reflects the key you already hold. To register an account or obtain a new activation key, see [Support](/configuration/infrastructure_and_access/support) for where that key comes from on `key.safesquid.com`.
## Where subscription state appears
The authoritative view is the **License Details** panel on the **Support** page, reached from the top navigation bar next to **Configure**. Verified 2026-09-04 against build `2026.0627.1344.3`.
There is no Subscription section under **Configure**, and no licence or module-status tab under **Reports**.
## License Details fields
The panel is read-only apart from a **Refresh** control.
| Field | What it shows |
| - | - |
| Activation Key Name | Name of the activation key registered on the appliance |
| Subscription Start | Date the current subscription began |
| Creator Details | Account that created the key |
| Contact Details | Contact address on the subscription |
| Status | Current subscription state, for example `ACTIVE` |
| Service ID | Identifier of the subscribed service |
| Service Name | Name of the subscribed service |
| Subscription Type | Basis the subscription is metered on, for example `CPU usage` |
| Remaining Subscription Quantity | Entitlement left against the metered basis |
| Service Location | Location recorded against the service |
| Last Updated Time | When the appliance last refreshed this data |
## How subscription affects the proxy
1. On each request, SafeSquid sets or clears `SUBSCRIPTION_EXPIRED` on the connection from subscription validity checks.
2. When expired, [Application Signatures](/configuration/custom_settings/application_signatures) processing is skipped for that connection and security logging records filter `subscription`.
3. Background subscription accounting talks to the vendor service, refreshes entitlement, and drives scheduled update hooks (signatures, categorisation feeds, trusted CA updates, and similar).
4. At certain points while a request is being processed, an expired subscription can occasionally interrupt it with a renewal notice instead of the normal response — not on every request, and not a permanent block, since browsing continues normally in between. The same mechanism can also interrupt Image analyzer processing specifically.
**Missing:** whether an expired subscription also skips Header filter processing, alongside the confirmed Application Signatures skip above. Legacy documentation claims it does, but the live Header filtering console section has no mention of subscription or expiry anywhere. The condition cannot be reproduced without an actually-expired licence. Escalate to engineering for a source-level answer before documenting this as behaviour.
An expired subscription is not the same as Access restrictions DENY — users may still connect while signature-dependent labelling and some update paths stop. Check the Support page's License Details panel and Native SECURITY logs when behaviour changes after expiry.
## Renewing an activation key
**Missing:** the on-appliance step for installing a renewed activation key. No upload control for one was found in the current build's console. So the procedure below is not documented here rather than guessed at. Obtain the renewed key from [key.safesquid.com](https://key.safesquid.com), then confirm the installation path with SafeSquid support for your build before a renewal window.
Once a renewed key is in place, confirm it took effect:
1. Open **Support → License Details** and select **Refresh**.
2. Check that **Status** and **Subscription Start** reflect the new subscription.
3. Confirm application signature tags apply again on new connections.
**Expected result:** `SUBSCRIPTION_EXPIRED` clears on new connections and signature-dependent labelling resumes.
## How to verify
1. **Support → License Details** for subscription status, then **Refresh** to pull current state.
2. Native SECURITY logs for `subscription: expired` on test requests.
3. Application signature stats after a successful update cycle.
Legacy documentation references a "Modules Status" report showing signature and feed load
status. No such tab exists in build `2026.0627.1344.3` — a DOM sweep of both the Reports and
Support views found no occurrence (verified Reports tabs: Dashboard, Statistics, Native logs,
Detailed logs, Config logs, Active Connections, Connection Pool, DNS Cache, LDAP Entries,
Password Cache; verified Support cards: Support Tarball, Download Config, Upload Config,
Upgradation, Performance Plot, URL Commands, Restart SafeSquid, Cloud Restore, Startup params,
Live Support). Use Native logs and the update-hook logs referenced in
[Cloud / categorisation feeds](/configuration/start_here/cloud_feeds) instead.
## Next steps
* [Support](/configuration/infrastructure_and_access/support) — License Details panel and appliance tools
* [Register and get your key](/getting_started/register)
* [Handle expiry](/deployment/manage_subscription_state)
* [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds)
* [Application Signatures](/configuration/custom_settings/application_signatures)
* [Logging](/configuration/start_here/logging)
# Support
Source: https://docs.safesquid.com/configuration/infrastructure_and_access/support
Check the appliance's license state and use on-appliance tools for restart, configuration backup, upgrade, and vendor support.
# Check Licence State and Use On-Appliance Support Tools
**Support** is the top-nav page next to Configure (not under Reports). It shows local license
state and exposes appliance-level operational tools — restart, config backup, upgrade, and
vendor support — none of which are policy sections.
This page is the **on-appliance** counterpart to [key.safesquid.com](https://key.safesquid.com),
SafeSquid's external licensing portal (see [Register and get your key](/getting_started/register)
and [Self-Service Portal](/architecture/interface/self_service_portal)). The two are easy to
conflate: `key.safesquid.com` is where you get and manage an activation key; this Support page is
where you see that key's status on this appliance and use appliance tools tied to it (Cloud
Restore in particular reads from the cloud account behind your key).
## License Details panel
The left panel shows the fields SafeSquid tracks for the current activation key:
| Field | Shows |
| - | - |
| Activation Key Name | The key identifier |
| Subscription Start | Activation date |
| Creator Details | Account email that owns the key |
| Contact Details | Account contact email |
| Status | `ACTIVE` or otherwise |
| Service ID | Instance identifier |
| Service Name | Operator-set label |
| Subscription Type | Billing basis (for example CPU usage) |
| Remaining Subscription Quantity | Time or usage left on the plan |
| Service Location | Operator-set label |
| Last Updated Time | Last sync with the licensing backend |
Click **Refresh** to re-pull this panel from the licensing backend without waiting for the next
scheduled sync — use this right after uploading a new activation key or renewing on
`key.safesquid.com`.
This is the authoritative place to check subscription/license status in the Web UI. It is not
under Reports — no Reports tab covers it.
Open **top nav → Support**. The License Details panel is not screenshotted here — it shows this
appliance's real activation key, contact email, and Service ID.
![SafeSquid console Support page showing the ten operational tool cards with Restart SafeSquid circled]()
## Operational tools
Ten cards, right of the License Details panel. Descriptions below are what each card states or
does on open; where a card's underlying behavior needs more than its stated purpose, that's
flagged rather than guessed.
* **Support Tarball** — "Download or Generate." Produces a support bundle for the vendor.
* **Download Config** — "Download Config Files."
* **Upload Config** — "Upload Config Files."
* **Upgradation** — "Upload New Version." Applies a new SafeSquid build.
* **Performance Plot** — "Application performance."
* **URL Commands** — "Test the Functionalities." Opens a **URL command executor**: pick a
diagnostic mode and a website, then run it through the proxy without changing policy. The
available modes (verified live, exact list): `xx--fresh`, `xx--raw`, `xx--cookies`, `xx--mime`,
`xx--headers`, `xx--score`, `xx--diff`, `xx--htmltree`, `xx--process`, `xx--offline`,
`xx--cache`, `xx--profiles`, `xx--https`, `xx--prefetch`, `xx--template`, `xx--proxytest`,
`xx--bypass`, `xx--password`, `xx--imgscore`, `xx--limits`, `xx--variables`.
* **Restart SafeSquid** — "Restart SafeSquid service." The action referenced by
[Handle expiry](/deployment/manage_subscription_state)'s "restart SafeSquid from the interface
after either action" step.
* **Cloud Restore** — "Restore Configuration." Confirmed live: the dialog states "You can get
configuration file and SSL certificate shared with activation key," with a **Restore** button.
This is the on-appliance side of the Self-Service Portal's backup/restore workflow — it pulls
from the cloud account tied to your activation key, it does not issue a new key.
* **Startup params** — "Edit SafeSquid params." Web UI editor for the same tunables covered in
[startup.ini tunables](/configuration/start_here/startup_ini) — confirm before assuming this
writes the same file directly.
* **Live Support** — "Chat with support." Vendor support chat.
**Card behavior beyond the stated purpose above (Upgradation's version-compatibility checks, what
Support Tarball actually collects, exact Cloud Restore scope) was not exercised this session** —
these are destructive or support-escalating actions and weren't tested live. Confirm scope before
walking an administrator through them for the first time.
## How to verify
1. **Support** page loads with the License Details panel populated (not blank/`YET_TO_DEFINE`
on every field) for an activated appliance.
2. After uploading a new activation key on [Subscription](/configuration/infrastructure_and_access/subscription),
click **Refresh** here and confirm **Last Updated Time** advances.
## Next steps
* [Subscription](/configuration/infrastructure_and_access/subscription)
* [Register and get your key](/getting_started/register)
* [Handle expiry](/deployment/manage_subscription_state)
* [Self-Service Portal](/architecture/interface/self_service_portal)
* [startup.ini tunables](/configuration/start_here/startup_ini)
* [Tools and Reports](/configuration/start_here/tools_and_reports)
# Clam antivirus
Source: https://docs.safesquid.com/configuration/real_time_content_security/clam_antivirus
Scan HTTP traffic for malware in real time by integrating the ClamAV clamd daemon with SafeSquid.
# Scan Traffic for Malware With Clam Antivirus
```mermaid theme={null}
flowchart TB
buffer[Buffer the upload or download body] --> walk[Walk enabled clamav rows top to bottom]
walk --> match{First row Profiles match?}
match -->|No| next[Next row]
match -->|Yes| scan[Stream body to clamd]
scan --> result{clamd result}
result -->|OK| allow[Allow]
result -->|FOUND| block[DO NOT BYPASS block]
block --> templ[Resolve template row then Default then built-in error]
```
## What does this section do?
The `ClamAV` section configures integration with a clamd daemon for real-time malware scanning of HTTP traffic.
Clam antivirus is one of two built-in scan engines. The other is [SqScan](/configuration/real_time_content_security/sqscan), an in-memory scanner that needs no external daemon. Many deployments run both, or add ICAP, for defense in depth.
## Core Mechanics (C++ Source Validation)
Policy walk, results cache.
* **Evaluation Order**: Rules are evaluated top-to-bottom. The first rule whose `Profiles` condition matches the connection is selected, and execution stops.
* **Cache Optimization**: If an object is already stored in the SafeSquid cache and marked as `CACHE_CLEAN`, the ClamAV subsystem will completely bypass scanning to improve performance.
* **Results Caching**: SafeSquid maintains an internal `ResultsCache` to avoid repeatedly sending identical in-memory payloads to clamd.
* **Connection Pool**: A `ClamavPool` mechanism manages idle TCP/Unix sockets to the `clamd` daemon to prevent socket exhaustion during high concurrency.
* **Enforcement**: If a virus is detected, the subsystem immediately changes the connection action to **DO NOT BYPASS**, dropping the payload and returning the configured block template, populating variables like `_VIRUSNAME_`.
## Schema Fields
### Global Fields
* **Enabled (enabled)**: When enabled, SafeSquid scans buffered uploads and downloads through ClamAV. When disabled, scan hooks return immediately and status shows Disabled.
* **ClamAV hostname or socket path (clamavhost)**: TCP hostname or IP of clamd , or absolute Unix socket path starting with / (for example /var/run/clamav/clamd.ctl ). A path uses a local socket; a hostname uses TCP on ClamAV port.
* **ClamAV port (clamavport)**: TCP port for clamd when ClamAV hostname or socket path is a hostname (default 3310). Ignored when the host field is a Unix socket path.
* **Default template (dtempl)**: Template name shown when a virus is detected and the matching policy leaves Template blank. If blank, SafeSquid falls back to the error template after the entry template is checked.
### Rule-Based Fields (Per Connection Tuning)
* **Enabled (enabled)**: When disabled, this clamav row is skipped. First matching enabled row wins.
* **Comment (comment)**: Operator note appended to the filter reason when ClamAV reports FOUND on a matching connection.
* **Profiles (profiles)**: Limit this entry to connections that already carry these Access Profile tags. SafeSquid tests against the connection’s active profiles: blank ignores profiles; a positive tag applies when present; prefix ! applies when absent. With multiple tags, the first list entry that resolves decides (positive match -> apply; negated match -> skip; lone unmatched ! -> apply). ClamAV walks enabled rows top to bottom. The first matching row triggers scanning of buffered uploads and downloads and selects the block template on FOUND . ENFORCE CLAMAV SCANNING Typical tag on a scan row for connections that must be scanned. !BYPASS CLAMAV SCANNING Row applies only when the connection lacks the bypass tag (scan everyone except bypass-tagged users). (blank) Row can match any connection (subject to list order).
* **Template (templ)**: Template name shown when ClamAV blocks this connection. If blank: Default template, then built-in error .
## How SafeSquid processes policies
1. On config reload, SafeSquid tests the `clamd` connection when the section is enabled.
2. For each buffered upload or download part, enabled rows are walked top to bottom.
3. The first row whose Profiles match (and row Enabled is on) triggers a stream scan via `clamd`.
4. ClamAV returns `stream: … FOUND` or `stream: OK`. Only `FOUND` blocks.
5. Template resolution: row Template → Default template → `error`.
**Order matters.** Put specific profile rows above broad catch-all rows. The first match wins; later rows are not evaluated for that connection.
Clam antivirus is first-match-wins — the same evaluation model as Access restrictions. The **opposite** of Access Profiles, which is cumulative. A broad row with a blank Profiles field above a narrower one means the narrower row can never fire for any connection the broad row also matches.
## Bypass and block severity
* Access restrictions **Bypass** with antivirus skips ClamAV entirely for that client.
* When a virus is found, action is **DO NOT BYPASS** (hard block) unless the connection has Allow bypassing and a valid bypass cookie. Then action is **DENY** (soft block with continue option).
## Examples
Open **Configure → Real time content security → Clam antivirus → Global**. Fields are Enabled,
ClamAV hostname or socket path, ClamAV port, and Default template.
![SafeSquid console showing Clam antivirus Global fields with the clamd socket path and virus template, the Edit Policy icon circled]()
### 1 — Scan everyone via local clamd
* Enabled: on
* ClamAV hostname or socket path: `/var/run/clamav/clamd.ctl`
* clamav row: Profiles blank, Enabled on, Template `virus`
**Result:** all buffered uploads and downloads are scanned; infected content is blocked with the virus template.
### 2 — Scan staff, skip guests
* Row A (top): Profiles `!BYPASS CLAMAV SCANNING`, Enabled on
* Row B: Profiles `BYPASS CLAMAV SCANNING`, Enabled off or omitted — guests tagged with bypass never hit row A
**Result:** only connections without the bypass tag are scanned. Row order and profile tags must align with your Access Profiles design.
### 3 — Remote clamd on TCP
* ClamAV hostname or socket path: `10.0.0.20`
* ClamAV port: `3310`
**Result:** SafeSquid opens a TCP stream to `clamd` on the scanner host for each scan.
## Recommended practice
* Keep ClamAV signature databases current on the appliance or scanner host.
* Verify `clamd` is listening before enabling the section (check native ANTIVIRUS logs on reload).
* Use SqScan or ICAP as a second layer if your policy requires defense in depth.
* Grant antivirus Bypass only to break-glass roles.
## How to verify
1. Download the EICAR test file through the proxy from a scanned profile.
2. Open **Reports → Detailed logs**; look for filter name Clam antivirus and a virus name in the reason.
3. Enable ANTIVIRUS and DEBUG log levels for native `clamav:` lines.
4. Dashboard stats show Objects Scanned and Threats Detected when scanning is active.
5) A flat Objects Scanned counter usually means the connection to the scanner, the entry Profiles, or the Access-level Bypass setting needs checking.
## Next steps
* **[SqScan](/configuration/real_time_content_security/sqscan)** - scan uploads and downloads for malware with SafeSquid's built-in in-memory scanner, with no external clamd process.
# Content modifier
Source: https://docs.safesquid.com/configuration/real_time_content_security/content_modifier
Rewrite HTTP headers and bodies with PCRE search-and-replace to inject cookies, strip sensitive header values, or change response content.
# Rewrite Headers and Bodies With the Content Modifier
## What does this section do?
The `Rewrite` section performs PCRE search-and-replace on HTTP headers and bodies. Use it to inject cookies, strip sensitive header values, or modify response body content before it reaches the client.
## Core Mechanics (C++ Source Validation)
### Hook points
* **Client header** — outgoing request headers.
* **Server header** — response headers.
* **Body** — response body during buffering; MIME regex tested against `Content-Type`.
* **POST DATA** — POST/PUT data sent when submitting a form or uploading a file.
### Every matching row applies, in list order
Rows are walked top to bottom and **every** row that matches applies. Evaluation does not stop at the first match. Each row operates on the text left by the row above it, so rewrites compose. A later row can match text an earlier row produced.
Row skipped when: disabled, Applies to flag mismatch, profiles fail, blank pattern, or MIME regex fails (body only).
The shipped default configuration relies on this. Two enabled rows both target the client `Accept` header — one replaces `avif`, the other `webp` — and a browser sends both tokens in the same header. Under first-match evaluation the second row would never run and image scanning would still receive unscannable WebP.
### One substitution per row
Each matching row performs a **single** substitution, not a global replace. A row whose pattern begins with a greedy `(.*)` therefore binds to the **last** occurrence in the header, leaving earlier occurrences untouched. To rewrite every occurrence, add a row per occurrence or anchor the pattern so it cannot skip ahead.
Pattern matching is **case-insensitive**: a pattern written `avif` matches `AVIF` in the header.
### MIME gate on body
For **BODY** rewrites, a non-empty MIME type regex must match the response `Content-Type`. Empty mime matches any body when other gates pass.
SafeSquid only buffers a response body when at least one enabled, matching BODY entry has a non-blank Pattern — bodies are not buffered needlessly when no BODY entry could possibly apply.
## Processing flow
```mermaid theme={null}
flowchart TB
msg[Request or response] --> flags{Applies to matches hook?}
flags -->|No| skip[Skip row]
flags -->|Yes| prof{Profiles match?}
prof -->|No| skip
prof -->|Yes| mime{Body: MIME matches?}
mime -->|No| skip
mime -->|Yes| pcre[PCRE replace on header or body]
pcre --> next[Continue to next row]
skip --> next
next --> more{More rows?}
more -->|Yes| flags
more -->|No| done[Modified stream continues]
```
## Schema Fields
### Global fields
* **Enabled (enabled)** — Master switch for all rewrite hooks.
### Policy rows
* **Profiles (profiles)** — Connection must match tags. Blank matches all.
* **MIME type (mime)** — Regex on Content-Type for body rewrites only. Console guidance: "It is highly advisable that you set this to some mime-type; otherwise, all files will be checked."
* **Pattern (pattern)** — PCRE search pattern (required). May be trailed with a `/` followed by flag characters, Perl-style, and must be if a `/` character appears anywhere else in the pattern.
* **Replace (replace)** — Replacement string; supports capture groups.
* **Applies to (which)** — CLIENT HEADER, SERVER HEADER, BODY, POST DATA flags. Stored values are `CLIENT`, `SERVER`, `BODY`, `POST`.
## Examples
Open **Configure → Real time content security → Content modifier → Rewriting policies**. Row
fields are Enabled, Comment, Profiles, Pattern, Replace, and Applies to.
![SafeSquid console showing Content modifier Rewriting policies rows rewriting Accept headers, the Edit Policies icon on the first row circled]()
### YouTube SafeSearch cookie injection
* **Configuration:** Profiles UNSAFE\_YOUTUBE, Pattern `Cookie: ([^\r\n]*)`, Replace `Cookie: ; PREF=f2=8000000;\r\n`, Applies to CLIENT HEADER.
* **Result:** matching request Cookie header rewritten to inject SafeSearch preference before origin fetch.
### Strip Server banner
* **Configuration:** Pattern on response Server header, Applies to SERVER HEADER.
* **Result:** Server field value replaced or removed per pattern.
### Body HTML substitution
* **Configuration:** Mime `text/html`, Pattern/Replace on body, Applies to BODY.
* **Result:** response HTML modified in buffered body before client delivery.
## Code note
Header rewrite uses hooks; body rewrite uses buffcheck. Both walk the full policy list and apply every match.
## How to verify
1. Enable REWRITE in `LOG_LEVEL` for `processing:` lines showing hook target.
2. Capture before/after with View headers or raw response inspection.
3. Detailed logs on blocked connections if rewrite triggers downstream policy.
To confirm rows compose rather than short-circuit, send one request whose header matches two enabled rows and inspect what reaches the origin. Request `http://httpbin.org/headers` through the proxy with an `Accept` header containing both `image/avif` and `image/webp`.
**Expected result:** both tokens are rewritten in the header the origin receives. If only the first is rewritten, the rows are not composing and the configuration should be re-checked.
## Next steps
* **[Header filter](/configuration/restriction_policies/privacy_control/header_filter)** - strip or inject HTTP headers on client requests and server responses using global, allow, deny, and insert rules.
* **[Cookie filter](/configuration/restriction_policies/privacy_control/cookie_filter)** - control which HTTP cookies pass between clients and servers using a global policy plus allow and deny override lists.
# DLP
Source: https://docs.safesquid.com/configuration/real_time_content_security/dlp
Inspect uploads and block sensitive data from leaving the network using MIME-based DLP policies and OCR text scoring.
# Block Sensitive Uploads With DLP
## What does this section do?
The `DLP` section inspects **uploaded** content and can block sensitive data leaving the network. MIME-based DLP policies set allow or block actions; OCR policies score text extracted from uploads against a global Threshold.
DLP runs on the request (upload) path only — not on downloaded responses. Access **Bypass** with DLP skips inspection. Access **Allow bypassing** can soften a DENY block when a valid bypass cookie is present.
Because the MIME layer only sees declared content type, pair a MIME allow entry (for example, allowing spreadsheet uploads) with a matching destination restriction in Access Profiles — otherwise allowing a common upload type through DLP is effectively blanket permission to upload that type anywhere, defeating the control.
## Core Mechanics (C++ Source Validation)
MIME regex compile (commas → `|`), policy walk, OCR scoring.
### MIME policy — last match wins
Unlike most SafeSquid lists, DLP MIME rows use **last matching enabled row wins**. Each row whose POSIX regex matches the uploaded part's MIME type overwrites the action as the walk continues top to bottom.
### OCR scoring
Unless MIME action is already **DO NOT BYPASS**, SafeSquid extracts text once (`text/*` uses text extraction; `image/*` uses OCR). Enabled OCR rows are walked while score \< Threshold; each keyword regex match adds Weight. Score ≥ Threshold → **DO NOT BYPASS**.
Modern zip-based Office documents (`.docx`, `.xlsx`, `.pptx`) are unarchived directly: their real paragraph or cell text is extracted with no OCR needed. Any images embedded inside the document are separately OCR'd for text they contain.
**Legacy binary Office formats (`.doc`, `.xls`, `.ppt` — pre-2007) and PDF are not zip containers, so the unarchive-and-extract step cannot open them.** They pass through as a single unmodified block of data — neither their text nor any embedded images are inspected. This is a known gap in today's content inspection, not something a configuration change can work around.
### Bypass severity
**DENY** may be bypassed with Allow bypassing and a valid bypass cookie. **DO NOT BYPASS** is never bypassed.
## Processing flow
```mermaid theme={null}
flowchart TB
upload[Upload part] --> mimeWalk[Walk DLP MIME rows top-down]
mimeWalk --> lastMatch[Last match sets action]
lastMatch --> dnb{DO NOT BYPASS?}
dnb -->|Yes| hardBlock[Hard block skip OCR]
dnb -->|No| ocr[Extract text OCR rows]
ocr --> thresh{score >= Threshold?}
thresh -->|Yes| hardBlock
thresh -->|No| allow[Continue or DENY with bypass option]
```
## Section fields
The console splits DLP into three tabs. The MIME walk and the OCR walk are separate stages of
the same upload inspection — see **Processing flow** above for how they hand off.
## Global fields
* **Enabled (enabled)** — Master switch for upload inspection and OCR scoring.
* **Threshold (threshold)** — OCR keyword weights summed per upload; total ≥ Threshold yields DO NOT BYPASS.
## DLP policy row fields
* **Upload Content type (mime)** — POSIX regex against part MIME. Commas become alternation (`|`). Blank matches all.
* **Profiles (profiles)** — Connection must match listed Access Profile tags.
* **Action (action)** — ALLOW, DENY, or DO NOT BYPASS.
The content-inspection layer can still escalate ALLOW or DENY to DO NOT BYPASS once the keyword score crosses Threshold. It never downgrades an existing DO NOT BYPASS.
* **Comment (comment)** — Block reason when Action is DENY or DO NOT BYPASS.
## OCR policy row fields
* **Search For (keyword)** — POSIX regex against extracted text.
* **Weight (score)** — Added on match. Weight 0 skips the row.
## Examples
Open **Configure → Real time content security → DLP → DLP policies** (sibling tabs: Global,
OCR policies). Row fields are Enabled, Comment, Profiles, Upload Content type, and Action.
![SafeSquid console showing DLP policies rows with Upload Content type regexes for office document uploads, the Edit Policies icon on the first row circled]()
### Block PDF uploads
* **Configuration:** Upload Content type `application/pdf`, Action DENY, Comment `PDF uploads not permitted`.
* **Result:** any upload part whose MIME matches is blocked with that comment as reason.
### OCR keyword threshold
* **Configuration:** Threshold 100; OCR row `confidential` Weight 60; OCR row `internal use only` Weight 50.
* **Result:** image upload containing both phrases scores 110 → DO NOT BYPASS at Threshold 100.
### Last match overrides allow
* **Configuration:** Row A blank MIME ALLOW; Row B below `image/` DO NOT BYPASS.
* **Result:** image uploads match both; row B wins (last match) and hard-blocks. Non-image uploads match only row A unless OCR scores high enough.
### Legacy document format bypasses content inspection
* **Configuration:** Threshold 100; an OCR row looking for a sensitive keyword. A user uploads a `.doc` file (legacy binary Word format) containing that keyword in its body text.
* **Result:** the MIME layer's action for `.doc` applies as configured. But the content-inspection layer cannot open the legacy binary format to extract its text. So the keyword is never seen and never contributes to the score. This is a known limitation of the pre-2007 Office formats and PDF, not a misconfiguration. A policy relying on keyword detection alone should not be assumed to cover these formats.
## How to verify
1. Upload test content through a profile without DLP bypass.
2. Enable DLP in `LOG_LEVEL` for native `dlp:` lines.
3. **Reports → Detailed logs** — filter name DLP with action and score.
4. Pair Access BYPASS + DLP checkbox to confirm skip path.
5) Test keyword scoring with `.docx`/`.xlsx`/`.pptx` uploads — testing with `.doc`/`.xls`/`.ppt` or PDF does not exercise the content-inspection layer at all, by design.
## Next steps
* **[Text analyzer](/configuration/real_time_content_security/text_analyzer)** - score text in HTTP payloads against keyword patterns and block content once its cumulative score passes the threshold.
* **[ICAP](/configuration/real_time_content_security/icap)** - send HTTP request and response bodies to ICAP services, built-in or third-party, at the REQMOD and RESPMOD hooks.
# DNS Blacklist
Source: https://docs.safesquid.com/configuration/real_time_content_security/dns_blacklist
Block malicious and unauthorized domains by category, DNS blacklist, and heuristics that catch newly registered attack domains.
# Block Malicious Domains With a DNS Blacklist
```mermaid theme={null}
flowchart TB
start[Request host] --> uncategorized{Website categories empty?}
uncategorized -->|Yes| heuristics[Run uncategorized heuristics for name length then homograph then unique host count]
uncategorized -->|No| category
heuristics --> hBlock{Heuristic failed?}
hBlock -->|Yes| block[DO NOT BYPASS and HTTP 451 block page]
hBlock -->|No| category
category[Walk Threatful Categories rows] --> catMatch{Category match?}
catMatch -->|Yes| block
catMatch -->|No| request[Walk Threatful Requests rows]
request --> reqMatch{Request type match?}
reqMatch -->|Yes| block
reqMatch -->|No| dnsbl[Append DNSBL Domain suffix and resolve A record]
dnsbl --> dnsblMatch{A record in Blocked IP addresses?}
dnsblMatch -->|Yes| block
dnsblMatch -->|No| ipcheck[Compare A record and reverse DNSBL answer and GeoIP country]
ipcheck --> ipMatch{Match Blocked IP addresses or Threatful Countries?}
ipMatch -->|Yes| block
ipMatch -->|No| allow[Allow]
```
## What does this section do?
The `Dnsbl` section provides domain blocking, category-based routing, and DNS-based blacklisting to prevent access to malicious or unauthorized websites.
Category-based blocking alone always lags a newly-registered attack domain by however long it takes the categorisation feed to see and label it. The uncategorized-domain heuristics in this section — unusually long hostnames, an unusual number of distinct hosts under one uncategorized domain, and homograph (lookalike-character) detection — exist specifically to close that gap, catching suspicious new domains on structural grounds before any external feed has categorized them at all.
This section blocks on:
* Threat categories — Malware, Phishing & Fraud, Botnets, Compromised, Hacking, Illegal Software, Anonymizers, Spam Sites.
* The same content/compliance categories Access Profiles' Categories field uses — for example Nudity, Gambling.
* Country of the resolved server.
* Classic external blocklist (DNSBL) lookups.
## Core Mechanics (C++ Source Validation)
* **Sequential Heuristics**: The DNSBL module does not just check lists. It runs a sequence of heuristic checks on the HTTP `Host` header (including length validation, homograph detection, and category/request structural checks).
* **Enforcement & Block Status**: If any heuristic or blocklist check fails, the connection action is instantly set to **DO NOT BYPASS**. SafeSquid sets the HTTP status to `LMS_MALICIOUS_SERVER`, terminates the forward connection, and serves the specified `Template` to the client.
* **Bypass Checking**: The entire module execution is skipped if the connection carries the `FEATURE_DNSBL` bypass right, or if the request is destined for the SafeSquid interface itself.
## Schema Fields
### Global Fields
* **Enabled (enabled)**: When off, DNSBL/category/country/IP checks in this section are skipped. When on, uncategorized-domain heuristics run first, then policy rows.
* **Maximum Permissible Unique Hosts In An Uncategorized Domain (limit)**: Before policy rows, block hosts in an uncategorized registered domain when unique host count under that domain exceeds this value. Legacy UI allows -1 to disable; verify behaviour in your build if you rely on that value.
* **Maximum Permissible Host Name Length In An Uncategorized Domain (namelegth)**: Before policy rows, block when the host label length in an uncategorized domain exceeds this limit. Legacy UI allows -1 to disable; verify behaviour in your build if you rely on that value.
* **Block Homograph based Uncategorized Domain (homograph)**: When on, block hosts in uncategorized domains whose registered domain contains confusable (homograph) characters.
### Rule-Based Fields (Per Connection Tuning)
* **Enabled (enabled)**: Skip this policy row when disabled.
* **Comment (comment)**: Notes for operators. Used as block reason when non-empty (category/request blocks).
* **Threatful Categories (bl\_categories)**: Block when the connection’s website categories include any listed category. No DNS lookup. First matching policy row wins within this check.
* **Threatful Requests (bl\_requests)**: Block when the connection’s request types include any listed type. No DNS lookup. First matching policy row wins within this check.
* **Threatful Countries (bl\_countries)**: After resolving the host A record, block when GeoIP country code is in this list. Requires a successful A lookup and runs inside the IP-check pass.
* **DNSBL Domain (domain)**: Suffix appended to the request host for DNSBL lookup (for example example.com.in.dnsbl.org ). Leave empty on rows that only use category/request/country/IP list checks.
* **Blocked IP addresses (badips)**: IPs that count as a DNSBL hit. Compared against: host A record, reverse-DNSBL answer, or direct IP match. Failed DNSBL lookups are treated as 0.0.0.0 ; include that address to block lookup failures.
* **Template (templ)**: Block page template when this row triggers a block. Blank uses blocked (request-type rows may append the match name).
## How SafeSquid processes checks
1. When website categories are empty, uncategorized heuristics run: host name length, homograph, then unique-host count under the registered domain.
2. Category check: walk policy rows top to bottom. First row whose Threatful Categories match any connection category blocks immediately (no DNS).
3. Request type check: same first-match walk against Threatful Requests.
4. DNSBL check: append DNSBL Domain suffix to the request host, resolve A record, compare to Blocked IP addresses. Failed lookups are treated as `0.0.0.0` — include that address to block lookup failures.
5. IP check: compare host A record, reverse DNSBL answer, and GeoIP country (Threatful Countries) against Blocked IP addresses / country list — first block in each sub-pass wins.
6. On block: action **DO NOT BYPASS**, block template, debug header `X-DNSBL-Filter` with match detail.
Category and request-type matches are tried first, before any DNS lookup, because they are the cheapest checks in the sequence.
## Important entry fields
* **Threatful Categories** — Block when the connection's website categories include any listed category. First matching policy row wins.
* **Threatful Requests** — Block when the connection's request types include any listed type. First matching row wins.
* **DNSBL Domain** — Suffix appended to the request host (for example `example.com.in.dnsbl.org`). Leave empty on rows that only use category/request/country/IP checks.
* **Blocked IP addresses** — IPs that count as a DNSBL hit (ranges supported). Compared against lookup answers and direct host A records.
* **Threatful Countries** — After resolving the host A record, block when GeoIP country code is in this list.
* **Template** — Block page when this row triggers. Blank uses `blocked` (request-type rows may append the match name).
## Examples
Open **Configure → Real time content security → DNS Blacklist → DNS and IP Black Listing
Policies**. Row fields are Enabled, Comment, and Threatful Categories (or Threatful Requests) —
the top row in the capture below is hidden since its category list names a CSAM category not
suitable to publish verbatim; the remaining rows show the field shape clearly.
![SafeSquid console showing DNS Blacklist policy rows with Threatful Categories including Malware and Phishing, the Edit Policies icon circled]()
### 1 — Block malware category without DNS
* Policy row: Threatful Categories includes `Malware`
**Result:** any connection already tagged with Malware is blocked immediately with HTTP 451 and the row template. No DNSBL query runs for that decision.
### 2 — DNSBL listed host
* DNSBL Domain: `.in.dnsbl.org`
* Blocked IP addresses: `0.0.0.0,127.0.0.1-127.0.0.6`
**Result:** SafeSquid looks up `.in.dnsbl.org`. If the A record is in the blocked list (including `0.0.0.0` on failure), the request is blocked before fetch.
### 3 — Long hostname on uncategorized site
* Maximum host name length: **5**
* Site has no categories yet; host `verylonglabel.example`
**Result:** name-length heuristic blocks with reason about uncategorized host length; policy rows are not reached for that connection.
### 4 — Trusted users skip DNSBL
* Access Allow entry with **Bypass → DNS Blacklist**
**Result:** matching clients skip the entire DNSBL module; other users still run category, DNSBL, and IP checks.
## How to verify
1. Request a known-listed or test host and confirm HTTP 451 block page.
2. Check debug response header `X-DNSBL-Filter` (category name, `Request/…`, DNSBL host/IP, or heuristic reason).
3. Enable SECURITY in `LOG_LEVEL` for native `dnsbl` / blocked lines.
4. Open **Reports → Detailed logs**; `filter_name` shows `dnsbl` with filtering reason.
5) If a category or country block was expected but did not fire, confirm the destination's own categorisation or resolved address first. This section can only act on categories and addresses already available to it.
## Next steps
* **[SSqore](/configuration/application_setup/ssqore)** - turn on SSqore cloud categorization so Access Profiles can match requests by website category.
* **[Access Profiles](/configuration/restriction_policies/access_profiles)** - decide what each user can fetch by combining time, request type, response type, category, and group labels into ordered allow and deny rules.
# HTTPS inspection
Source: https://docs.safesquid.com/configuration/real_time_content_security/https_inspection
Control how SafeSquid handles HTTPS CONNECT requests and when it decrypts traffic for inspection, using ordered inspection policies.
# Control HTTPS Inspection of CONNECT Requests
```mermaid theme={null}
flowchart TB
connect[CONNECT request] --> enabled{HTTPS Inspection enabled and RCSC valid?}
enabled -->|No| tunnel[Tunnel without decrypting]
enabled -->|Yes| find[Load first matching Inspection Policy row]
find --> deepscan{DeepScan TRUE?}
deepscan -->|No| tunnel
deepscan -->|Yes| validate[Validate upstream certificate against no-cert error level and domain mismatch rules]
validate --> valid{Upstream certificate passes?}
valid -->|No| dropconn[Drop connection]
valid -->|Yes| handshake[Complete client TLS handshake and decrypt for filtering]
```
## What does this section do?
HTTPS Inspection controls CONNECT handling and optional TLS man-in-the-middle (Deep Scan) for HTTP inside HTTPS. Requires a valid RCSC (root CA) loaded from activation. The policy engine returns no policy when the section is off or misconfigured. Enabled Master switch ( ssl\_policy ). Off: no inspection policy applies. Inspection Policies Profile rows; first match wins. Sets Deep Scan, no-certificate, domain-mismatch, and max SSL error level for that CONNECT. Setup Stored server/ passphrase rows (see field help — not read by current runtime setup code). SSL Certs/Cache Download, upload, or refresh RCSC files and view SSL session/context cache. On CONNECT, deep\_scan\_check() loads the first matching Inspection
By default, general web traffic should be fully verified and fully inspected. The realistic exception is internal or development infrastructure whose certificates are self-signed, whose issuing chain is incomplete, or that is simply expired. Rather than relaxing verification globally, scope the relaxation to the specific traffic that needs it — ideally via a Request Type built for those internal hosts — rather than opening it up for everyone.
## Core Mechanics (C++ Source Validation)
* **Deep Scan (MITM)**: The connection evaluator determines if `deepscan` is enabled for the connection. If true, SafeSquid performs full Man-in-the-Middle interception by generating a forged, trusted certificate for the client using the defined Root CA, enabling inspection of the encrypted payload.
* **Upstream Validation**: SafeSquid builds an OpenSSL certificate store and verification parameters to validate the upstream origin server’s certificate against known CA authorities.
* **Strict Error Handling**: Handlers validate domain mismatches (`block_domain_mismatch`), missing certificates (`block_no_cert`), and maximum allowable OpenSSL error levels (`max_error_level`). Failures drop the connection to prevent MITM attacks from malicious servers.
## Section fields
The console splits HTTPS Inspection into three tabs. There is **no Setup tab** — the Setup rows
described under SSL Certs/Cache below are configuration the current build never reads.
## Global field
* **Enabled (enabled)**: Master switch for HTTPS Inspection. Off: The policy engine returns NULL and the inspection engine never enables Deep Scan. On: policies apply only when RCSC setup succeeds.
## Row fields
Every field here is per-connection tuning on an Inspection Policy row. The first matching
enabled row from the top wins for each CONNECT — this is first-match-wins, **not
cumulative like Access Profiles**: only the first matching entry governs a given CONNECT,
and entries below it are never consulted for that connection.
* **Enabled (enabled)**: When disabled, this row is skipped. First matching enabled row wins for each CONNECT.
* **Comment (comment)**: Operator note only; not used in SSL verification logs.
* **Profiles (profiles)**: Connection must match at least one listed profile (Access Profiles engine). Leave blank for all connections. Negated tags ( !profile ) skip the row when that profile is present. The engine stops at the first matching row from the top.
* **DeepScan (deepscan)**: When TRUE, the inspection engine returns TRUE and SafeSquid performs a client TLS handshake on CONNECT, decrypting HTTP for inspection. When FALSE, CONNECT is tunneled without decrypting; upstream SSL checks in this row are not applied to tunneled traffic. Use FALSE for non-HTTP TLS (Drive, Subversion, WinSCP, etc.).
* **Block Access to Sites that do not have an SSL Certificate (block\_no\_cert)**: When TRUE (default), upstream validation blocks if the upstream presents no certificate. When FALSE, connections without a server certificate are allowed to continue (logged at DEBUG).
* **Acceptable Errors in SSL Verification (block\_err\_level)**: Maximum OpenSSL verification error SafeSquid tolerates on the upstream certificate. Upstream validation blocks when error limits are exceeded. Level 0 is strictest — only a fully valid chain passes. Choosing a level tolerates that condition and everything listed above it in strictness; anything below it still blocks. Hostname and IP mismatch are also gated by Block domain mismatch separately.
* **Block domain mismatch in the web-site SSL certificate (block\_domain\_mismatch)**: When TRUE (default), hostname or IP mismatch errors from OpenSSL block the connection. When FALSE, X509\_V\_ERR\_HOSTNAME\_MISMATCH and X509\_V\_ERR\_IP\_ADDRESS\_MISMATCH are explicitly allowed even if they exceed the acceptable error level.
## How CONNECT is handled
1. On CONNECT, the inspection engine loads the first matching Inspection Policy row.
2. When Deep Scan is **FALSE**, CONNECT is forwarded as a tunnel without decrypting application data.
3. When Deep Scan is **TRUE** and RCSC is valid, SafeSquid completes a client-side TLS handshake and decrypts HTTP for filtering.
4. Before decrypting, the validation engine checks the upstream certificate (no cert, error level, domain mismatch rules).
5. Deep Scan only works when the tunneled protocol is HTTP; many non-HTTP TLS clients break when forced through inspection.
Certificate files live here. The **Setup** rows below were intended to carry the RCSC
passphrase and cache sizing per node, but the current build does not read them — they are
listed so an operator who finds them populated knows they have no effect.
### Setup row fields (stored, never read)
* **Enabled (enabled)**: When disabled, this Setup row is skipped when the list is rebuilt on config reload. Note: rows are loaded into server\_config\_list but no runtime code in this tree reads that list (see ambiguities).
* **Comment (comment)**: Operator note only; not referenced by SSL setup code.
* **Proxy Host (proxy\_server)**: Intended to match this SafeSquid instance (hostname from startup parameters) so the row applies on the correct node.
* **Encrypted Password (enc\_pwd)**: Encrypted passphrase for the RCSC private key, stored per Setup row. Runtime RCSC load uses the global activation password, not this field, in the current build.
* **SSL Cache Store Size (ssl\_cache\_store\_size)**: Intended cap for outbound SSL context/session cache entries ( CTXcacheOUT ). Stored on each server\_config row but not applied by current cache code (cache sizing is internal to CTXcacheOUT ). Changing cache behaviour requires a restart when supported.
* **appcontent (appcontent)**: No description provided.
## Code quirks — the Setup rows are not read at runtime
**Setup rows are not used by current SSL setup code.** Fields Proxy Host, Encrypted Password, and SSL Cache Store Size are loaded into the internal configuration loader decrypts and loads the root CA using the global activation password only — not Setup row passphrases. Cache sizing is internal to `CTXcacheOUT`; Setup SSL Cache Store Size is not applied. Treat Setup as operator reference until wired in code. Use activation for the RCSC passphrase and SSL Certs/Cache for certificate files.
## Examples
Open **Configure → Real time content security → HTTPS Inspection → Inspection Policies** (sibling
tabs: Global, SSL Certs/Cache). Row fields match the Inspection Policy fields listed above exactly.
![SafeSquid console showing HTTPS Inspection policy rows with DeepScan and certificate-error fields, the Edit Policies icon on the first row circled]()
### 1 — Inspect general web browsing
* Enabled: on, valid RCSC from activation
* Inspection row: Profiles blank, DeepScan TRUE, strict certificate checks
* Clients trust RCSC public cert
**Result:** HTTP inside HTTPS is decrypted and passed through the normal filter pipeline.
### 2 — Tunnel non-HTTP TLS (Drive, Git, RDP-over-TLS)
* Row A (top): Profiles for known non-HTTP apps, DeepScan FALSE
* Row B: Profiles blank, DeepScan TRUE
**Result:** matching non-HTTP CONNECT tunnels without decryption; general HTTPS still inspected via row B.
### 3 — Allow self-signed upstream with strict client trust
* Acceptable Errors: relaxed level for internal sites
* Block domain mismatch: TRUE for public sites, FALSE on a row matching internal host profiles
**Result:** internal servers with name mismatch may pass upstream validation while public sites remain strict.
### 4 — Scoped relaxation for internal development servers
* Inspection row, above the default: Profiles set to a label for known internal/development hosts, DeepScan TRUE, Acceptable Errors relaxed enough to tolerate a self-signed certificate or an incomplete local chain, Block domain mismatch left TRUE
**Result:** internal staging servers with a self-signed or incomplete-chain certificate pass Deep Scan without a certificate block, while Block domain mismatch staying on still catches a genuine hostname mismatch even on this relaxed entry. Every connection outside that Profile still gets the strict default.
**Turning on Deep Scan before clients trust the RCSC breaks HTTPS browsing for everyone behind it, not just for one site.** Test with one machine that already trusts the certificate before enabling Deep Scan network-wide.
## Recommended practice
* Deploy RCSC to all managed clients before enabling Deep Scan broadly.
* Use DeepScan FALSE rows for protocols that are not HTTP-over-TLS.
* Use SSL Certs/Cache to upload corporate roots and refresh caches after certificate changes.
* Do not rely on Setup Encrypted Password for RCSC unlock — use activation passphrase.
## How to verify
1. CONNECT to an HTTPS site; confirm filters (for example ClamAV) see decrypted content when DeepScan is TRUE.
2. Enable SSL log level for `SSLcertSection::` and certificate validation lines.
3. Check Detailed logs for CONNECT handling and upstream certificate errors.
4. SSL Certs/Cache → Cache Refresh after RCSC or trusted-CA changes.
5. Confirm a destination with a genuinely broken certificate (expired, wrong hostname, self-signed) is blocked under the strict default entry. Only passes through when routed to an entry whose Acceptable Errors and Block domain mismatch settings were deliberately relaxed for it.
## Next steps
* **[Clam antivirus](/configuration/real_time_content_security/clam_antivirus)** - scan HTTP traffic for malware in real time by integrating the ClamAV clamd daemon with SafeSquid.
* **[SqScan](/configuration/real_time_content_security/sqscan)** - scan uploads and downloads for malware with SafeSquid's built-in in-memory scanner, with no external clamd process.
# ICAP
Source: https://docs.safesquid.com/configuration/real_time_content_security/icap
Send HTTP request and response bodies to ICAP services, built-in or third-party, at the REQMOD and RESPMOD hooks.
# Send Request and Response Bodies to ICAP Services
## What does this section do?
The `ICAP` section sends HTTP request or response bodies to an external ICAP server for scanning or modification. Typical uses include antivirus ICAP services, DLP adapters, and content adaptation.
ICAP lets SafeSquid delegate inspection to specialized third-party scanners rather than relying only on its own built-in engines.
Access **Bypass** with ICAP skips all ICAP processing for matching clients.
## Core Mechanics (C++ Source Validation)
Policy walk, ICAP response handling.
### Row walk with fallback
For each REQMOD or RESPMOD hook, enabled rows are walked top to bottom. Row must match Profiles, include the Applies to flag, and have a valid ICAP Service URL.
If no row is eligible for the current hook — none match Profiles, include the Applies to flag, or carry a valid Service URL — ICAP does not run for that hook on this connection.
### Response codes
* **204 No Content** — clean; processing stops; later rows not tried.
* **200 OK** with configured threat header — block or content replacement; stops on first successful 200.
* **5xx** — `error` template, log `server failed`.
* Timeout or connection failure — try next matching row.
## Processing flow
```mermaid theme={null}
flowchart TB
hook[REQMOD or RESPMOD hook] --> walk[Walk ICAP rows top-down]
walk --> row{Match profiles flags URL?}
row -->|No| next[Next row]
row -->|Yes| icapcall[Call ICAP server]
icapcall --> code{Response code?}
code -->|204| clean[Allow stop]
code -->|200 + threat| block[Block or replace stop]
code -->|5xx| error[Error template]
code -->|timeout| next
```
## Schema Fields
### Global fields
* **Enabled (enabled)** — Master switch for ICAP REQMOD and RESPMOD.
### Policy rows
* **ICAP Service URL (icapurl)** — Full URI: host, port, service path (e.g. `icap://127.0.0.1:1344/avscan`).
* **ICAP Timeout (timeout)** — Seconds for connect and read/write.
* **Applies to (flags)** — REQUESTS (REQMOD) and/or RESPONSES (RESPMOD).
* **Threat ID Header (threatheader)** — Header name(s) on ICAP 200 response for threat name.
- **Threat ID Header, first-match nuance**. The **first** of the configured names present in the response supplies the threat name used for logging and the block template. If none of them are present in a 200 response, the reason is recorded as a missing threat header.
- **Profiles (profiles)** — Limit to connections with these tags. Blank matches all.
## Examples
Open **Configure → Real time content security → ICAP → ICAP**. Live rows show Enabled, Comment,
ICAP Timeout, Applies to, and Threat ID Header — **ICAP Service URL and Profiles do not appear on
either shipped row**, though both are listed under Schema Fields above. Confirm before assuming
those two fields render on a fresh row.
![SafeSquid console showing ICAP rows for ClamAV REQMOD and RESPMOD with ICAP Timeout and Threat ID Header fields, the Edit Policies icon on the first row circled]()
### Scan downloads only
* **Configuration:** Applies to RESPONSES, Service URL `icap://10.0.0.5:1344/respmod`.
* **Result:** response bodies sent to ICAP RESPMOD; 204 allows; 200 with threat header blocks.
### REQMOD for uploads
* **Configuration:** Applies to REQUESTS, Service URL `icap://127.0.0.1:1344/reqmod`.
* **Result:** uploaded content scanned before forwarding to origin.
### Fallback server
* **Configuration:** Row A primary URL Timeout 30; Row B backup below Timeout 60.
* **Result:** row A timeout tries row B; 204 from row A stops before row B.
## How to verify
1. Enable ICAP log level; look for `ICAPSection::` lines and response codes.
2. Detailed logs show filter name ICAP on block.
3. Test EICAR through ICAP-enabled profile.
## Next steps
* **[SqScan](/configuration/real_time_content_security/sqscan)** - scan uploads and downloads for malware with SafeSquid's built-in in-memory scanner, with no external clamd process.
* **[Clam antivirus](/configuration/real_time_content_security/clam_antivirus)** - scan HTTP traffic for malware in real time by integrating the ClamAV clamd daemon with SafeSquid.
# Image analyzer
Source: https://docs.safesquid.com/configuration/real_time_content_security/image_analyzer
Score images in downloads and uploads, and replace any image that scores above the threshold with a block template.
# Block Risky Images With the Image Analyzer
## What does this section do?
The `Imgfilter` section scores `image/*` response and upload bodies and blocks or debug-replaces content when the engine score is at or above a threshold. Blocked images can be replaced with a template (default `checkeredgif`).
It exists to keep unwanted image content (for example, adult material) off the network — useful both for blocking what users download and for stopping the same kind of content from being uploaded through the proxy.
## Core Mechanics (C++ Source Validation)
### First match wins
Walk enabled filtering policy rows top to bottom; first profile match sets threshold, bypass, debug, and template.
### MIME and size gates
Only parts whose MIME starts with `image/` are candidates. Images smaller than 50×50 pixels are skipped — too small to meaningfully score, and excluding them avoids wasted work on tracking pixels and icons.
### Threshold scale
Roughly **-10** (unlikely inappropriate) through **0** (very likely). Block when engine score ≥ threshold.
### Debug mode
On responses with Debug enabled, images at or above threshold are blurred and annotated in-place. Connection still marked blocked but block template not sent.
### Bypass
Bypass Image Scanning on a matching row skips buffering and scoring entirely.
## Processing flow
```mermaid theme={null}
flowchart TB
part[image/* body] --> size{>= 50x50?}
size -->|No| skip[Skip]
size -->|Yes| walk[Walk policy rows]
walk --> match{First profile match}
match --> bypass{Bypass on?}
bypass -->|Yes| skip
bypass -->|No| score[Engine score]
score --> thresh{score >= threshold?}
thresh -->|No| pass[Allow]
thresh -->|Yes| debug{Debug on response?}
debug -->|Yes| blur[Blur annotate]
debug -->|No| templ[Block template]
```
## Schema Fields
### Global fields
* **Enabled (enabled)** — Master switch; requires library init success.
* **Default template (dtempl)** — Fallback when row Template blank; default `checkeredgif`.
* **Library path (libpath)** — Path to imgfilter engine module.
### Policy rows
* **Profiles (profiles)** — Limit to tagged connections. Blank matches all.
* **Threshold (threshold)** — Block when score ≥ this value. A **lower** Threshold number is **stricter** (blocks more). A higher one is more permissive — for example, a Threshold of `-2` blocks less aggressively than a Threshold of `0`.
* **Bypass Image Scanning (bypass)** — Skip scan for matching profiles.
* **Debug (debug)** — Blur/annotate on response instead of block template. Has no equivalent effect on the upload path, which always uses the block template.
* **Template (template)** — Replacement on block. Falls back through the matching entry's own Template, then the section's Default template, then the built-in checkered placeholder — whichever is first non-blank.
## Examples
Open **Configure → Real time content security → Image analyzer → Filtering policies**. Row fields
are Enabled, Comment, Bypass Image Scanning, Profiles, Threshold, Template, and Debug.
![SafeSquid console showing Image analyzer Filtering policies rows with Threshold and Template fields, the Edit Policies icon on the first row circled]()
### Block for students
* **Configuration:** Profiles STUDENT, Threshold 0, Template checkeredgif.
* **Result:** student image responses scoring ≥ 0 replaced with checkered template.
### Staff bypass
* **Configuration:** Row A Profiles STAFF Bypass on; Row B blank Threshold -2.
* **Result:** staff skip imgfilter; others scored via row B.
### Debug tuning
* **Configuration:** Debug on, Threshold -5.
* **Result:** borderline response images blurred with score annotation; still logged blocked.
## How to verify
1. Fetch image through profile with image-filter tag and imgfilter enabled.
2. Enable imgfilter log level for score lines.
3. Detailed logs show filter name imgfilter on block. If a request you expected to be scored is missing, check whether an earlier entry's Bypass Image Scanning claimed it first.
## Next steps
* **[Text analyzer](/configuration/real_time_content_security/text_analyzer)** - score text in HTTP payloads against keyword patterns and block content once its cumulative score passes the threshold.
* **[DLP](/configuration/real_time_content_security/dlp)** - inspect uploads and block sensitive data from leaving the network using MIME-based DLP policies and OCR text scoring.
# Redirect
Source: https://docs.safesquid.com/configuration/real_time_content_security/redirect
Intercept requests for specific URLs and rewrite them internally or send an HTTP 302 to the browser, for example to enforce safe search.
# Redirect Requests for Specific URLs
```mermaid theme={null}
flowchart TB
req[Client request or response Location header] --> walk[Walk enabled rows top to bottom]
walk --> match{Profiles and direction and URL regex all match?}
match -->|No| next[Next row]
match -->|Yes| mode{302 redirect field}
mode -->|Yes| send302[Send HTTP 302 to client with rewritten URL]
mode -->|No| fetch[Rewrite proto host file and port then fetch internally]
```
## What does this section do?
The `Redirect` section allows SafeSquid to intercept requests for specific URLs and either internally rewrite them (fetching content from a new destination on behalf of the client) or send an HTTP 302 redirect back to the client’s browser. Typical uses include enforcing a search engine's safe-search mode, sending users away from a decommissioned internal site, or rewriting an insecure link a server returned into its secure equivalent before it reaches the browser.
## Core Mechanics (C++ Source Validation)
First-match URL/Location rewrite, send302 branching.
* **Evaluation Order**: Rules are evaluated top to bottom. The first matching rule takes effect and evaluation stops for that pass.
* **PCRE Matching**: The `URL` field accepts Perl Compatible Regular Expressions (PCRE) with capture groups (e.g., `(.*)`), which can be referenced in the `Redirect` field using `$1`, `$2`, etc.
* **Internal Rewrite vs. 302**: If `send302` is false, SafeSquid fetches the rewritten URL and serves the content transparently. If true, it returns an HTTP 302 Location redirect to the client.
## Schema Fields
### Global Fields
* **Enabled (enabled)**: Toggles URL redirection globally, on for all connections unless the matching Access restrictions entry's Bypass grants Redirect.
### Rule-Based Fields (Per Connection Tuning)
* **Enabled (enabled)**: Toggles the rule.
* **Comment (comment)**: User description. Logged on match when non-empty.
* **Profiles (profiles)**: The trigger condition. Limit this entry to connections that already carry these Access Profile tags.
* **URL (url)**: PCRE matched against the request URL or Location header.
* **Redirect (redirect)**: The replacement template after the PCRE match.
* **Port (port)**: When > 0, forces this destination port on internal rewrite. `0` keeps the port from the rewritten URL.
* **302 redirect (send302)**: Set to `Yes` for HTTP 302, or `No` for internal transparent fetch.
* **Options (options)**: Bitmask/list of options: Decode URL before match (`DECODEBEFORE`), encode URL path (`ENCODE`), or decode URL path after substitution (`DECODEAFTER`).
* **Applies to (which)**: Match client request URL (`URL`), response Location header (`LOCATION`), or both (`BOTH`).
## How SafeSquid processes the list
1. On the client request, SafeSquid builds `proto://host/file` and tests rows whose Applies to includes URL (or BOTH).
2. On redirect responses, SafeSquid tests the response `Location` value for rows that include LOCATION (or BOTH).
3. First enabled row that matches profiles, URL regex, and direction wins; processing stops.
4. **302 redirect = No** (default): rewrite `proto`, `host`, `file`, and optional port on the request and fetch internally. Request type may become HTTP proxy.
5. **302 redirect = Yes**: send HTTP 302 to the client with the rewritten URL as Location. No origin fetch for that request.
6. Options: percent-decode before PCRE match; URL-encode or decode the path portion after substitution.
**Order matters.** Put specific URL patterns above broad catch-alls — first match wins.
## Important entry fields
* **Profiles** — Apply only when the connection has one of these profiles. Blank = all connections. Prefix `!` to skip connections that have a profile.
* **URL** — PCRE with capture groups matched against the request URL or Location header. Required; blank URL skips the row.
* **Redirect** — Replacement template after PCRE match (supports `$1` captures and connection variables).
* **Port** — When > 0, force this destination port on internal rewrite. 0 keeps the port from the rewritten URL.
* **302 redirect** — **Yes** — HTTP 302 to client. **No** — internal rewrite and fetch.
* **Applies to** — URL (request only), LOCATION HEADER (response redirects only), or BOTH (separate processing passes).
## Examples
Open **Configure → Real time content security → Redirect → Redirection policies**. Row fields are
Enabled, Comment, Profiles, URL, Redirect, Port, 302 redirect, and Applies to — the shipped
default rows enforce safe search on Bing, Google, Yahoo, and DuckDuckGo.
![SafeSquid console showing Redirection policies rows enforcing search-engine safe search, the Edit Policies icon on the first row circled]()
### 1 — Force Google safe search (internal rewrite)
* URL: `^https://(www\.)?google\.com/search\?(.*)`
* Redirect: `https://www.google.com/search?safe=active&$2`
* 302 redirect: **No**, Applies to: URL
**Result:** matching Google search requests are rewritten and fetched by SafeSquid with `safe=active`. The browser address bar stays on the original URL pattern.
### 2 — Send users to a block info page (302)
* URL: `^https://old-portal\.example\.com/`
* Redirect: `https://intranet.example.com/moved.html`
* 302 redirect: **Yes**
**Result:** client receives HTTP 302 with Location set to the new URL. SafeSquid does not fetch the old portal for that request.
### 3 — Rewrite outbound redirect Location
* Applies to: LOCATION HEADER
* URL: `^http://cdn\.example\.com/(.*)`
* Redirect: `https://cdn.example.com/$1`
**Result:** when the origin returns a redirect whose Location matches, SafeSquid replaces Location with the HTTPS form before the response reaches the browser.
### 4 — Profile-gated redirect only for guests
* Profiles: `Guest`
* URL: `^https://mail\.example\.com/`
* Redirect: `https://webmail-lite.example.com/`, 302 redirect: **Yes**
**Result:** Guest users get 302 to webmail-lite; staff without the Guest profile skip the row and reach mail.example.com normally.
## How to verify
1. Reproduce the URL from a client and watch whether the browser receives 302 or content from the rewritten host.
2. Enable REDIRECT in `LOG_LEVEL` for native lines showing match, internal rewrite, or an HTTP 302.
3. Open **Reports → Detailed logs** for the requested URL and response code.
4. Pair Redirect profile tags with rows in Access Profiles (tags are not hard-coded — both sections must reference the same tag string).
## Next steps
* **[Content modifier](/configuration/real_time_content_security/content_modifier)** - rewrite HTTP headers and bodies with PCRE search-and-replace to inject cookies, strip sensitive header values, or change response content.
* **[Access Profiles](/configuration/restriction_policies/access_profiles)** - decide what each user can fetch by combining time, request type, response type, category, and group labels into ordered allow and deny rules.
# SqScan
Source: https://docs.safesquid.com/configuration/real_time_content_security/sqscan
Scan uploads and downloads for malware with SafeSquid's built-in in-memory scanner, with no external clamd process.
# Scan Uploads and Downloads With SqScan
## What does this section do?
The `SqScan` section is SafeSquid’s built-in in-memory antivirus scanner. It scans buffered uploads and downloads without an external `clamd` process. When malware is detected, the connection is blocked with **DO NOT BYPASS**.
Use **sqscan status** in the Web UI to confirm Ready state and signature currency. See also ClamAV and ICAP for defense in depth.
## Core Mechanics (C++ Source Validation)
### First match wins
Enabled virus scanning policy rows are walked top to bottom. The **first** row whose Profiles match applies for that connection.
### Scan levels — BYPASS only
Malware Security Level **BYPASS** skips scanning. Values STANDARD, HIGH, and PARANOID are stored but the engine uses fixed scan options. Only **BYPASS** changes runtime behaviour today.
### Malware Types unused
The eight Malware Types checkboxes — **VIRUS**, **SPYWARE**, **ADWARE**, **SPAM**, **ROOTKIT**, **DIALER**, **MALICIOUS\_APP**, and **ARCHBOMB** — set bit flags on the policy but are not passed to the scanner API. Detection uses the engine’s built-in signature set.
### Enforcement
Virus detection sets the action to **DO NOT BYPASS**. Access restrictions **Bypass** with antivirus skips SqScan entirely.
## Processing flow
```mermaid theme={null}
flowchart TB
part[Buffered upload/download] --> walk[Walk policy rows top-down]
walk --> match{First profile match?}
match -->|No| skip[No SqScan]
match -->|Yes| bypass{BYPASS level?}
bypass -->|Yes| skip
bypass -->|No| scan[In-memory scan]
scan --> virus{Virus found?}
virus -->|Yes| block[DO NOT BYPASS block]
virus -->|No| pass[Continue]
```
## Schema Fields
### Global fields
* **Enabled (enabled)** — Master switch. When off, hooks exit immediately. When on, scanning requires successful engine init (Ready in sqscan status).
### Policy rows
* **Profiles (profiles)** — Limit row to connections with these Access Profile tags. Blank matches all.
* **Malware Security Level (scan\_flag)** — BYPASS skips SqScan. Other levels label the row but do not alter scan depth in the current build.
* **Malware Types (malware\_types)** — Eight checkboxes (`VIRUS`, `SPYWARE`, `ADWARE`, `SPAM`, `ROOTKIT`, `DIALER`, `MALICIOUS_APP`, `ARCHBOMB`). Stored for operator reference; not forwarded to scan API.
## Examples
Open **Configure → Real time content security → SqScan → Virus scanning policies**. Row fields
are Enabled, Comment, Malware Security Level, and Malware Types.
![SafeSquid console showing a SqScan Virus scanning policies row with STANDARD Malware Security Level, the Edit Policies icon circled]()
### Scan all users
* **Configuration:** Enabled on; one row Profiles blank, Malware Security Level STANDARD.
* **Result:** all buffered content on matching connections is scanned in memory.
### Skip scanning for admins
* **Configuration:** Row A (top) Profiles ADMIN, Malware Security Level BYPASS; Row B Profiles blank, STANDARD.
* **Result:** ADMIN connections hit row A first and skip; everyone else scanned via row B.
### EICAR verification
* **Configuration:** sqscan status shows Ready; download EICAR through scanned profile.
* **Result:** block with DO NOT BYPASS; Detailed logs show virus detection.
## How to verify
1. **sqscan status** — module Ready, signatures current.
2. Download EICAR test file through proxy.
3. Enable ANTIVIRUS log level for native `sqscan:` lines.
4. Dashboard counters: Objects Scanned, Threats Detected, Scan bypassed. A rising Scan Bypassed count with no corresponding BYPASS entries usually points to the scanner not being Ready, not to a misconfigured policy.
## Next steps
* **[Clam antivirus](/configuration/real_time_content_security/clam_antivirus)** - scan HTTP traffic for malware in real time by integrating the ClamAV clamd daemon with SafeSquid.
* **[ICAP](/configuration/real_time_content_security/icap)** - send HTTP request and response bodies to ICAP services, built-in or third-party, at the REQMOD and RESPMOD hooks.
# Text analyzer
Source: https://docs.safesquid.com/configuration/real_time_content_security/text_analyzer
Score text in HTTP payloads against keyword patterns and block content once its cumulative score passes the threshold.
# Block Content With the Text Analyzer
```mermaid theme={null}
flowchart TB
resp[Response Content-Type] --> mimeGate{Any enabled row MIME regex matches?}
mimeGate -->|No| pass[Pass through unscanned]
mimeGate -->|Yes| buffer[Buffer response body]
buffer --> walk[Walk rows top to bottom]
walk --> row{Row MIME and Keyword regex match body?}
row -->|Yes| add[Add row Score to running total]
row -->|No| next[Next row]
add --> thresh{Total at or above Threshold?}
thresh -->|Yes| block[DO NOT BYPASS and HTTP 451 block page]
thresh -->|No| next
```
## What does this section do?
The `Keywords-filtering` section (`safesquid-keywords-filtering(5)`) scans the textual content of HTTP payloads for specific patterns and assigns scores to determine if the content should be blocked.
Cumulative scoring suits content that no single keyword proves is a problem. But that is clearly objectionable once several related terms appear on the same page — acceptable-use enforcement against gambling, adult, or extremist material.
## Core Mechanics (C++ Source Validation)
Cumulative scoring, early exit at threshold.
* **Cumulative Scoring Engine**: Unlike standard first-match modules, the keyword filter evaluates *all* enabled rules matching the connection profile. When a Regex keyword is matched, its defined `Score` is added to a cumulative tally for that connection.
* **Early Exit**: If the cumulative score breaches the Global Threshold (`if (x >= threshold)`), scanning immediately stops to save CPU.
* **MIME Filtering**: SafeSquid will only scan payloads whose `Content-Type` matches the specified `Mime type` regular expression.
* **Enforcement**: Once the threshold is breached, the connection action becomes **DO NOT BYPASS**, serving the specified block template and populating the `_SCORE_` and `_REASON_` template variables.
**A Text analyzer block is not click-through-able.** Even when the matching Access restrictions entry grants **Allow bypassing**, a Text analyzer block offers the user no continue-anyway link. That override applies to some other block reasons, not this one.
## Schema Fields
### Global Fields
* **Enabled (enabled)**: Turn Text analyzer on or off for all connections, unless the matching Access restrictions entry's **Bypass** grants **Text analyzer**.
* **Threshold (threshold)**: Minimum total score from matching rows to block. Block when total ≥ this value (strictly below = allow).
* **Template (templ)**: Block page template when score ≥ Threshold. Blank uses blocked . Template receives *SCORE* and *THRESHOLD* variables.
### Rule-Based Fields (Per Connection Tuning)
* **Enabled (enabled)**: Skip this row when disabled. Rows with Score 0 or blank Keyword are never applied.
* **Comment (comment)**: Notes for operators. Logged on match when non-empty.
* **Profiles (profiles)**: Apply only when the connection has one of these profiles. Blank = all connections. Prefix ! to skip connections that have a profile.
* **Mime type (mime)**: Regex on response Content-Type . Blank defaults to matching text (same as built-in text/css/javascript/xml/json family).
* **Keyword(s) (keyword)** — Regex searched in the response body. Required; blank Keyword skips the row. Example: `\b(gambling|casino)\b`. One match adds Score once per scan pass for this row.
* **Score (score)**: Points added when this row’s keyword regex matches the body. Use 0 to disable the row. Negative values reduce the running total — useful for a keyword that should offset an otherwise-alarming score in a legitimate context, for example a news article that discusses a sensitive topic responsibly.
## How SafeSquid processes the list
1. During response processing, if any enabled row matches the response `Content-Type`, SafeSquid buffers the body.
2. After the body is available, rows are walked top to bottom.
3. Mime type regex must match `Content-Type`. Blank mime defaults to matching `text` (same family as text/css/javascript/xml/json).
4. Keyword regex is searched in the buffered body; each match adds that row's Score (negative scores reduce the total).
5. Rows with Score 0 or blank Keyword are never applied.
6. At or above Threshold: HTTP 451 block page, bypass disallowed, cache code `TCP_DENIED`. The connection's cache entry is marked so the blocked response is never served from cache.
## Important entry fields
* **Profiles** — Apply only when the connection has one of these profiles. Blank = all connections. Prefix `!` to skip connections that have a profile.
* **Mime type** — Regex on response `Content-Type`. Blank defaults to matching `text`.
* **Keyword(s)** — Regex searched in the response body. Required; blank Keyword skips the row.
* **Score** — Points added when the keyword regex matches. Use 0 to disable the row. Negative values reduce the running total.
## Examples
Open **Configure → Real time content security → Text analyzer → Global** for Enabled, Threshold,
and Template. The **Filtering policies** row list is not screenshotted here — its shipped default
keyword rows contain explicit search terms, unsuitable to publish verbatim.
![SafeSquid console showing Text analyzer Global fields with Threshold set to 100, the Edit Policy icon circled]()
### 1 — Block pages with multiple mild terms
* Threshold: **100**
* Row A: Keyword `gambling`, Score **40**
* Row B: Keyword `casino`, Score **70**
**Result:** a page containing both terms scores 110, meets Threshold, and is blocked with HTTP 451 and the configured template. A page with only `gambling` scores 40 and is allowed.
### 2 — Single high-weight term
* Threshold: **50**
* Row: Keyword `\bweapon\b`, Score **100**, Mime blank (text family)
**Result:** any text/html body matching the regex is blocked on first row match; scan stops once total ≥ Threshold.
### 3 — Limit to students profile
* Row: Profiles `Students`, Keyword `weapon`, Score **80**
* Threshold: **50**
**Result:** staff without the Students profile skip the row entirely; student connections with `weapon` in the body are blocked.
### 4 — Non-text response skipped
* Row: Mime `text`, Keyword `badword`, Score **100**
**Result:** an `image/png` response does not match the mime regex, is not buffered for keyword scan, and passes through even if binary data accidentally contained the string.
## How to verify
1. Fetch a test page through the proxy and confirm block vs allow against known body content.
2. Check debug response header `X-Text-Analyzer` (shows score vs threshold, `Buffering Requested` when mime matched, or `Disabled` when the section is off for that connection).
3. Enable TEXT\_ANALYZER in `LOG_LEVEL` for native `match:` and `blocked` / `allowed` lines.
4. Open **Reports → Detailed logs**; blocked responses show `filter_name` for text analyzer and the score reason.
5. If a page you expect to be blocked passes through, check its actual `Content-Type` first. A Mime type mismatch is the most common reason a response is never scanned.
## Next steps
* **[DLP](/configuration/real_time_content_security/dlp)** - inspect uploads and block sensitive data from leaving the network using MIME-based DLP policies and OCR text scoring.
* **[Image analyzer](/configuration/real_time_content_security/image_analyzer)** - score images in downloads and uploads, and replace any image that scores above the threshold with a block template.
# Access Profiles
Source: https://docs.safesquid.com/configuration/restriction_policies/access_profiles
Decide what each user can fetch by combining time, request type, response type, category, and group labels into ordered allow and deny rules.
# Decide What Each User Can Fetch With Access Profiles
The **Access Profiles** section is the central content-policy hub. Access restrictions decide *who* connects; Access Profiles decide *what* they may fetch. It combines Time Profiler, Request Types, Response Types, categories, and User-Groups, then adds profile tags and sets Allow/Deny.
Unlike Access restrictions (first match), **every** matching row in Default and Secondary Policies applies. Later rows see tags changed by earlier rows. A broad Deny early in the list is not final. A later, more specific Allow can still override it, and the reverse works too. The recommended shape is to deny broadly first and carve out specific exceptions after.
## Profile pipeline
On each request (non-interface), SafeSquid builds label lists in this order before Access Profiles runs:
1. [Time Profiler](/configuration/custom_settings/time_profiler) → `time_schedules`
2. [Request Types](/configuration/custom_settings/request_types) → `request_types`
3. Domain categorization → `website_categories`
4. **Access Profiles** → `profiles` + `action`
5. [Response Types](/configuration/custom_settings/response_types) on response headers/body → updates `response_types`; Access Profiles runs again
Access restrictions **User-Groups** populate `user_groups` (not `profiles`). Access Profiles **User Groups** gate matches those tags.
## Core mechanics
### List order
1. Clear the connection's profile tags; set the action to **ALLOW**.
2. Walk **Default Policies** top-down — every match applies.
3. Walk **Secondary Policies** top-down — same cumulative rules.
4. Final action not Allow → block (bypass cookie may apply).
```mermaid theme={null}
flowchart TB
start[New request] --> clear["Clear profile tags, set Action = ALLOW"]
clear --> walk[Walk Default Policies then Secondary Policies top-down]
walk --> row{"Row: Profiles, Time Schedule, Request Types, Response Types, User Groups, Categories all match?"}
row -->|Yes| apply["Add or remove profiles, update Action"]
row -->|No| next["Next row - cumulative, no stop"]
apply --> next
next --> final{Final Action = Allow?}
final -->|Yes| allow[Continue with applied profile tags]
final -->|No| block[Block template]
block --> bypass[451 + bypass cookie if Allow bypassing]
```
### Action values
* **Allow** — Default. Downstream sections use applied profile tags.
* **Deny** — Block. With Access **Allow bypassing**, temporary bypass cookie may be offered.
* **Do not bypass** — Hard block; no bypass cookie.
* **Inherit** — Keep action from earlier matching rows; use when row only adds/removes tags.
## Rule fields
All configured criteria on a row must match. Blank = any. Use `!` to negate tags in list fields.
* **Enabled** (`enabled`) — disabled entries are skipped entirely; they never match and never affect the connection.
* **Comment** (`comment`) — free text describing why the entry exists. Also shown to the user as the block reason when this entry's Action sets Deny or Do not bypass.
* **Trace Entry** (`profile_tracing`) — writes a native log line every time this entry adds or removes a Profile label. Switch it off again once testing is done.
* **Proxy instance** (`proxyhost`) — a regular expression matched against this appliance's own hostname, for deployments where several instances share one configuration but should apply different entries. Blank applies on every instance.
* **Applicable Profiles** — Tags on connection from earlier rows in this pass (list is cleared at start).
* **Time Schedule** — Tags from [Time Profiler](/configuration/custom_settings/time_profiler).
* **Request Types** — Tags from [Request Types](/configuration/custom_settings/request_types).
* **Response Types** — Tags from [Response Types](/configuration/custom_settings/response_types); requires response header when field set. Also skipped for a response confirmed empty (not chunked, Content-Length zero).
* **User Groups** — From Access restrictions. Non-blank + empty user\_groups → row skipped. Setting this field never by itself forces a login prompt.
* **Categories** — Domain categories; empty lookup tests as `UNCATEGORIZED`. When referer categorization is enabled, the referer's category is matched too.
* **Action** (`action`) — only changes the connection's running Action when it differs from the current Action and is not Inherit.
* **Added Profiles** / **Removed profiles** — labels applied when the entry matches. Added runs first, then Removed, on the same entry — so one entry can add one label and remove a different one. But cannot remove a label it just added. A label already present is not duplicated; removing a label that is not present has no effect.
### Default Policies vs. Secondary Policies
**Default Policies** is evaluated first, for every connection, on every pass. **Secondary Policies** runs after it, using the labels and Action Default Policies left behind. The natural home for scoped exceptions layered on top of a broad Default Policies deny.
## Examples
Open **Configure → Restriction Policies → Access Profiles**. Default Policies is the tab that
opens first; each row shows Enabled, Comment, Trace Entry, Categories or Request Types, Action, and
Added Profiles inline, and the right-hand panel restates the evaluation order.
![SafeSquid console showing the Access Profiles Default Policies list, with the Edit Policies pencil icon on the first row circled]()
### LAN users + category deny
**Config:** Default: User Groups `LAN_USERS`, add `users`, Inherit. Secondary: Categories `Social`, profiles `users`, Deny.
**Result:** LAN traffic tagged; Social category blocked with row comment as reason.
### Time-gated exception
**Config:** Time Profiler adds `LUNCH_TIME`; Secondary matches Time Schedule `LUNCH_TIME`, Allow streaming.
**Result:** exception only during lunch window local time.
### Response-side deny
**Config:** Response Types adds `executable_download`; Secondary matches that tag, Deny.
**Result:** may not match until response headers arrive and profile matching runs again.
## How to verify
1. **Reports → Detailed logs** — profiles, request/response/time profile columns.
2. Enable **Trace Entry** on one row; check native logs.
3. Debug headers — `X-SafeSquid-Profiles`, `X-SafeSquid-Access-Policy`.
4. If an expected label is missing, check whether an earlier entry's gates actually fit the connection. A skipped entry contributes nothing.
5. To confirm cumulative behaviour, deliberately place a Deny in Default Policies and a narrower Allow below it in Secondary Policies, and verify the connection is allowed. This is what most clearly distinguishes Access Profiles from Access restrictions.
6. When a block is unexpected, check the Comment recorded as the block reason and whether the Action was Deny or Do not bypass. A Do not bypass block will not respond to a bypass cookie even for a user who otherwise holds the Allow bypassing right.
## Next steps
* **[Time Profiler](/configuration/custom_settings/time_profiler)** - tag connections with time labels from the appliance clock so Access Profiles can apply policy by weekday and time of day.
* **[Request Types](/configuration/custom_settings/request_types)** - label HTTP requests with tags that Access Profiles and other filters match on, based on what the client asked for.
* **[Response Types](/configuration/custom_settings/response_types)** - label HTTP responses by their real content type, such as executable, archive, or image, so Access Profiles can block by actual file type.
# Cookie filter
Source: https://docs.safesquid.com/configuration/restriction_policies/privacy_control/cookie_filter
Control which HTTP cookies pass between clients and servers using a global policy plus allow and deny override lists.
# Control Which Cookies Pass With the Cookie Filter
Open **Configure → Restriction Policies → Privacy control → Cookie filter**. This section sits under the **Privacy control** menu group alongside [Cookie filter](/configuration/restriction_policies/privacy_control/cookie_filter), [Header filter](/configuration/restriction_policies/privacy_control/header_filter) and [Elevated Privacy](/configuration/restriction_policies/privacy_control/elevated_privacy) — configure them together, since a Cookie filter allow row and an Elevated Privacy STANDARD row can otherwise fight over the same header.
The `Cookies-filtering` section (`safesquid-cookies-filtering(5)`) provides granular control over HTTP cookies passing between clients and servers.
```mermaid theme={null}
flowchart TB
field[Cookie header field] --> policy{Policy Deny or Allow?}
policy -->|Deny| walkA1[Walk Allow list]
policy -->|Allow| walkD1[Walk Deny list]
walkA1 --> walkD2[Walk Deny list]
walkD1 --> walkA2[Walk Allow list]
walkD2 --> last[Last match in list pass wins]
walkA2 --> last
last --> result{Match outcome?}
result -->|Allow| keep[Keep cookie]
result -->|Deny| strip[Strip cookie field]
```
## Core mechanics
Dual-list Allow/Deny walk, **last** match in pass wins — unlike most other sections' first-match rule.
* **Dual-List Policy Engine**: Cookie filtering operates on a Global Policy (Allow or Deny) combined with Allow/Deny override lists. If the global policy is set to `Allow`, SafeSquid first scans the Deny List (to block matching cookies) and then scans the Allow List (to explicitly permit exceptions).
* **Time-Based Evaluation**: Unlike other modules, the time profiles here (`limitmonths`, `limitdays`, etc.) are checked against the cookie's literal `Expires` attribute (`COOKIE_HAS_EXPIRES`), not the proxy's current system time.
* **Action**: Matches result in the cookie being silently stripped from the HTTP stream (`HEADER_FILTERED`).
- **Clear-Site-Data**: whenever any cookie is dropped from a connection, SafeSquid adds a `Clear-Site-Data: "*"` header, asking the browser to clear stored site data. A stronger cleanup than simply not forwarding the one cookie field.
### How SafeSquid processes the lists
1. If Policy is **Deny**, SafeSquid walks **Allow** first, then **Deny**.
2. If Policy is **Allow**, SafeSquid walks **Deny** first, then **Allow**.
3. Within each list, every enabled matching row is evaluated. The **last** match in that list pass sets the outcome (not first-match like Access restrictions).
4. Each `Cookie` header field is processed separately; denied fields are erased from the header list.
5. Domain, path, and expiry filters on a row apply only when Direction is **IN** (Set-Cookie). The live request/response header hooks call filtering with outbound (`Cookie`) direction only. Set-Cookie rows are configured for server→browser cookies but are not applied by the active `filter_cookies` path in this tree.
**Order matters.** Put specific host or profile rules above broad catch-alls. Because the last match in a list pass wins, a lower row can override an upper row in the same list.
**IN direction is configured but not enforced.** Domain/Path/expiry filters on IN (Set-Cookie) rows are evaluated in code. But the active `filter_cookies` path only calls filtering for OUT (browser→server `Cookie`) direction. Do not rely on an IN row to block a server's `Set-Cookie` in the current build.
## Section fields
The console splits Cookie filter into three tabs. **Allow** and **Deny** use an identical row
form — only their position in the walk and the meaning of a match differ — so the row fields are
documented once, under **Allow**.
## Global fields
* **Enabled (`enabled`)** — off means `Cookie` and `Set-Cookie` headers pass through unmodified.
* **Policy (`policy`)** — the walk-order selector described above, and also the default action when no configured row matches a cookie: **Allow** forwards it, **Deny** strips it.
## What an Allow row does
A matching Allow row keeps the cookie field. With Policy **Deny**, the Allow list is walked
**first** and is the only thing that lets a cookie through; with Policy **Allow**, it is
walked **second** and can restore a field the Deny pass stripped. The **last** matching row
in the pass wins, so a lower row overrides a higher one.
## Row fields
* **Profiles** — Limit the row to connections that carry these Access Profile tags. Blank ignores profiles. Prefix `!` negates a tag.
- **The built-in `Read Only` profile** is meant for Deny rows: apply it to a connection and matching cookies are blocked. So the user cannot stay signed in to that site. See the `cookie_profiles` catalog in [Suggested profiles](/configuration/custom_settings/suggested_profiles).
- **Direction** — **OUT** — browser→server `Cookie` headers (what the live hooks filter). **IN** — server→browser `Set-Cookie` (domain, path, expiry tests in code; not invoked by current hooks). **BOTH** — either direction when filtering runs.
- **Domain / Path** — Regular expressions. Used for Direction IN when Set-Cookie filtering runs. For OUT rows, only profiles and direction are tested.
* **Domain regex accepts pipe-separated alternatives** — for example `safesquid.com|google.com`. Applies only when Direction is IN, per the warning above.
* **Expiry ranges / Time match mode** — Apply only to Set-Cookie with a parseable `Expires` attribute. **ABSOLUTE** — one continuous window from start through end fields. **ALL RANGES** — expiry must satisfy every configured range at once.
- **Expiry range fields (internal names)** — `year`, `month`, `day`, `weekday`, `hour`, `minute` — inclusive bounds tested against the cookie's own `Expires` attribute, not the appliance clock. For example, an hour range of 1–10 matches a cookie that expires between 1 AM and 10 AM. Configured but not enforced today — see the IN direction warning above.
* **`comment`** — an operator note only; does not affect matching.
## What a Deny row does
A matching Deny row strips the cookie field from the header list and adds
`Clear-Site-Data: "*"` to the connection. With Policy **Deny** the Deny list is walked
**second**, so it can revoke something the Allow pass permitted; with Policy **Allow** it is
walked **first**. Last match in the pass wins.
The built-in **Read Only** profile is intended for Deny rows: apply it to a connection and
matching cookies are blocked, so the user cannot stay signed in to that site.
Rows use the same form as the Allow list — see the **Allow** tab for every field.
## Examples
Open **Configure → Restriction Policies → Privacy control → Cookie filter**. The **Global**
sub-tab holds the Enabled switch and the Policy (Allow/Deny); **Allow** and **Deny** are
separate sub-tabs holding the override row lists.
![SafeSquid console showing the Privacy control Cookie filter Global tab, with the Edit Policy icon circled]()
### Deny by default, allow intranet SSO cookies
* Policy: **Deny**
* Allow row: Profiles `Staff`, Direction OUT, Domain `corp\.example\.com`
**Result:** staff users keep `Cookie` headers for `corp.example.com`. All other outbound cookies on matching requests are stripped and `Clear-Site-Data: "*"` is added when any cookie is dropped.
### Last match in Allow list wins
* Policy: **Deny**
* Allow row 1 (top): Domain `.*` — permits all
* Allow row 2 (below): Profiles `Guest`, Direction OUT — no domain
**Result:** for Guest connections, row 2 is the last Allow match and permits cookies. For others, row 1 is the last Allow match.
## How to verify
1. From a test client, browse a site that sets cookies and watch the browser devtools Network tab for request `Cookie` headers upstream of SafeSquid.
2. Open **Reports → Detailed logs**. Look for `filter_name` related to cookies and native `cookie:` lines when COOKIE is enabled in `LOG_LEVEL`.
3. Check debug response header `X-Cookie-Filter` on the connection (`Dropped-Cookie-Out` when cookies were stripped).
4. Enable **Trace Entry** on one row to confirm profile and domain matching in Native logs.
5) Confirm the appliance and the browser agree on direction — **OUT** is what the browser sends, **IN** is what the website sets. A Domain or Path filter that never seems to match is most often pointed at the wrong Direction.
## Next steps
* **[Header filter](/configuration/restriction_policies/privacy_control/header_filter)** - strip or inject HTTP headers on client requests and server responses using global, allow, deny, and insert rules.
* **[Elevated Privacy](/configuration/restriction_policies/privacy_control/elevated_privacy)** - reduce cross-site tracking by stripping third-party cookies and selected tracking headers.
* **[Suggested Profiles](/configuration/custom_settings/suggested_profiles)** - legacy reference: the autocomplete catalog of ready-made profile names in the Web UI. This section is not in the current Configure console.
# Elevated Privacy
Source: https://docs.safesquid.com/configuration/restriction_policies/privacy_control/elevated_privacy
Reduce cross-site tracking by stripping third-party cookies and selected tracking headers.
# Reduce Cross-Site Tracking With Elevated Privacy
Open **Configure → Restriction Policies → Privacy control → Elevated Privacy**. This section sits under the **Privacy control** menu group alongside [Cookie filter](/configuration/restriction_policies/privacy_control/cookie_filter), [Header filter](/configuration/restriction_policies/privacy_control/header_filter) and [Elevated Privacy](/configuration/restriction_policies/privacy_control/elevated_privacy) — configure them together, since a Cookie filter allow row and an Elevated Privacy STANDARD row can otherwise fight over the same header.
The `Elevated` section reduces cross-site tracking by stripping third-party cookies and selected tracking headers. Without it, third-party cookies and related trackers can follow users from site to site.
## Core mechanics
### First match wins
On each request and response header pass, enabled Elevated policy rows are walked top to bottom. The **first** matching row sets the privacy level for that connection; later rows are skipped.
### Privacy levels (action field)
* **NOT-REQUIRED** — No stripping; bypass elevated privacy.
* **LOW** — Drop third-party Cookie and Set-Cookie when cookie flag set.
* **STANDARD** — LOW plus remove Referer and Origin on outgoing requests.
* **PARANOID** — STANDARD plus remove User-Agent (may break browser-variant sites).
Changes are logged to the privacy log and Detailed logs with filter name Elevated-Privacy. Debug header `X-Elevated-Privacy` reports level when Send Debugging Headers includes client.
```mermaid theme={null}
flowchart TB
hdr[Request or response headers] --> walk[Walk Elevated rows top-down]
walk --> match{First enabled profile match?}
match -->|No| none[No elevated changes]
match -->|Yes| level{Privacy level}
level -->|NOT-REQUIRED| none
level -->|LOW| cookies[Strip third-party cookies]
level -->|STANDARD| cookies --> stripRO[Remove Referer Origin]
level -->|PARANOID| stripRO --> stripUA[Remove User-Agent]
```
### Global fields
* **Enabled (`enabled`)** — master switch. When off, request and response header processing exits without changing any headers.
### Important entry fields
* **Profiles (`profiles`)** — limits the row to connections carrying the listed Access Profiles; blank matches every connection.
* **Privacy Levels (`action`)** — NOT-REQUIRED, LOW, STANDARD, or PARANOID, applied when this row is the first match.
* **Comment (`comment`)** — operator note only; does not affect matching.
## Examples
Open **Configure → Restriction Policies → Privacy control → Elevated Privacy → Elevated
policies**. Rows are tested top to bottom; the first enabled match sets the level for the
connection.
![SafeSquid console showing Elevated Privacy policy rows with NOT-REQUIRED, PARANOID, and LOW privacy levels, the Edit Policies icon on the first row circled]()
### Paranoid for guests, bypass for staff
* **Configuration:** Row A Profiles STAFF NOT-REQUIRED; Row B blank PARANOID.
* **Result:** staff keep full headers; others get paranoid stripping.
### Cookie-only for marketing
* **Configuration:** Profiles MARKETING USERS, Privacy Levels LOW.
* **Result:** only third-party cookies stripped; Referer and User-Agent remain.
### Standard privacy for everyone
* **Configuration:** One row, Profiles blank, Privacy Levels STANDARD.
* **Result:** every connection has third-party cookies dropped and Referer/Origin removed from outgoing requests.
Start with LOW or STANDARD before PARANOID — removing User-Agent breaks some applications. Place NOT-REQUIRED bypass rows above broad PARANOID rows.
## How to verify
1. Browse multi-site flow; inspect request headers upstream of proxy.
2. Check `privacy.log` under Reports.
3. Enable elevated log level for native privacy lines.
4. Debug header `X-Elevated-Privacy` on client when configured.
## Next steps
* **[Cookie filter](/configuration/restriction_policies/privacy_control/cookie_filter)** - control which HTTP cookies pass between clients and servers using a global policy plus allow and deny override lists.
* **[Header filter](/configuration/restriction_policies/privacy_control/header_filter)** - strip or inject HTTP headers on client requests and server responses using global, allow, deny, and insert rules.
# Header filter
Source: https://docs.safesquid.com/configuration/restriction_policies/privacy_control/header_filter
Strip or inject HTTP headers on client requests and server responses using global, allow, deny, and insert rules.
# Strip or Inject Headers With the Header Filter
Open **Configure → Restriction Policies → Privacy control → Header filter**. This section sits under the **Privacy control** menu group alongside [Cookie filter](/configuration/restriction_policies/privacy_control/cookie_filter), [Header filter](/configuration/restriction_policies/privacy_control/header_filter) and [Elevated Privacy](/configuration/restriction_policies/privacy_control/elevated_privacy) — configure them together, since a Cookie filter allow row and an Elevated Privacy STANDARD row can otherwise fight over the same header.
The `Header-filtering` section (`safesquid-header-filtering(5)`) allows administrators to strip out or inject HTTP headers into client requests or server responses.
```mermaid theme={null}
flowchart TB
field[Header field] --> policy{Policy Deny or Allow?}
policy -->|Deny| walkA1[Walk Allow list]
policy -->|Allow| walkD1[Walk Deny list]
walkA1 --> walkD2[Walk Deny list]
walkD1 --> walkA2[Walk Allow list]
walkD2 --> first[First matching row decides field]
walkA2 --> first
first --> result{Allow or strip?}
result -->|Allow| keep[Field kept]
result -->|Deny| strip[Field stripped]
keep --> insert[Insert rows apply cumulative]
strip --> insert
```
## Core mechanics
Allow/Deny list order (**first** match wins, unlike Cookie filter's last-match rule), Insert with variable expansion.
* **Dual-List Policy Engine**: Header filtering utilizes a global Allow/Deny switch. If the global policy is set to `Allow`, SafeSquid first scans the Deny List to strip headers (`action = FALSE`), then evaluates the Allow List to preserve exceptions.
* **Insertion Engine**: Independent of the filter list, the `Insert` list injects entirely new headers into the stream. The inserted headers undergo variable expansion, meaning runtime variables (like usernames or IP addresses) can be dynamically injected into the header value.
* **Flags Targeting**: Both filter and insert rules target either the Request, Response, or Both (`which & flags`).
### How SafeSquid processes the lists
1. For each header field on the message being filtered:
2. If Policy is **Deny**, SafeSquid walks **Allow** first, then **Deny**.
3. If Policy is **Allow**, SafeSquid walks **Deny** first, then **Allow** (Allow can restore a field Deny removed, and vice versa on the second pass).
4. Within each list pass, the **first** matching row decides allow or strip for that field.
5. Stripped fields are removed and logged as `removed` in native header logs.
6. Insert runs after allow/deny. Both **Type** and **Value** must be non-empty; Value supports connection variables.
7. A field that is kept (not stripped) is logged as `allowed`, alongside the `removed` note in step 5.
8. Insert rows are cumulative, not first-match — more than one enabled, matching Insert row can add a header to the same message.
**Order matters.** On Allow/Deny rows, put specific regexes above broad ones — first match in that list pass wins for each field.
## Section fields
The console splits Header filter into five tabs. **Allow** and **Deny** share one row form, so
the fields are documented once under **Allow**; **Insert** reuses the same fields with different
meanings, called out in that tab.
## Global fields
* **Enabled (`enabled`)** — turns Header filter on or off for all connections, unless the matching Access entry's **Bypass** grants **Header filtering**.
* **Policy (`policy`)** — the default outcome when no Allow/Deny row matches a header field: **Deny** strips it, **Allow** forwards it. It also decides which list is walked first (see step 2–3 above).
## What an Allow row does
A matching Allow row keeps the header field. With Policy **Deny** the Allow list is walked
**first**; with Policy **Allow** it is walked **second**, where it can restore a field the
Deny pass stripped. The **first** matching row in that pass decides the field — the opposite
of Cookie filter's last-match rule — so put specific regexes above broad ones. A kept field
is logged as `allowed`.
## Row fields
* **Enabled (`enabled`)** — disabled rows are skipped and never match.
* **Comment (`comment`)** — operator note; shown only in the configuration, never to end users.
* **Profiles** — Apply only when the connection has one of these profiles. Blank = all connections. Prefix `!` to skip connections that have a profile (for example `!Guest`).
* **Type** — On Allow/Deny: regex on the header field name (for example `Referer`, `User-Agent`); blank matches any name. On Insert: literal header name to add (not a regex).
* **Value** — On Allow/Deny: regex on the field value; blank matches any value. On Insert: header body with variables expanded.
* **Applies to** — **CLIENT HEADER** — request headers (browser → origin). **SERVER HEADER** — response headers (origin → browser). Row must include the direction being filtered.
- **Internal field names** — Profiles is `profiles`, Type is `type`, Value is `value`, Applies to is `which`.
- **Insert non-blank requirement** — both Type and Value must be non-blank for an Insert row to apply.
## What a Deny row does
A matching Deny row strips the header field from the message and logs it as `removed` in the
native header logs. With Policy **Deny** the Deny list is walked **second**; with Policy
**Allow** it is walked **first**. First match in that pass wins.
Stripping the destination's own `Content-Security-Policy` with a Deny row is a prerequisite
for writing your own — see the **Insert** tab.
Rows use the same form as the Allow list — see the **Allow** tab for every field.
## What an Insert row does
Insert runs **after** the allow/deny pass and adds entirely new headers rather than filtering
existing ones. It is **cumulative, not first-match**: every enabled matching Insert row can
add a header to the same message.
Three fields behave differently here than on an Allow/Deny row:
* **Type** — a literal header name to add, not a regex.
* **Value** — the header body, with connection variables expanded at runtime, so a username
or client IP can be injected dynamically.
* Both **Type** and **Value** must be non-blank or the row does not apply.
## Content-Security-Policy tiers
Content-Security-Policy (CSP) is a response header that controls what an already-loaded page is allowed to do — which hosts its scripts may connect to, whether it may embed frames, whether it may submit forms elsewhere. Insert rows can write one, which makes Header filter a meaningful defense even for destinations you have chosen to allow: a legitimate site can still be abused to run injected scripts, load third-party tracking, or exfiltrate data to an unexpected destination.
**Browsers combine multiple CSP headers by intersecting them**, taking whichever directive is more restrictive. A SafeSquid-authored CSP only takes clean effect if the destination's **own** `Content-Security-Policy` is stripped first with a Deny row. Skip that step and the browser merges the two. The practical result is usually **more** restrictive than intended, and pages can appear broken (missing fonts, broken widgets) for reasons that are not obvious from the Insert row alone.
SafeSquid's built-in Profile catalog offers three tiers of increasing openness, applied via an Access Profile and referenced from Insert rows:
* **Minimal content access** — baseline. Same-origin scripts and forms only; `connect-src` and `script-src` are restricted to the page's own host, and violations are reported back to SafeSquid.
* **Standard content access** — relaxes `connect-src` and `child-src` to the page's own host domain, while keeping the other directives as tight as the minimal tier.
* **Full content access** — removes the added restriction once a connection is confirmed trustworthy.
See the `header_filter_profiles` catalog in [Suggested profiles](/configuration/custom_settings/suggested_profiles), which names these same tiers plus `DROP ORIGINAL CSP`.
## View headers
A read-only, unfiltered table (**type** / **value** columns) showing the headers on the
request that loaded the panel itself — Host, Proxy-Connection, Content-Length,
X-Requested-With, User-Agent, Accept, Content-Type, Origin, Referer, Accept-Encoding,
Accept-Language in this build. The console's own description calls these "example headers,"
confirming the panel is a live worked example of one request rather than a running log across
your traffic — use it to see the exact header names and casing your browser sends, to build
Allow, Deny and Insert rows against real names instead of guessing them. No filter or export
control is present.
## Examples
Open **Configure → Restriction Policies → Privacy control → Header filter**. Five sub-tabs:
**Global** (Enabled/Policy), **Allow**, **Deny**, **Insert**, and **View headers** — the last
lets you inspect real header names and values from a live connection before writing regexes.
![SafeSquid console showing the Privacy control Header filter Global tab with its five sub-tabs, the Edit Policy icon circled]()
### Strip Referer on all users except marketing
* Policy: **Deny**
* Allow row: Profiles `Marketing`, Type `Referer`, Applies to CLIENT HEADER
**Result:** every client request loses the `Referer` field except connections with the Marketing profile, which keep it.
### Insert a custom request header
* Insert row: Type `X-Proxy-User`, Value `$_USERNAME_$`, Applies to CLIENT HEADER
**Result:** after filtering, matching connections get `X-Proxy-User` added to the forwarded request with the expanded username variable.
### Enforce a Content-Security-Policy correctly
* Deny row: strips the response's own `Content-Security-Policy` field on all connections.
* Insert row: applies the minimal-access CSP tier to all connections by default.
* Insert row: gated to a line-of-business Profile, applies the standard-access tier instead.
**Result:** every response gets a clean, SafeSquid-authored CSP instead of a merged one. Most sites run under the tight, same-origin-only policy. The one tool that needs to reach its own backend gets the slightly more permissive tier.
### Allow everything, hide the server banner
* Policy: **Allow**
* Deny row: Type `Server`, Applies to SERVER HEADER
**Result:** the `Server` field is stripped from every response, hiding the origin's web-server signature. All other fields pass through unless another Deny row matches.
## How to verify
1. Use **View headers** in the Web UI to capture real header names and values before writing regexes.
2. Enable HEADER in `LOG_LEVEL` and read native `removed:` / `added:` lines.
3. Open **Reports → Detailed logs** while reproducing from a known client.
4. Enable System configuration debug response headers (see [Debug response headers](/configuration/start_here/debug_response_headers)) to inspect policy outcomes on the wire.
5) Use browser devtools to confirm the `Content-Security-Policy` header a page actually received matches the tier you intended. A page that looks broken after adding a CSP entry is the classic symptom of the site's own CSP not having been stripped first.
## Next steps
* **[Cookie filter](/configuration/restriction_policies/privacy_control/cookie_filter)** - control which HTTP cookies pass between clients and servers using a global policy plus allow and deny override lists.
* **[Elevated Privacy](/configuration/restriction_policies/privacy_control/elevated_privacy)** - reduce cross-site tracking by stripping third-party cookies and selected tracking headers.
* **[Suggested Profiles](/configuration/custom_settings/suggested_profiles)** - legacy reference: the autocomplete catalog of ready-made profile names in the Web UI. This section is not in the current Configure console.
# Speed Limits
Source: https://docs.safesquid.com/configuration/restriction_policies/speed_limits
Cap bandwidth, connection counts, and transfer sizes per profile so no single user consumes the proxy's capacity.
# Cap Bandwidth Per Profile With Speed Limits
```mermaid theme={null}
flowchart TB
req[Request on connection] --> match[Evaluate every enabled row matching Profiles]
match --> reqLimit{Request limit exceeded?}
reqLimit -->|Yes| block429[HTTP 429 + row Template]
reqLimit -->|No| bytes{Remaining transfer bytes reach 0 tightest cap?}
bytes -->|Yes| blockXfer[Block further transfer + row Template]
bytes -->|No| rate[Throttle at lowest non-zero Download rate among matching rows]
rate --> counters[Increment counters unless Per-request limit or cache excluded]
```
## What does this section do?
The `Limits` section allows administrators to constrain bandwidth, connection counts, and data transfer sizes on a per-profile basis.
It shares bandwidth fairly and stops any single user or profile from consuming too much capacity. Unlike Access restrictions (first-match-wins) and System configuration's Compression and buffering policies (also first-match-wins), **Speed Limits is cumulative**. Every enabled entry whose Profiles condition matches applies, not just the first.
## Core Mechanics (C++ Source Validation)
Token-bucket rate, quota counters, request cap enforcement.
* **Bandwidth Shaping**: SafeSquid utilizes a token-bucket mechanism. Connections are assigned to a specific `LimitGroup`. The traffic shaper enforces the `downloadrate` throttle globally across all connections in that group.
* **Quota Tracking**: Global and per-user transfer quotas (`maxdownloadbytes`, `maxuploadbytes`, `maxrequests`) are updated incrementally as payloads are flushed. Cached payloads (`CONNECTION_CACHING`) can be configured to bypass quota deductions (`LIMIT_CACHE`).
* **Enforcement**: If a connection violates `maxrequests`, the connection action is instantly set to block, serving the block template with a `LMS_TOO_MANY_REQUESTS` status and generating a `TCP_DENIED` log entry.
## Schema Fields
### Global Fields
* **Enabled (enabled)**: Toggles the entire Limits subsystem on or off.
### Rule-Based Fields (Per Connection Tuning)
* **Enabled (enabled)**: Toggles the specific rule.
* **Comment (comment)**: User description of the rule.
* **Profiles (profiles)**: The trigger condition. The rule applies if the connection has this tag. Blank matches every connection; a Profile written with a leading `!` matches connections that do not carry it.
* **Action (action)**: `Allow` or `Deny`. Verified on this build to have no runtime effect — see the note below.
* **Template (templ)**: Name of the block-page template shown when this entry matches. Blank uses `blocked`. Built-in examples: `maxbandwidth`, `maxrequests`.
* **Download transfer limit (maxdownloadbytes)**: Maximum bytes a client can download before being blocked, counted since the last counter reset (\~10 s). `0` = no cap from this row for that direction.
* **Upload transfer limit (maxuploadbytes)**: Maximum bytes a client can upload before being blocked, counted since the last counter reset (\~10 s). `0` = no cap from this row for that direction.
* **Request limit (maxrequests)**: Maximum number of HTTP requests allowed within the tracking window (\~10 s). `0` = unlimited. Exceeded → HTTP 429.
* **Download rate (downloadrate)**: Bandwidth throttle (e.g., bytes per second) applied to downloads. `0` = no rate from this row. Lowest non-zero matching rate wins.
* **Adjust Transfer Limits (flags)**: Modifier flags for how limits are enforced or tracked.
## Troubleshooting
Check `/var/log/safesquid/native/safesquid.log` for limit enforcement messages. A client hitting a quota will typically receive a 429 with a specific limit-exceeded template.
## How SafeSquid processes the list
1. On each relevant request, every enabled row matching profiles is evaluated.
2. **Request limit** exceeded → HTTP 429 and the row Template block page, regardless of the row's **Action** field — see the note below.
3. **Download / upload transfer limits** — remaining bytes are the tightest cap among matching rows. When remaining reaches 0, further transfer on matching connections is blocked and the row's Template block page is shown (built-in example: `maxbandwidth`).
4. **Download rate** — lowest non-zero rate among matching rows wins for throttling.
5. **Adjust Transfer Limits** flags: Limit cache transfers (count cached responses), Per-request limit (do not accumulate row counters at connection end — each request gets full quota), Group limit (share download rate bucket across matching connections).
6. After connections complete, byte and request counters increment for matching rows (unless Per-request limit or cache exclusion applies). Counters clear on the periodic reset.
**Action has no runtime effect.** The console's own field help describes Action as enforced — set `Deny` and matching requests are blocked outright, set `Allow` and limits apply until a cap is reached — but a live behavioural test (a disposable profile tag, Action set to `Deny`, numeric caps set high enough to never trigger) showed the connection tagged and evaluated correctly, then proceeding past this section entirely rather than being blocked. Only the numeric caps (Download/Upload transfer limit, Request limit, Download rate) actually gate a connection. Set `Action` to whichever value documents your intent, since either behaves identically.
## Important entry fields
* **Profiles** — Limit to connections with these Access Profile tags. Typical tags: `RESTRICTED DOWNLOAD TRANSFER RATES`, `RESTRICTED UPLOAD TRANSFER RATES`.
* **Action** — Verified to have no runtime effect on this build. The console's own field help describes it as enforced, but only the numeric caps below actually block a connection. See the note above.
* **Template** — Block page shown when this entry matches. Blank uses `blocked`. This same field also covers download/upload transfer-limit overruns: the console names a `maxbandwidth` template for excessive bandwidth, paired with `maxrequests` for excessive requests. Both are shown to the user through this field, not a separate default/bypass path.
* **Download / Upload transfer limit** — Maximum bytes counted against this row since last counter reset (\~10 s). `0` = no cap from this row for that direction.
* **Request limit** — Maximum requests counted since last reset. `0` = unlimited. Exceeded → HTTP 429.
* **Download rate** — Throttle in bytes/sec. `0` = no rate from this row. Lowest non-zero matching rate wins.
* **Adjust Transfer Limits** — Limit cache transfers, Per-request limit, Group limit — see processing order above.
## Examples
Open **Configure → Restriction Policies → Speed Limits → Set limits**. Each row shows Enabled,
Comment, Profiles, Action, Download/Upload transfer limit, Request limit, Download rate, and
Adjust Transfer Limits.
![SafeSquid console showing Speed Limits rows with Download rate and transfer limit fields, the Edit Policies icon on the first row circled]()
### 1 — Guest download cap and throttle
* Profiles: `Guest`
* Download transfer limit: 50 MB, Download rate: 512000 bytes/sec
**Result:** Guest connections download at most \~500 KB/s and stop receiving data once 50 MB is consumed within the current counter window. Other profiles without matching rows are unaffected.
### 2 — Request flood cap
* Request limit: **100**, Template: `too-many-requests`
**Result:** after 100 counted requests in the reset window, the next matching request gets HTTP 429 and the template block page.
### 3 — Per-request 5 MB (not shared window)
* Download transfer limit: 5 MB, Adjust Transfer Limits: **Per-request limit**
**Result:** each single request may transfer up to 5 MB; counters are not accumulated at connection end for this row. So the cap applies per request rather than shared across the \~10 s window.
### 4 — Two matching rows tighten together
* Row A: Download rate 1 MB/s
* Row B: Download rate 256 KB/s, same profiles
**Result:** both rows match; lowest non-zero rate (256 KB/s) is applied. If both set byte caps, the tightest remaining bytes win.
## How to verify
1. Assign a test profile and reproduce large download or many parallel requests.
2. Enable LIMITS in `LOG_LEVEL` for native `limits:` download/upload limit and rate lines.
3. Open **Reports → Detailed logs**. Blocked transfers show `filter_name` for limits and reason such as `Max Requests` or upload limit text.
4. Confirm counter reset behaviour by waiting \~10 seconds and retrying after hitting a window cap.
5. If an entry seems to have no effect at all, check the section-wide **Enabled** switch first, then confirm the entry's **Profiles** actually matches the connection under test — and remember **Action** has no bearing on whether the entry is active.
## Next steps
* **[Access Profiles](/configuration/restriction_policies/access_profiles)** - decide what each user can fetch by combining time, request type, response type, category, and group labels into ordered allow and deny rules.
# Architecture and request pipeline
Source: https://docs.safesquid.com/configuration/start_here/architecture
Follow a request through SafeSquid from admission and identity, through protocol fork and enforcement, to fetch and response delivery.
# Trace Request Pipeline Architecture From Admission to Response
SafeSquid sits between client browsers and the Internet (or upstream proxies). Each connection is handled by a worker that processes one HTTP transaction at a time, or a CONNECT tunnel for HTTPS.
Setting up for the first time? Follow [First configuration](/configuration/start_here/first_configuration). The sections below show how the pieces fit together.
## Two configuration layers
* **Web UI (policy)** — Access restrictions, Access Profiles, filters, scanners, and so on. Stored as sections in `config.xml`. This is what most administrators edit daily.
* **startup.ini (process)** — Listen fallback, threads, log levels, TLS and sync tunables. Edited on the appliance filesystem — see [startup.ini](/configuration/start_here/startup_ini).
## What to configure first
This is setup order, not the order a live request is processed.
```mermaid theme={null}
flowchart TB
net["Network settings — the listen port"]
access["Access restrictions — who may use the proxy, including login if you require it"]
profiles["Access Profiles — which sites and content"]
rest["HTTPS Inspection · antivirus · filters · Caching"]
net --> access --> profiles --> rest
rest -.->|reuse the people and labels defined above| profiles
```
1. [Network settings](/configuration/application_setup/network_settings_and_listeners) — where SafeSquid listens
2. [Access restrictions](/configuration/application_setup/access_restrictions) — who may connect, login if required, HTTP vs HTTPS rights
3. [Access Profiles](/configuration/restriction_policies/access_profiles) — which sites and content to allow
4. **Everything else** — HTTPS Inspection, scanners, cookie/header filters, Caching
## What happens to a request
Names below are the Web UI section titles, in the order SafeSquid calls them. A request is **either HTTPS or HTTP**, never both in sequence. Access Profiles Deny is remembered early and only enforced later. [DLP](/configuration/real_time_content_security/dlp), [Clam antivirus](/configuration/real_time_content_security/clam_antivirus), and [SqScan](/configuration/real_time_content_security/sqscan) are queued as their own steps (upload, then downloaded body). The pipeline is drawn below in three stages: admission and identity, the HTTPS/HTTP fork and enforcement, then fetch and delivery. Yes-branches stop; No-branches continue down.
### Stage 1 — admission and identity
```mermaid theme={null}
flowchart TB
listen["Network settings — already listening on the port the browser uses"]
sysconf["System configuration — timeouts, buffers, CONNECT port range, used later"]
read["Read the request — which site, which page, HTTP or HTTPS"]
unsafe{"Destination unsafe or internal?"}
isui{"Host is the Web UI, safesquid.cfg?"}
uiaccess["Access restrictions — who may open the console"]
uishow["Show the Web UI — STOP"]
labels["Time Profiler · Application Signatures · Request Types · Categorize Web-Sites · SSqore"]
remember["Access Profiles — remember Allow or Deny, do not block yet"]
identity["Access restrictions — Integrate LDAP consulted here; External applications may assist login"]
rerun["Access Profiles — run again, User-Groups can change the match"]
stop["Templates — block page or login prompt, STOP"]
listen --> sysconf --> read --> unsafe
unsafe -->|Yes| stop
unsafe -->|No| isui
isui -->|Yes| uiaccess
uiaccess -->|Refused, or login challenge| stop
uiaccess -->|Allowed| uishow
isui -->|No| labels --> remember --> identity
identity -->|Must log in, or not allowed| stop
identity -->|HTTP, HTTPS, Bypass rights and User-Groups resolved| rerun
```
The Web UI path deliberately skips Time Profiler, Application Signatures, Request Types,
Categorize Web-Sites, SSqore **and** Access Profiles — an Access Profiles Deny cannot lock you
out of the console. SSqore runs only if the site is still uncategorized, and none of the
labelling sections block; they only attach labels.
### Stage 2 — protocol fork and enforcement
```mermaid theme={null}
flowchart TB
limits["Speed Limits — can delay or block; System configuration may hold a large upload"]
modify["Content modifier · External applications · ICAP · HTTPS Inspection · Subscription"]
fork{"HTTPS or HTTP — never both in sequence"}
connect["Access restrictions — CONNECT right"]
ports["System configuration — CONNECT port range"]
decrypt{"HTTPS Inspection decrypts?"}
restart["Start again at Read the request"]
tunnel["Continue as a tunnel"]
rights["Access restrictions — HTTP, proxy, transparent rights"]
redirect{"Redirect — first match?"}
found["302 to the client — STOP"]
enforce{"Access Profiles — now enforce the remembered Deny"}
body{"Request has an upload body?"}
upscan["Application Signatures · Request Types · Access Profiles · Clam antivirus · SqScan · Image analyzer · DLP"]
onward["Continue to fetch"]
stop["Templates — block page, STOP"]
limits --> modify --> fork
fork -->|HTTPS| connect
connect -->|No CONNECT right| stop
connect -->|Allowed| ports
ports -->|Port out of range| stop
ports -->|In range| decrypt
decrypt -->|Yes| restart
decrypt -->|No| tunnel --> enforce
fork -->|HTTP| rights
rights -->|Not allowed| stop
rights -->|Allowed| redirect
redirect -->|Match| found
redirect -->|No match| enforce
enforce -->|Deny, and no temporary bypass| stop
enforce -->|Allow| body
body -->|Yes| upscan
upscan -->|First of these that denies| stop
upscan -->|Pass| onward
body -->|No| onward
```
HTTPS Inspection does not continue the outer HTTPS request — it decrypts and runs the inner
HTTP from **Read the request** again, so Stage 1 repeats for the decrypted request. DLP
inspects this upload only, never the page that comes back.
### Stage 3 — fetch, response, and delivery
```mermaid theme={null}
flowchart TB
cache["Caching"]
dnsbl{"DNS Blacklist — matching block policy?"}
chain["Proxy chain — upstream proxy or direct; rows naming this proxy are skipped, so a request cannot loop back"]
open["Open the connection to the peer or origin — reuse an idle pooled connection when one exists, else new TCP and DNS"]
outbound["Header filter · Cookie filter · Elevated Privacy · Content modifier — on headers sent to the origin"]
fetch["Fetch the response — cache hit or the Internet"]
rtypes{"Response Types · Access Profiles — MIME and response labels"}
dscan{"SqScan · Clam antivirus · Image analyzer · Text analyzer · ICAP — downloaded body"}
tail["Prefetching — linked objects in HTML · FTP browsing"]
send["Send the page to the browser · write logs"]
stop["Templates — block page, STOP"]
cache --> dnsbl
dnsbl -->|Yes| stop
dnsbl -->|No| chain --> open --> outbound --> fetch --> rtypes
rtypes -->|Deny| stop
rtypes -->|Pass| dscan
dscan -->|Malware or content match| stop
dscan -->|Pass| tail --> send
```
Only **buffered** responses are scanned — a streamed response passes the download scanners
unexamined. DLP does not run on the response at all. FTP browsing handles `ftp://` only:
Access restrictions gate the client first, and the FTP `USER`/`PASS` exchange is a separate
login to the remote server, not proxy authentication. Connection pool size and timeout are
System configuration fields.
A few details from the walk above are easy to misread:
* **Access Profiles runs more than once per request, and that is normal.** The walk calls it at least four separate times — before identity is known, again once identity resolves, again after the request-modify stage, and again once an upload's content type is known — plus further checks against response headers and downloaded content. Each call re-evaluates against whatever labels and identity exist at that point. The repetition is how an early verdict only gets enforced once the right stage is reached, not a duplicate check to remove.
* **Incomplete requests are dropped silently.** If the client disconnects before sending a complete request, the connection is simply dropped at "Read the request". There is nothing to inspect and nothing to log as a policy decision.
* **Speed Limits can apply before Access restrictions has finished granting the connection's full rights** at the HTTP/HTTPS protocol branch further down this walk — worth knowing if a limit appears to take effect earlier than expected.
Open a section: [Network settings](/configuration/application_setup/network_settings_and_listeners) · [System configuration](/configuration/application_setup/system_configuration) · [Templates](/configuration/custom_settings/templates) · [Time Profiler](/configuration/custom_settings/time_profiler) · [Application Signatures](/configuration/custom_settings/application_signatures) · [Request Types](/configuration/custom_settings/request_types) · [Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites) · [SSqore](/configuration/application_setup/ssqore) · [Access Profiles](/configuration/restriction_policies/access_profiles) · [Access restrictions](/configuration/application_setup/access_restrictions) · [Integrate LDAP](/configuration/application_setup/integrate_ldap) · [External applications](/configuration/custom_settings/external_applications) · [Speed Limits](/configuration/restriction_policies/speed_limits) · [Content modifier](/configuration/real_time_content_security/content_modifier) · [ICAP](/configuration/real_time_content_security/icap) · [HTTPS Inspection](/configuration/real_time_content_security/https_inspection) · [Subscription](/configuration/infrastructure_and_access/subscription) · [Redirect](/configuration/real_time_content_security/redirect) · [DLP](/configuration/real_time_content_security/dlp) · [Caching](/configuration/application_setup/accelerators/caching) · [DNS Blacklist](/configuration/real_time_content_security/dns_blacklist) · [Proxy chain](/configuration/application_setup/proxy_chain) · [Header filter](/configuration/restriction_policies/privacy_control/header_filter) · [Cookie filter](/configuration/restriction_policies/privacy_control/cookie_filter) · [Elevated Privacy](/configuration/restriction_policies/privacy_control/elevated_privacy) · [Response Types](/configuration/custom_settings/response_types) · [Clam antivirus](/configuration/real_time_content_security/clam_antivirus) · [SqScan](/configuration/real_time_content_security/sqscan) · [Image analyzer](/configuration/real_time_content_security/image_analyzer) · [Text analyzer](/configuration/real_time_content_security/text_analyzer) · [Prefetching](/configuration/application_setup/accelerators/prefetching) · [FTP browsing](/configuration/application_setup/ftp_browsing)
Open the Web UI at `http://safesquid.cfg/` from a machine that Access restrictions allows. That path skips Access Profiles so you can still fix a mistaken Deny. HTTPS Inspection does not continue this HTTPS request. It decrypts and runs the inner HTTP from Read the request again. **DLP** inspects upload bodies only. **Clam antivirus** and **SqScan** inspect uploads and downloaded bodies.
The **Header filter** module is bypassed for the Web UI path as well, not just Access Profiles content policy. Reaching the console and actually *changing* configuration are also two different rights — Access restrictions governs who may reach the console at all. But applying a change requires a separate console-access right beyond merely reaching it.
**A response over the download buffer size is not scanned.** SqScan, Clam antivirus, Image analyzer, Text analyzer, and ICAP inspect a *downloaded body*. A response SafeSquid buffered before sending it on. The matching **System configuration → Compression and buffering policies** row sets **Maximum download buffer size** (`maxdbuffer`, default `10M`). A response larger than that streams straight to the browser instead — marked `Direct` rather than `Buffered` — and never reaches those scanners. Nothing in the response or the block page announces the skip.
Verified on this build: fetching a 5 MB file (under the 10 MB default buffer) returned both `X-Virus-Scan` and `X-Text-Analyzer` debug headers. An otherwise identical 20 MB file (over the buffer) returned neither. Test your own buffer size the same way. Set **System configuration → Send Debugging Headers To** to `CLIENT` (see [Debug response headers](/configuration/start_here/debug_response_headers)), fetch a file just under and just over the configured size, and compare the response headers. Size the buffer for the file sizes you actually need scanned.
**Elevated Privacy strips in a fixed order as its level rises:** third-party cookies first, then Referer/Origin, then User-Agent. A lower level stops earlier in that order; the strictest level applies all three.
### Example — one blocked HTTPS visit
A user on the LAN opens `https://social.example/` through the proxy:
1. Network settings, Read the request, and the host check pass (public site).
2. Not the Web UI. Time Profiler, Application Signatures, Request Types, then Categorize Web-Sites / SSqore: category may be Social.
3. Access Profiles remembers Deny for Social — no block page yet.
4. Access restrictions already allows this person; they have the HTTPS right.
5. The **HTTPS** branch only (not Redirect). Permission and System configuration CONNECT ports pass. Inspection off: stay on the tunnel.
6. Access Profiles now enforces Deny: **Templates** block page. Detailed logs show which rule fired.
### Example — DLP on upload, malware on download
1. A user POSTs a spreadsheet. After Access Profiles Allow, the upload body is inspected: **Clam antivirus**, **SqScan**, **Image analyzer**, then **DLP**. A DLP MIME policy match sends **Templates** and stops — Caching and the origin never see that body.
2. A later GET of an executable is Allowed by Access Profiles. Caching misses, DNS Blacklist passes, Proxy chain fetches it. **SqScan** or **Clam antivirus** on the downloaded body match: **Templates** block page. DLP does not run on that download.
**Upload scanner order is not fixed.** Which of Clam antivirus, SqScan, Image analyzer, and DLP actually runs first on an upload depends on which scan engines are installed on the appliance, not a built-in fixed order. Whichever module blocks first stops the request there with a block page.
Once Proxy chain has selected a peer, SafeSquid opens the transport before sending the request.
Legacy documentation states that a SOCKS4 or SOCKS5 peer is negotiated first, that a failed
connection attempt is retried a fixed number of times before the request fails, and that the
retry is abandoned if the client has already disconnected.
**Missing:** the retry count, and whether it changes by peer type. Legacy documentation states a
fixed number; nothing on this build corroborates it, and it cannot be exercised without forcing
an upstream failure. Confirm with SafeSquid support before sizing timeouts around a specific
retry budget.
Legacy documentation also states that FTP directory listings are not scanned or categorized, and
that no FTP response — buffered or streamed — gets Response Types categorization or a
response-side Access Profiles check, unlike HTTP.
**Missing:** confirmation of the FTP claim above. It could not be tested in this environment —
there is no network path to an FTP server through the proxy — and no other page in this tree
corroborates or contradicts it.
## Policy matching styles
* **Dual allow/deny lists** — Access restrictions, Cookie filter, Header filter. List order depends on the section default policy.
- **Opposite winners within that pair** — Header filter: the *first* matching entry decides. Cookie filter: the *last* matching entry decides.
- **First match** — Clam antivirus, HTTPS Inspection, Redirect, DNS Blacklist block policies, and several scanners.
- **All matches** — Access Profiles (secondary), Speed Limits, Content modifier, [Application Signatures](/configuration/custom_settings/application_signatures).
* **Cumulative score** — Text analyzer adds up scores across every matching rule instead of stopping at the first, so several mild matches together can block a page no single one would.
* **Last match** — [DLP](/configuration/real_time_content_security/dlp) MIME policies (OCR uses cumulative score vs Threshold).
* **Groups** — Menu groups (Accelerators, Real time content security) contain child sections only. They have no policy lists of their own.
## Verified gaps and non-claims
* **Subscription**, **Content Signatures**, and **Suggested Profiles** are not part of the live pipeline above. Subscription is a licensing/entitlement check that can interrupt the flow at the request-modify stage, not a content-policy stage with its own list of entries. Content Signatures and Suggested Profiles exist as Web UI sections. But neither currently runs against a live request — nothing executes for them in this walk.
* **WCCP** governs how traffic reaches SafeSquid in the first place (network-level redirection so clients need no proxy setting of their own). It is not a step in what happens *after* a request has already arrived. So it is not part of this walk either. Confirm its current working status in your build before relying on it for a transparent deployment.
## Bypass
Access restrictions entries can grant **Bypass** for Header filter, Cookie filter, Redirect, Content modifier, Proxy chain, Text analyzer, DNS Blacklist, antivirus, ICAP, and DLP. That skips those modules for matching clients. Separate from Access Profiles temporary bypass cookies (**Allow bypassing**).
## Debug headers
When **System configuration → Send Debugging Headers To** is CLIENT, SERVER, or BOTH, SafeSquid adds identity and policy headers. Prefer CLIENT only on a test network. See [Debug response headers](/configuration/start_here/debug_response_headers).
## Next steps
* [First configuration](/configuration/start_here/first_configuration)
* [Daemon and service](/configuration/start_here/daemon)
* [Access restrictions](/configuration/application_setup/access_restrictions)
* [Access Profiles](/configuration/restriction_policies/access_profiles)
* [Logging](/configuration/start_here/logging)
* [Application Signatures](/configuration/custom_settings/application_signatures)
* [Clam antivirus](/configuration/real_time_content_security/clam_antivirus)
* [SqScan](/configuration/real_time_content_security/sqscan)
* [DLP](/configuration/real_time_content_security/dlp)
* [SSqore](/configuration/application_setup/ssqore)
* [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds)
* [Full section index](/configuration/main)
# Authentication
Source: https://docs.safesquid.com/configuration/start_here/authentication
Choose how SafeSquid identifies users, including Kerberos SSO and system authentication, so Access Profiles and logs can name them.
# Choose an Authentication Method to Identify Users
SafeSquid identifies users for logging, Access Profiles, and LDAP-based rules. Without authentication, many deployments still work by IP — but Detailed logs show anonymous users and group-based policy is harder.
Configure authentication switches in **Access restrictions**. Configure the directory in **Integrate LDAP**. New users: finish [First configuration](/configuration/start_here/first_configuration) (IP allow) before adding auth.
## Three mechanisms
* **Kerberos / SSO** — Global setting in Access restrictions. When enabled, the browser can sign in with Kerberos Single Sign-On — users do not type credentials in Access entries. Requires a valid keytab at `/usr/local/safesquid/security/HTTP.keytab` and correct domain setup.
* **System authentication** — Per-entry setting. The browser prompts for username and password; SafeSquid validates through PAM (`/etc/pam.d/safesquid`) and optionally LDAP. Use when Kerberos / SSO is off.
* **User name / Password (entry)** — Fixed credentials on an Access row when neither Kerberos / SSO nor System authentication is used for that entry. Fine for a lab admin account; avoid for large user populations.
## Which should I choose?
* **Active Directory domain, browsers joined** — prefer Kerberos / SSO
* **No SSO yet, local or LDAP passwords** — System authentication on Allow entries
* **Single test account** — entry User name / Password
## Kerberos / SSO
The Web UI shows **Kerberos / SSO** (internal tag `ntlm`).
* When enabled, SafeSquid offers Negotiate (GSSAPI/Kerberos) on authenticated connections.
* After success, the username comes from the Kerberos ticket and is logged in Detailed logs.
* When `SUBSCRIPTION_EXPIRED` is set, some modules (Application Signatures, SSqore) skip processing — see [Subscription](/configuration/infrastructure_and_access/subscription).
* If the keytab is missing at startup, Negotiate is not offered even when the UI setting is on.
- **Silent failure, no error anywhere.** A missing or invalid keytab produces no error anywhere in the Web UI. The global switch simply has no practical effect. Clients fall through silently to whatever fallback the matching entry provides (System authentication, a fixed User name/Password), or an outright deny if the entry required identity and offers none.
- **Independent of licensing.** An expired subscription can stop licensed modules such as Application Signatures and cloud categorisation from processing a request further. But it does not itself affect Kerberos / SSO's ability to authenticate the user — these are independent checks.
### Example — turn on SSO after IP allow works
1. Confirm clients already work with an IP-based Allow entry.
2. Install and verify `HTTP.keytab`; restart SafeSquid if needed.
3. Enable **Kerberos / SSO** globally in Access restrictions.
4. Browse again; Detailed logs should show the domain username instead of anonymous.
## System authentication
Enable **System authentication** on an Access Restrictions entry (internal tag `pamauth`). For each login attempt SafeSquid tries, in order:
1. Password cache (recent successful or failed attempts)
2. PAM — typically local Unix accounts via `pam_unix`
3. LDAP bind — when Integrate LDAP is configured and the user DN is known
Cache size and expiry: `PASSWORD_CACHE_SIZE` and `PASSWORD_CACHE_EXPIRE_TIME` in `startup.ini`. View entries under **Reports → Password Cache**.
```mermaid theme={null}
flowchart TB
challenge[Login attempt on an entry with System authentication on]
cache{"Password cache — recent success or failure?"}
pam{"PAM — typically local Unix accounts via pam_unix"}
ldap{"LDAP bind — Integrate LDAP configured and user DN known?"}
done[Definite result — stop here]
fail[No mechanism returned a definite result]
challenge --> cache
cache -->|Definite success or failure| done
cache -->|Not applicable| pam
pam -->|Definite success or failure| done
pam -->|Not applicable| ldap
ldap -->|Definite success or failure| done
ldap -->|Not applicable| fail
```
The order is fixed and evaluation stops at the first **definite** result. A definite *failure*
ends the chain — only a "not applicable" outcome, such as no LDAP configured, falls through to
the next mechanism.
The three checks always run in that fixed order for a given challenge. SafeSquid stops at the first one that returns a definite result. A definite failure at one step is **not** passed through to the next step. Only a "not applicable" result (for example, no LDAP configured) moves on. While System authentication is on for an entry, that entry's own **Password** field is never read at all — **User name** becomes purely a regular-expression filter restricting *who may use this entry*, not a password check.
A stale cached *failure* keeps blocking an already-corrected login until it naturally expires — clearing **Reports → Password Cache** is the standard first step after fixing a password or a directory problem.
### Example — PAM login for the office range
* Allow entry: IP `192.168.10.0-192.168.10.255` (hyphen range, not CIDR)
* **System authentication** — on
* **User name** — blank (any PAM user) or a regex of allowed names
* **Password** — leave blank so PAM checks the secret
**Result:** browser shows a proxy login; success populates username in logs and policies.
## Entry username and password
* **Kerberos / SSO off, System authentication off**. Set User name and Password on the entry; the challenge must match exactly.
* **System authentication on** — list allowed usernames (regex allowed); leave Password blank so PAM or LDAP checks the secret.
* **Kerberos / SSO on** — leave credentials blank on entries; the browser handles sign-in.
## Integrate LDAP
1. Add and enable at least one **LDAP servers** entry.
2. Confirm users and groups in **LDAP Entries**.
3. Use **LDAP Profiles** on Access Restrictions or other policy rows.
LDAP matches directory users and groups to rules, and acts as an authenticator after PAM when System authentication is enabled.
A successful LDAP bind proves the password only. It says nothing on its own about which Access entry or which Access Profile then applies. That still depends on the User-Groups and LDAP Profiles matching Access restrictions performs separately.
### Example — allow only the “ProxyUsers” LDAP group
* Default Access Policy: Deny
* Allow entry: LDAP Profiles match your ProxyUsers profile, System authentication or Kerberos as appropriate
**Result:** only directory members of that group get through, even if they are on the office IP range.
## When is a login prompt shown?
SafeSquid challenges the browser when the matching Access entry has:
* Kerberos / SSO enabled globally and Negotiate has not succeeded yet, or
* System authentication enabled, or
* User name filled in on the entry.
If the entry matches only by IP or interface and none of the above apply, the connection may proceed without a prompt.
The prompt itself is the browser's own native credential dialog, not a page SafeSquid renders.
## Username without a prompt
SafeSquid can assign a username when:
* Kerberos / SSO succeeds
* An IP-to-user map applies (for example VPN clients)
* The client already sent matching Basic credentials for a fixed User name / Password entry
The username appears in Detailed logs; **Add to User-Groups** on the Access entry feeds downstream policies.
## Where authentication runs
Authentication runs early in the pipeline (after Time Profiler and Request Types, before Speed Limits and content filters). Until it completes, SafeSquid may reply with HTTP 407 (proxy) or 401 with `Proxy-Authenticate` or `WWW-Authenticate`. After success, Access rights, Bypass, and User Groups from the matching entry are applied.
Once identity is known, Access restrictions re-walks the same Allow/Deny list with that identity now available. This is the only reason an entry that tests only **LDAP Profiles** can ever match. On the first, identity-less pass it has nothing to test.
## Common problems
* **Repeated login prompts** — Check Kerberos / SSO, SPN, keytab, and clock skew. Clear Password Cache.
* **Valid user denied** — Confirm Allow list match, LDAP Profiles, Interface, and IP. In Detailed logs look for access-related `filter_name`. Also confirm a broader entry above it in the list isn't matching first — see [Access restrictions](/configuration/application_setup/access_restrictions)'s first-match-wins rule.
* **PAM failures** — Review `/etc/pam.d/safesquid`. Native log lines start with `pam:`.
* **LDAP failures** — Enable LDAP in LOG\_LEVEL. Verify Integrate LDAP and LDAP Entries.
- **PAM keeps failing for a known-good desktop account.** A valid desktop account is not automatically a valid PAM account on this appliance — confirm the account is actually usable for a login on the appliance itself.
- **LDAP login fails even though PAM succeeds.** A missing LDAP directory sync is indistinguishable from a bad password from the browser's point of view. Check the user actually appears under LDAP Entries before assuming the password is wrong.
## Verify a successful login
Check **Reports → Password Cache** immediately after a successful login. A fresh entry there confirms the cache step is populating correctly.
## Next steps
* [First configuration](/configuration/start_here/first_configuration)
* [Access restrictions](/configuration/application_setup/access_restrictions)
* [Logging and troubleshooting](/configuration/start_here/logging)
* [Integrate LDAP](/configuration/application_setup/integrate_ldap)
* [Access Profiles](/configuration/restriction_policies/access_profiles)
# Cloud / categorisation feeds
Source: https://docs.safesquid.com/configuration/start_here/cloud_feeds
Understand how SafeSquid categorises sites and refreshes signature databases through cloud feeds, scheduled updates, and local caches.
# Understand Cloud Categorisation Feeds and Updates
SafeSquid categorises websites and refreshes signature databases using cloud services, scheduled updates, and local caches. Categories and signature tags feed [Access Profiles](/configuration/restriction_policies/access_profiles), filters, and Detailed logs.
Valid [Subscription](/configuration/infrastructure_and_access/subscription) is required for cloud signature downloads and for Application Signatures / SSqore processing on each connection. Check **Support → License Details** when feeds stop updating.
## Pieces
* **[SSqore](/configuration/application_setup/ssqore)** — CCS URL categorisation during request profiling. Globals: Enabled (Heuristic is stored but unused in the current build).
* **[Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites)** — Local category overrides you maintain. Takes precedence over cloud results for matching hosts on the hot path.
- **Local override wins outright** — for a host the local editor explicitly covers, the two categorisation sources are not merged. The local override simply wins, even if the cloud disagrees.
- **[Application Signatures](/configuration/custom_settings/application_signatures)** — Vendor `applications4` database plus custom rules. Downloaded on UPDATE schedule; skipped when subscription expired.
- **[Content Signatures](/configuration/custom_settings/content_signatures)** — Vendor `content4.xml` plus libmagic MIME database under `/var/lib/safesquid/content_signatures/`.
* **Detects the actual file type** of a response or upload body, independent of what its filename or declared content type claims.
* **DNS\_CAT\_ZONE** — In [startup.ini](/configuration/start_here/startup_ini) (default `.c.ssquid.in`). Set to `.` to disable DNS categorisation zone use.
* **UPDATE\_INTVL / UPDATE\_RETRY\_DELAY** — How often the appliance fetches signature and feed updates ([startup.ini](/configuration/start_here/startup_ini)).
## Update cycle (overview)
1. Background hooks on the UPDATE schedule call signature updaters (`update_application_signatures`, `update_content_signatures`, and related).
2. Downloaded files land under `/var/lib/safesquid/` (application\_signatures, content\_signatures, ssqore cache, and similar).
3. Config reload or init hooks merge vendor data with custom dev XML from the Web UI.
4. Per-request labelling runs in the pipeline: SSqore and local category editor for website categories; Application Signatures for application tags.
```mermaid theme={null}
flowchart TB
hook["Background hooks fire on the UPDATE schedule"]
fetch["Signature updaters run — update_application_signatures, update_content_signatures, and related"]
land["Downloaded files land under /var/lib/safesquid/"]
merge["Config reload or init hooks merge vendor data with custom dev XML from the Web UI"]
label["Per-request labelling in the pipeline"]
sites["SSqore and the local category editor label websites"]
apps[Application Signatures label applications]
hook --> fetch --> land --> merge --> label
label --> sites
label --> apps
```
Custom rules and local category overrides layer on top of the vendor data at the merge step —
they never replace it.
Custom Application Signature rules, custom Content Signature rules, and local category overrides all layer on top of the vendor data. They do not replace it.
## Offline behaviour
When cloud lookups or downloads fail, SafeSquid relies on the last loaded on-disk databases and SSqore cache entries. New hosts may receive no categories until connectivity returns. Enable CATEGORY log level and check module load status (location to be confirmed).
* Local overrides in Categorize Web-Sites are entirely unaffected by an outage. They never depend on cloud connectivity in the first place.
* Custom Application Signature and Content Signature rules keep working too during an outage: only the vendor database refresh depends on connectivity, not the matching of rules already loaded.
* Previously-seen hosts keep working exactly as before, from the last successful update.
This matters directly for policy: a DENY rule that depends on Categories matching a specific cloud category simply will not fire for an uncategorised new host during an outage. The request is not automatically blocked because categorisation failed, it is only left uncategorised, and whatever the rest of policy says about uncategorised traffic applies to it instead.
## Examples
### Block Social Networking by cloud category
1. Enable [SSqore](/configuration/application_setup/ssqore); confirm subscription valid.
2. In Access Profiles Secondary Policies, DENY when Categories matches the SSqore name for social sites (exact string from Detailed logs).
**Result:** categorized social hosts are blocked; uncategorized hosts may pass until CCS returns a category.
### Override one miscategorised partner
1. Use [Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites) to assign `Business-Partners` to `partner.example.com`.
2. Allow that category in Access Profiles for trusted users.
**Result:** local override applies even if SSqore still lists a different cloud category.
## How to verify
1. Module load status — application/content signature load times and errors. Location in the console to be confirmed.
2. Detailed logs — `categories` and `application_signatures` columns on test URLs.
3. Native logs with CATEGORY enabled for SSqore lines.
4) If categorisation looks stale or wrong, check module load status for the last successful update time before assuming a policy problem. A feed that has not refreshed in a long time behaves very differently from a misconfigured policy. The two are easy to confuse.
## Next steps
* [SSqore](/configuration/application_setup/ssqore)
* [Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites)
* [Application Signatures](/configuration/custom_settings/application_signatures)
* [Content Signatures](/configuration/custom_settings/content_signatures)
* [Subscription](/configuration/infrastructure_and_access/subscription)
* [startup.ini](/configuration/start_here/startup_ini)
* [Access Profiles](/configuration/restriction_policies/access_profiles)
# SafeSquid daemon
Source: https://docs.safesquid.com/configuration/start_here/daemon
Learn how the SafeSquid daemon handles connections and policy, when a change needs a reload or a restart, and how to control the service.
# Control the SafeSquid Daemon
SafeSquid is the main proxy process on the Secure Web Gateway appliance. It accepts client connections, applies policies from the Web UI, and forwards allowed traffic.
## Lifecycle
1. **Start** — the daemon reads its own startup configuration, opens its configured listeners, loads the currently saved policy, and begins accepting connections.
2. **Accept** — each new client connection lands on a configured listener.
3. **Evaluate** — the connection runs through the request pipeline against whichever policy is currently loaded in memory.
4. **Forward or block** — a permitted request is forwarded to its destination. A denied request receives a block response and the connection is closed.
5. **Log** — each completed transaction is logged as it finishes.
6. **React to policy changes** — see [Live policy reload vs restart](#live-policy-reload-vs-restart).
7. **Stop** — on a stop request, the daemon finishes or drops any in-flight connections cleanly and exits.
```mermaid theme={null}
flowchart TB
start[Start — read startup config, open listeners, load saved policy]
accept[Accept — a new client connection lands on a configured listener]
evaluate[Evaluate — run the request pipeline against the policy in memory]
verdict{Permitted?}
forward[Forward the request to its destination]
block[Return a block response and close the connection]
log[Log the completed transaction]
react{Policy changed?}
reload[Apply the new policy to the next connections evaluated]
restart[Restart required for listener-level settings]
stop[Stop — finish or drop in-flight connections and exit]
start --> accept --> evaluate --> verdict
verdict -->|Yes| forward
verdict -->|No| block
forward --> log
block --> log
log --> react
react -->|Most sections| reload --> accept
react -->|Low-level resources| restart --> start
react -->|No| accept
accept -->|Stop request| stop
```
### Live policy reload vs restart
Saving a change in the Web UI updates the running daemon's policy for most sections with no restart. The new policy applies to the next connections evaluated. A small minority of low-level settings need a restart because they affect resources the daemon opens only once at startup, such as listener sockets.
## Binary and service
* **Binary** — `/opt/safesquid/bin/safesquid`
* **Service user** — `ssquid` (group `root` on the appliance)
* **PID file** — `/var/run/safesquid/safesquid.pid`
* **Init script** — `/etc/init.d/safesquid`
* **systemd unit** — `/etc/systemd/system/safesquid.service`
## Command-line options
* **`-f`** — Run in the foreground (no double-fork). Use for debugging.
* **`-v`** — Print the build version and exit.
`-v` exits without starting the proxy at all, which makes it the quickest way to confirm exactly which build is installed before comparing two appliances or filing a support request.
Most tunables (listen address, thread limits, log levels) are set in `/opt/safesquid/startup.ini`, not on the command line.
**Foreground mode** runs the daemon attached to the invoking session. So its own startup output and any immediate errors are visible directly, instead of only a generic service-manager failure summary. Use it for first-time setup and low-level troubleshooting, not day-to-day operation. It applies to both the `-f` flag above and the `foreground` service verb below.
## Service control
```text theme={null}
/etc/init.d/safesquid start
/etc/init.d/safesquid stop
/etc/init.d/safesquid restart
/etc/init.d/safesquid status
/etc/init.d/safesquid foreground
```
## Important paths
* **Policy** — `/usr/local/safesquid/security/policies/config.xml`
* **Web UI** — `/usr/local/safesquid/ui_root/` — browse at `http://safesquid.cfg/`
* **Logs** — `/var/log/safesquid/` (native, extended, config, performance, …)
* **Cache** — `/var/cache/safesquid/`
* **Startup settings** — `/opt/safesquid/startup.ini`, `/opt/safesquid/setup.ini` — see [startup.ini tunables](/configuration/start_here/startup_ini) (not in sectionMaster)
Editing `/usr/local/safesquid/security/policies/config.xml` directly, outside the Web UI, is **unsupported** and risks putting the running daemon and the Web UI's view of policy out of sync.
## Subscription and updates
Background UPDATE hooks refresh application signatures, content signatures, categorisation feeds, and related databases. License state is managed under [Subscription](/configuration/infrastructure_and_access/subscription) in the Web UI; see [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds) for paths under `/var/lib/safesquid/`.
This refresh runs on its own schedule, with no restart and no interruption to active connections.
## Common problems
* **Service shows stopped but was not deliberately stopped** — check status, then start it. If it will not stay up, run Foreground so the real startup error surfaces rather than a generic failure.
* **A Web UI change appears to have no effect** — confirm it was actually saved, not just typed into a field. Most sections apply live; restarting to "fix" a section that should already apply live usually masks the real problem.
* **Need the exact installed build**. Use the version flag rather than inferring it from the Web UI, especially when comparing appliances or filing a support request.
* **Suspected conflicting or unexpected policy**. Check Config logs for the most recent changes and who made them before assuming the daemon is misbehaving. Most such reports are an unnoticed policy change.
## How to verify
1. Confirm status reports running with a valid PID file.
2. Send one test request and confirm it appears in **Reports → Detailed logs**.
3. After a change expected to need a restart, restart and re-test rather than assuming it applied live.
4. If startup itself is in doubt, stop the service and start in Foreground.
5. Confirm the build with the version flag after an upgrade.
## Next steps
* [First configuration](/configuration/start_here/first_configuration)
* [Architecture and request pipeline](/configuration/start_here/architecture)
* [Access restrictions](/configuration/application_setup/access_restrictions)
* [Subscription](/configuration/infrastructure_and_access/subscription)
* [Logging and troubleshooting](/configuration/start_here/logging)
# Debug response headers
Source: https://docs.safesquid.com/configuration/start_here/debug_response_headers
Turn on X-SafeSquid debug headers to see which profiles, categories, and filters applied to a request.
# Turn On Debug Response Headers
SafeSquid can attach diagnostic information to HTTP messages as `X-SafeSquid-*` and module-specific headers. Modules push entries onto the connection `dheader` list. When headers are sent, SafeSquid may insert a fixed identity block plus every marked `dheader` entry.
This is the supported way to see which profiles, categories, and filters applied to a request.
## Enable or disable
In **System configuration**, set **Send Debugging Headers To**:
* **Send Debugging Headers To (`dheaders`)** — System configuration, global field.
* **NONE** — Do not send debugging headers (production default).
* **CLIENT** — Add debugging headers on responses to the browser.
* **SERVER** — Add debugging headers on requests to the origin or upstream proxy.
* **BOTH** — Send to client and server.
Enable CLIENT or BOTH only on a test profile or management network. These headers can reveal usernames, groups, and policy decisions.
The headers reflect the state of the connection at the point they are attached. The identity, categorisation, and policy results already resolved earlier in the pipeline for this same request.
## Always included (when enabled)
* `X-Powered-By` — product name
* `X-SafeSquid-Client-ID` — `clientid.request` (match Detailed logs)
* `X-SafeSquid-User` — username
* `X-SafeSquid-User-Groups` — groups from Access restrictions
* `X-SafeSquid-Profiles` — Access Profiles tags
* `X-SafeSquid-Categories` / `X-SafeSquid-Ref-Categories`
* `X-SafeSquid-Request-Types`, `X-SafeSquid-Response-Types`
* `X-SafeSquid-Application-Signatures`
* `X-SafeSquid-Time-Profiles`
## Module and policy headers
Each module header appears only when that module actually ran and had something to report — which of them appear on a given request depends entirely on which filters the request passed through.
During processing, modules append named headers to `dheader`. Common examples:
* `X-SafeSquid-Instance`, `X-SafeSquid-Subscription`, `X-Registered-Domain`
* `X-SafeSquid-Access-Policy` — Access Profiles reason
* `X-SafeSquid-Template` — block or info template name
* `X-Cookie-Filter`, `X-Text-Analyzer`, `X-DNSBL-Filter`
* `X-Clam-AV`, `X-Virus-Scan`, `X-DLP-Check`, `X-Image-Filter`
* `X-Elevated-Privacy`, `X-URL-Cat`, `X-REF-Cat`
Use browser developer tools (Network → response headers) or a capture. Correlate `X-SafeSquid-Client-ID` with Detailed logs `client_id` / `request_id`.
## Bypass
To skip filters for a role, use the Access restrictions **Bypass** field. Keep **Allow bypassing** when you want temporary Access Profiles DENY bypass (cookie).
Debug headers only report — they never change policy on their own. Turning them on alongside a Bypass configuration is a good way to confirm the bypass is genuinely taking effect: the relevant module's header is simply absent from a request that was correctly skipped.
## Examples
### Diagnose an unexpected block without opening a report
* **Configuration:** Set **Send Debugging Headers To** to **CLIENT**, temporarily, on a test or management network only. Reproduce the blocked request from the affected client's own browser.
* **Result:** the browser's developer tools show the response headers, including `X-SafeSquid-Profiles`, `X-SafeSquid-Categories`, `X-SafeSquid-User-Groups`, and `X-SafeSquid-Template` — together these usually identify exactly which Access Profile and which category decided the block, without needing to search Detailed logs at all.
## How to verify
1. Set **Send Debugging Headers To** to **CLIENT** on a test profile or management network.
2. Reproduce the request in question and inspect the response headers in the browser's developer tools (or a packet capture).
3. Note `X-SafeSquid-Client-ID` and cross-check it against **Reports → Detailed logs** to confirm both views describe the same transaction.
4. Once diagnosis is complete, set **Send Debugging Headers To** back to **NONE** — leaving it enabled outside a controlled test exposes policy and identity information on every single response.
## Next steps
* [Logging and troubleshooting](/configuration/start_here/logging)
* [Architecture](/configuration/start_here/architecture)
* [Access restrictions](/configuration/application_setup/access_restrictions)
* [System configuration](/configuration/application_setup/system_configuration)
# First configuration
Source: https://docs.safesquid.com/configuration/start_here/first_configuration
Set up a safe minimal SafeSquid configuration: confirm the service, restrict clients, test the proxy, add a content rule, and find the logs.
# Complete Your First Configuration Safely
This page is for a new administrator who has a working SafeSquid appliance and needs a safe, minimal setup: browsers can use the proxy, only intended clients are allowed. You can see why a request was allowed or blocked.
Open the Web UI at `http://safesquid.cfg/` from a machine that can reach the appliance. Policy lives in the Web UI; process tunables live in [startup.ini](/configuration/start_here/startup_ini).
## What you will set up
1. Confirm the service is running
2. Confirm how clients reach SafeSquid (listen address)
3. Lock down who may use the proxy (Access restrictions)
4. Point a browser at the proxy and test
5. Add a simple content rule (Access Profiles)
6. Learn where to look when something fails (logs)
## 1. Confirm the service
On the appliance:
```text theme={null}
/etc/init.d/safesquid status
```
If it is not running: `/etc/init.d/safesquid start`. Details: [Daemon, service, and files](/configuration/start_here/daemon).
If it fails to start, run it in the foreground instead of as a background service for this first attempt — foreground mode prints startup errors directly to the console instead of only to log files, the fastest way to spot a listen address already in use or a permissions problem on a box being set up for the first time.
## 2. Confirm listen address
In the Web UI open **Network settings → Listen**.
* You should see at least one enabled listener (IP and port), often port **8080**.
* If Listen is empty, SafeSquid falls back to `LISTEN_IP` / `LISTEN_PORT` in [startup.ini](/configuration/start_here/startup_ini).
- Each enabled Listen entry binds when the service starts. Adding or changing a Listen entry only takes effect after a service restart, not on a configuration save.
### Example — dual listeners
* **0.0.0.0:8080** — proxy traffic from the LAN
* **10.0.0.5:80** — Web UI only on a management address (optional)
Later you can restrict Web UI access in Access restrictions using the **Interface** field so only the management listener may open `http://safesquid.cfg/`.
More detail: [Network settings](/configuration/application_setup/network_settings_and_listeners).
## 3. Lock down Access restrictions
A freshly installed appliance with a reachable listen socket and no Access restrictions configured yet will, depending on **Default Access Policy**, either deny everyone or — if that policy is set to Allow before any restrictions exist — let anyone who can reach the socket use the proxy. Treat this step as the real priority, even though the walkthrough covers the service check first, for the practical reason that you cannot configure a Web UI that is not running.
Open **Access restrictions**. This is the security perimeter: who may connect and what they may do.
1. Set **Default Access Policy** to **Deny** (recommended).
2. Leave **Kerberos / SSO** off for this first pass (add it later; see [Authentication](/configuration/start_here/authentication)).
3. Add one **Allow list** entry for your office or lab network.
### Example — allow the LAN to use the proxy
On the Allow list entry:
* **Enabled** — on
* **Comment** — `LAN proxy users`
* **IP Address** — `10.0.0.0-10.255.255.255` (use your real range; SafeSquid does not use CIDR like `10.0.0.0/8`)
* **Access** — enable at least proxy / HTTP rights your deployment needs (Web interface only if this entry should also reach the UI)
* Leave Profiles, LDAP, username blank so the rule matches by IP only
**Expected result:** a PC in `10.0.0.0`–`10.255.255.255` can use the proxy; a client outside that range is denied.
Blank match fields mean “match any.” An Allow entry with nothing filled in can open the proxy to everyone. Always set IP, Interface, or identity criteria.
Full guide: [Access restrictions](/configuration/application_setup/access_restrictions).
## 4. Point a browser and test
1. On a PC inside the allowed range, set the HTTP/HTTPS proxy to the appliance IP and listen port (for example `10.0.0.5:8080`).
2. Browse to a simple HTTP site (or HTTPS if your clients already trust the appliance for inspection — skip HTTPS Inspection for day one if unsure).
3. Open **Reports → Detailed logs**. You should see your request with username (or anonymous), URL, and status.
### Example — quick deny check
Temporarily change the Allow entry IP to a range that does *not* include your PC, save, and reload a page. The browser should fail to use the proxy. Restore the correct range afterward.
This confirms Access restrictions is being *enforced*, not merely present, and catches the most common first-configuration mistake. An Allow entry that looks right but was saved against the wrong subnet.
## 5. Add a simple Access Profiles rule
**Access restrictions** decides who may use SafeSquid. **Access Profiles** decides what those users may fetch (categories, sites, profiles).
1. Open **Access Profiles → Default Policies** (or Secondary Policies).
2. Add a DENY rule for a category you can test safely (or a specific host if categories are not ready yet).
### Example — block one test site for everyone
* **Enabled** — on
* **Comment** — `Block example test host`
* Match the host or category your lab uses
* **Action** — **DENY** (use **DO NOT BYPASS** if you do not want a temporary bypass cookie)
**Expected result:** matching requests show a block page; Detailed logs show a profiles-related `filter_name` / reason. See [Access Profiles](/configuration/restriction_policies/access_profiles).
## 6. When something fails
1. Note the time, client IP, and URL.
2. Search **Reports → Detailed logs** for `filter_name` and `filtering_reason`.
3. On a test network only, set **System configuration → Send Debugging Headers To → CLIENT** and inspect response headers in the browser. See [Debug response headers](/configuration/start_here/debug_response_headers).
4. Turn debugging headers back to **NONE** when finished.
Full workflow: [Logging and troubleshooting](/configuration/start_here/logging).
## How to verify
1. Confirm the service reports running before doing anything else. A Web UI you cannot reach means every later step is moot.
2. Confirm the Listen entry you expect is enabled. That the service was restarted after any change — Listen entries only bind at service start.
3. Read the Allow list top to bottom before trusting it: first-match-wins means a broad entry above your intended one silently claims its connections, with no warning anywhere in the Web UI.
4. Generate one allowed and one denied request, and confirm both appear in Detailed logs with the outcome you expect.
5. Confirm Detailed logs attribute the Access Profiles block to Access Profiles rather than Access restrictions. The two sections produce different filter reasons, and confusing one for the other is a common early debugging mistake.
## What to do next
* [Authentication](/configuration/start_here/authentication) — Kerberos / SSO or System authentication so logs show real usernames
* [Integrate LDAP](/configuration/application_setup/integrate_ldap) — groups for policy
* [HTTPS Inspection](/configuration/real_time_content_security/https_inspection) — decrypt HTTPS when your policy requires it (plan client trust carefully)
* [SSqore](/configuration/application_setup/ssqore) and [Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites) — category-based Access Profiles
* [Application Signatures](/configuration/custom_settings/application_signatures) — tag client applications for policy
* [SqScan](/configuration/real_time_content_security/sqscan) or [Clam antivirus](/configuration/real_time_content_security/clam_antivirus) — malware scanning
* [Subscription](/configuration/infrastructure_and_access/subscription) — license and feed updates
* [Architecture](/configuration/start_here/architecture) — how sections fit together
## Next steps
* [Full documentation index](/configuration/main)
* [Daemon, service, and files](/configuration/start_here/daemon)
# Integrations
Source: https://docs.safesquid.com/configuration/start_here/integrations
Map every external system SafeSquid integrates with, where each is configured, and what breaks when one is missing or misconfigured.
# Map SafeSquid Integrations With External Systems
SafeSquid works with external systems and bundled services. Configure most integrations in the Web UI; some host paths and daemons are appliance packages.
SafeSquid rarely operates alone; this page maps every external system it integrates with, where each is configured, and what breaks when one is missing or misconfigured. It deliberately does not repeat each integration's own topic.
## Directory and identity
* [Integrate LDAP](/configuration/application_setup/integrate_ldap) / Active Directory — users, groups, LDAP Profiles on Access rows. Disabled means the cache is cleared and any Access entry relying on LDAP Profiles or LDAP-backed System authentication stops matching until re-enabled and re-synced. Get the **Group Identifier** attribute name wrong and **LDAP Profiles matching silently never fires, with no error anywhere**.
* [Kerberos / SSO](/configuration/start_here/authentication) — keytab at `/usr/local/safesquid/security/HTTP.keytab`. Depends on a valid keytab present and readable **at process start**. If it is missing or invalid when the service starts, Negotiate is never offered to browsers even though the Web UI switch shows it enabled. Installing or replacing the keytab needs a service restart.
* PAM stack `/etc/pam.d/safesquid` for System authentication. Credentials are validated in order: a short-lived password cache, then the appliance's own OS authentication stack, then an LDAP bind if Integrate LDAP is configured and the user is already known. Local OS accounts and directory accounts therefore share one authentication path on the same Access entry.
* IP-to-user map: `USER_IP_DB_FILE` in [startup.ini](/configuration/start_here/startup_ini) (for example VPN clients).
## Scanning and adaptation
* [Clam antivirus](/configuration/real_time_content_security/clam_antivirus) — local `clamd` socket. SafeSquid does not manage virus signatures; keeping the `clamd` signature database current belongs to whatever manages that installation. An unreachable scan target **fails scanning for that connection rather than silently skipping it** — verify that matches your policy's expectation.
* [SqScan](/configuration/real_time_content_security/sqscan) — built-in in-memory scanner. No external daemon and nothing to reach over the network. Choose it when you want scanning with no external dependency, and ClamAV or ICAP when you need a separately maintained, swappable engine.
* [ICAP](/configuration/real_time_content_security/icap) — third-party REQMOD/RESPMOD services. REQMOD for uploads, RESPMOD for downloads. A server error or timeout **falls through to the next matching ICAP entry**, if any.
* [DLP](/configuration/real_time_content_security/dlp) — upload inspection and OCR scoring.
* [Image analyzer](/configuration/real_time_content_security/image_analyzer) — optional image scoring module.
## Categorisation and feeds
* [SSqore](/configuration/application_setup/ssqore) — cloud URL categorisation (CCS). Needs reachability and a valid subscription. When it cannot reach the service, or the subscription is invalid, requests to previously-uncategorised hosts may pass through with **no category at all** — which matters if your policy denies by category, since an uncategorised host is not automatically denied unless you wrote policy that treats "no category" as denied.
* [Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites) — local category overrides. A purely local override list that **takes precedence over** whatever cloud categorisation returns for the same host, and needs no external connectivity.
* [Application Signatures](/configuration/custom_settings/application_signatures) / [Content Signatures](/configuration/custom_settings/content_signatures) — vendor signature databases.
* [Subscription](/configuration/infrastructure_and_access/subscription) — license and activation. Gates whether the scheduled update cycle can refresh feeds **and** whether per-request Application Signatures processing runs at all. An expired subscription is not an Access denial: existing traffic keeps flowing. But signature-dependent labelling stops being applied to new connections and feed refresh stops.
* See [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds) for UPDATE schedule and offline behaviour.
## Network services
* [WCCP](/configuration/application_setup/wccp) — transparent redirection to the proxy. Confirm WCCP redirection works on your build before planning a deployment around it. That topic records the caveat in full.
* [Proxy chain](/configuration/application_setup/proxy_chain) — upstream peers and CARP. A parent proxy, sibling caches, or a CARP cluster of peer SafeSquid instances sharing load by URL hash. Use it when SafeSquid must sit behind another proxy layer, or to distribute requests deterministically across multiple instances.
* BIND / DNS stubs under the security DNS directory (appliance). Coordinate any change with whoever manages DNS. Getting either the DNS categorisation zone or the appliance's own DNS resolution setup wrong affects ordinary browsing and categorisation accuracy at once. The symptoms look identical from inside SafeSquid.
* rbldnsd-style DNS blacklists used with [DNS Blacklist](/configuration/real_time_content_security/dns_blacklist). SafeSquid appends the configured suffix to the request's host name and treats specific returned addresses as a block signal. If you run your own zone, that zone server is the external dependency. **A zone that fails open — returning nothing rather than a clear miss — silently stops blocking anything.** Verify both a known-bad and a known-good host name.
* DNS categorisation zone: `DNS_CAT_ZONE` in startup.ini.
## Operations
* Monit: `/etc/monit/conf.d/safesquid.monit` — a supervisor that is itself not running gives no safety net at all. Confirm periodically, **from outside the Web UI**, that it is active and pointed at the SafeSquid service.
* systemd / init: see [Daemon](/configuration/start_here/daemon)
* logrotate: `/etc/logrotate.d/safesquid`
* Master sync: `MASTER_IP`, `NEVER_SYNC`, `ALWAYS_SYNC` in startup.ini
## Examples
### Diagnosing feeds stopped updating
Check licence state first: an expired subscription is the most common cause and also explains why signature processing stopped on live connections, not merely why the download stopped. If the subscription is valid, confirm outbound connectivity to the vendor update service before assuming a Web UI misconfiguration.
## How to verify
1. For any directory integration, confirm entries actually appear under **Reports → LDAP Entries** after enabling. An empty list after a full sync cycle means the connection, credentials, or base DN are wrong, not that there are no users.
2. For any scanning integration, send a known test payload through a profile that should be scanned, and confirm both a block page and a matching filter name in **Reports → Detailed logs**.
3. For subscription-gated feeds, check load timestamps rather than assuming a key upload refreshed anything — refresh happens on the next scheduled cycle.
4. For any network-level redirection, confirm with the network team that traffic is actually arriving at SafeSquid before troubleshooting inside the Web UI.
5. For host-level supervision, confirm outside the Web UI that the supervising process is running.
## Next steps
* [Architecture](/configuration/start_here/architecture)
* [Logging and troubleshooting](/configuration/start_here/logging)
* [Full section index](/configuration/main)
# Logging and troubleshooting
Source: https://docs.safesquid.com/configuration/start_here/logging
Find which SafeSquid log proves what happened when a user reports a blocked site or a page that will not load.
# 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?
| 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](/configuration/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.
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](/configuration/application_setup/network_settings_and_listeners).
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](/configuration/application_setup/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](/configuration/restriction_policies/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](/configuration/start_here/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](/configuration/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.
## 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
* [First configuration](/configuration/start_here/first_configuration)
* [Access restrictions](/configuration/application_setup/access_restrictions)
* [Authentication](/configuration/start_here/authentication)
* [Access Profiles](/configuration/restriction_policies/access_profiles)
* [Architecture](/configuration/start_here/architecture)
* [Debug response headers](/configuration/start_here/debug_response_headers)
# startup.ini tunables
Source: https://docs.safesquid.com/configuration/start_here/startup_ini
Tune process-level settings in startup.ini, such as listen identity, threads, memory, logging, and master sync, read once at start.
# Adjust startup.ini Tunables for the Process
Many appliance behaviours are set in `/opt/safesquid/startup.ini` (defaults in `/opt/safesquid/default/startup.ini`). These values are loaded before SafeSquid starts. They are **not** edited in Web UI sections from `sectionMaster.xml`.
After edits, restart SafeSquid (`/etc/init.d/safesquid restart`). Path layout comes from `/opt/safesquid/setup.ini`.
**Two layers:** Web UI / `sectionMaster` = policy XML. `startup.ini` = process and host tunables (listen, threads, logs, TLS, sync, DNS categorisation zone, and similar). Every value here is read once, at process start — there is no partial-reload path. A config sync from a master, or a Web UI policy save, does not touch or re-read this file. An unrecognised key is silently ignored rather than rejected — consult the shipped default file if unsure a key is spelled correctly.
## Listen and identity
* **LISTEN\_IP / LISTEN\_PORT** — Default bind address and port if no Network settings Listen entry is enabled. See [Network settings](/configuration/application_setup/network_settings_and_listeners). Once you add and enable a real Listen entry that entry is used and this fallback becomes irrelevant — but it is never actively disabled. So if every Listen entry is later disabled or removed, the appliance silently falls back to these defaults again rather than refusing to bind at all.
* **HOSTNAME / DOMAIN** — Appliance hostname and domain.
## Threads, memory, sockets
* `MAXTHREADS`, `MAX_FDS` (about 4× threads — sized at that ratio because each connection can hold more than one descriptor at once, such as a client socket, an origin socket, and a cache file), `STACKSIZE`, `OVERLOAD_FACTOR`
* `SOCKET_TIMEOUT`, `THREAD_TIMEOUT`
* **`MAX_CONCURRENT`** — a global concurrent-connection ceiling for the whole process, distinct from the per-user, per-client-IP ceiling set by **MAX Concurrent Connections** on an individual Access restrictions entry.
* `HEAP_MEM`, `SOCK_MEM` — lower if the host is memory-starved
* `SEND_SOCKET_BUFFERS`, `RECEIVE_SOCKET_BUFFERS` — `0` = no artificial limit
* `TCP_KEEPIDLE_TIME`, `TCP_KEEPINTVL_TIME`, `TCP_KEEPCNT_COUNTS`
* **`CLIENT_DEFER_ACCEPT`** — defers accepting a client connection until data has actually arrived, reducing wasted thread time on connections that open and immediately go idle.
## CPU placement
* **LISTEN\_CPUS** — Cores reserved for accepting clients (default `0,1`)
* **CPU\_RESERVATION** — Reservation strategy (default `1`)
## Authentication cache
`PASSWORD_CACHE_SIZE` and `PASSWORD_CACHE_EXPIRE_TIME` — see [Authentication](/configuration/start_here/authentication).
## Logging
`LOG_LEVEL`, `LOG_SIZE_LIMIT`, `PROCESS_OLD_LOGS`, `DATE_TIME_FORMAT`, and optional `NATIVE_UDP_*` / `EXTENDED_UDP_*` / `CONFIG_UDP_*` — see [Logging](/configuration/start_here/logging).
## Master sync
* **MASTER\_IP / MASTER\_PORT** — Master appliance for configuration sync
* **NEVER\_SYNC / ALWAYS\_SYNC** — Comma-separated section names that must never / always sync (default `NEVER_SYNC=cache`)
* **SYNCTIME** — Sync interval toward the master
## Updates and HTTPS
* `UPDATE_INTVL`, `UPDATE_RETRY_DELAY`
* `FORCE_SNI` — use SNI for client certs in HTTPS Inspection
* `USE_SESSION_TICKETS`
* `CLIENT_CIPHERS_LIST` / `SERVER_CIPHERS_LIST` (TLS ≤ 1.2)
* `CLIENT_CIPHERS_SUITE` / `SERVER_CIPHERS_SUITE` (TLS 1.3)
## Categorisation and identity side channels
* **DNS\_CAT\_ZONE** — DNS categorisation zone (default `.c.ssquid.in`). Set to `.` to disable.
* **USER\_IP\_DB\_FILE** — SQLite map of IP → username (for example VPN clients)
* **OPENVPN\_CLIENT\_HEAD** — OpenVPN client head file path when that integration is used
* **IPV6\_DETECT\_SITE** — FQDN:PORT used to test IPv6 reachability
## Reporting database
`REAL_TIME_DB_WRITE`, `STATEMENT_COUNT`, `MAX_MAIL_THRESHOLD`, `MIN_MAIL_THRESHOLD`, `KEEP_DATA`.
## Debugging
`MALLOC_CHECKING` — glibc `MALLOC_CHECK_` mode (see comments in the default file).
## Examples
### Fitting resource limits to a smaller host
On a lower-memory appliance, lower `HEAP_MEM` and `SOCK_MEM` alongside `MAXTHREADS` and `MAX_FDS` (keeping `MAX_FDS` at roughly four times `MAXTHREADS`), restart, then watch Dashboard and Statistics under load to confirm the appliance stays responsive.
### Disabling DNS categorisation temporarily
If the DNS categorisation zone is unreachable and producing errors rather than degrading gracefully, set `DNS_CAT_ZONE=.` and restart to disable that path while resolving the underlying DNS issue. Other categorisation sources such as SSqore and local category overrides continue to function.
## How to verify
1. After any edit, restart the service, then confirm the appliance is actually running the new configuration. A misspelled tunable is silently ignored, which looks identical from the outside to the tunable simply not mattering.
2. For listen-related changes, confirm with a direct connection test rather than trusting the Web UI Network settings page alone. That page shows configured Listen entries, not the process's actual fallback behavior when none are enabled.
3. For master sync changes, confirm on the replica that a policy change made on the master actually arrives within the configured sync interval. That any section in `NEVER_SYNC` genuinely does not change.
4. Revert any temporary diagnostic change and restart again once the investigation is complete.
## Next steps
* [Daemon and service](/configuration/start_here/daemon)
* [Logging](/configuration/start_here/logging)
* [Authentication](/configuration/start_here/authentication)
* [HTTPS Inspection](/configuration/real_time_content_security/https_inspection)
* [Cloud / categorisation feeds](/configuration/start_here/cloud_feeds)
* [Subscription](/configuration/infrastructure_and_access/subscription)
# Tools and Reports
Source: https://docs.safesquid.com/configuration/start_here/tools_and_reports
Use the Reports and Support utilities to confirm the proxy is healthy, audit configuration changes, and troubleshoot user issues.
# Use Tools and Reports to Check Proxy Health
The Web UI includes Reports and Support utilities that are not policy sections. Use them to confirm the proxy is healthy, audit configuration changes, and troubleshoot user issues.
## Reports
* **Dashboard and Statistics** — traffic overview and module counters (DLP blocks, scan totals, and similar).
* **Native logs, Detailed logs, Config logs** — see [Logging and troubleshooting](/configuration/start_here/logging).
* **Active Connections, Connection Pool** — live appliance state. Useful for diagnosing a specific client's session in real time, or when suspecting connection exhaustion under heavy load.
* **DNS Cache** — live appliance state. Check here before assuming a stale DNS answer is a resolver problem outside SafeSquid. The appliance's own cache may be the one serving it.
* **Password Cache** — live appliance state. Clear it when troubleshooting a credential change that doesn't seem to take effect. A cached failure or cached stale success can otherwise mask the real state for the remainder of the cache's expiry window.
* **SSL Certs/Cache** — live appliance state. Relevant when a client reports certificate errors that persist even after you believe the underlying HTTPS Inspection configuration is fixed.
* **LDAP Entries** — directory browse after [Integrate LDAP](/configuration/application_setup/integrate_ldap) is configured. Use it to confirm a directory sync actually populated the expected users and groups before writing Access restrictions or Access Profiles rules that depend on them.
License and signature/feed status are not under Reports — that's the separate **Support**
top-nav page, next to Configure. See [Support](/configuration/infrastructure_and_access/support)
for its License Details panel and ten appliance-operation cards (support tarball, config
backup/restore, upgrade, restart, diagnostics, live chat).
## Other utilities
* **password** — confirmed live as the `xx--password` mode of **Support → URL Commands** (the same "URL command executor" dialog used for Test the Functionalities), not a separate card. Whether individual password fields (for example HTTPS Inspection's cached cert password) also carry their own dedicated button that opens this same tool pre-filled was not exercised — confirmed only that the mode itself exists and is reachable this way.
* **Upload templates** — not a standalone tool. Each entry under [Custom Settings → Templates](/configuration/custom_settings/templates) carries its own **File** field (for example `blocked.html`). Uploading a custom block/info template is done per-entry there, via that field's own upload control, not through a separate global "Upload templates" utility. Any policy section's Template field (Access Profiles DENY actions, ClamAV, DNS Blacklist, and others) can then reference the uploaded template by name.
* **[Subscription](/configuration/infrastructure_and_access/subscription)** — activation key upload and license view (on-appliance side; distinct from the Support page's License Details).
* **[Categorize Web-Sites](/configuration/custom_settings/categorize_web_sites)** — local category overrides (Web UI app, not a policy section list).
## CLI and files
* Init script: `/etc/init.d/safesquid {start|stop|restart|status|foreground|space_clean}` — see [Daemon](/configuration/start_here/daemon).
* Policy file: `/usr/local/safesquid/security/policies/config.xml`; process tunables: `/opt/safesquid/startup.ini`.
## Examples
### Confirm signature feeds after renewal
1. Upload activation key under Subscription.
2. Open Support — the License Details panel's **Last Updated Time** should advance after the next UPDATE cycle.
3. Reproduce a request; Detailed logs should show `application_signatures` when subscription is valid.
### Recover a forgotten encrypted cache-certificate password
Open the **password** utility, enter the plaintext, and paste the resulting encrypted value directly into the target policy field — do not hand-construct an encrypted value or reuse one copied from a different password.
## How to verify
1. When troubleshooting with Reports, start with Detailed logs for a single-request question and only move to Native logs, with the matching log family enabled, once you know which module is involved.
2. Treat Active Connections and Connection Pool as point-in-time snapshots — refresh and re-check rather than diagnosing a live capacity issue from one stale view.
## Next steps
* [Support](/configuration/infrastructure_and_access/support)
* [Logging and troubleshooting](/configuration/start_here/logging)
* [First configuration](/configuration/start_here/first_configuration)
* [Daemon and service](/configuration/start_here/daemon)
* [Full documentation index](/configuration/main)
# Choose an Architecture
Source: https://docs.safesquid.com/deployment/choose_an_architecture
Decide where SafeSquid intercepts traffic — forward, transparent, TCP, reverse, or chained — and what each choice costs you in client configuration, coverage, and bypass risk.
# Decide Where Traffic Is Intercepted
The interception point determines what SafeSquid can enforce. Choose it before sizing, before firewall changes, and before any client is touched. The choice drives client configuration effort, coverage gaps, and how easily a user can route around the control.
SafeSquid cannot enforce policy on traffic that bypasses the proxy. Every mode below is a different answer to how you stop that from happening.
Work through the decision in this order: direction of traffic, then whether the client can be configured. Then consider protocol and upstream constraints. Confirm the result against the table below.
```mermaid theme={null}
flowchart TB
Start[Traffic needs interception] --> Direction{Inbound or outbound}
Direction -->|Outbound - egress control| ClientConfig{Client is configurable}
Direction -->|Inbound to an internal server| Reverse[Reverse proxy]
ClientConfig -->|Yes| Protocol{Protocol is HTTP or HTTPS}
ClientConfig -->|No - device cannot be configured| Transparent[Transparent proxy]
Protocol -->|Yes| Upstream{An upstream proxy already exists}
Protocol -->|No - non-HTTP protocol| TCP[TCP proxy]
Upstream -->|Yes| Chain[Proxy chain]
Upstream -->|No| Forward[Forward proxy]
```
## Match the mode to the constraint
| Mode | Traffic reaches SafeSquid because | Costs you | Bypass risk |
| - | - | - | - |
| Forward proxy | The client is configured to send it | Client rollout on every endpoint | User can remove the proxy setting |
| Transparent proxy | The network redirects it | Router, switch, or firewall change | Low for managed paths; none for the user to undo |
| TCP proxy | The client targets a proxied TCP port | Per-protocol configuration | Depends on the routing in front of it |
| Reverse proxy | External clients resolve to SafeSquid | Public DNS and certificate ownership | Not applicable — inbound, not outbound |
| Proxy chain | An upstream proxy forwards it | Coordination with the upstream owner | Inherited from the upstream tier |
Start with forward proxy for a pilot even when transparent is the production target. Explicit configuration makes it obvious which client is being tested and easy to roll back.
## Understand what each mode enforces
Each mode trades control, coverage, and rollback differently. Open the one that matches the row you picked above.
Requires explicit client configuration through browser settings, a [PAC file](/getting_started/client_configuration/pac_file), or system-level proxy settings. It gives the most granular control over which clients are proxied, and the clearest rollback — remove the setting. It also means an endpoint that misses the rollout is silently unprotected.
Intercepts traffic through network-level redirection, with no client configuration. Coverage is comprehensive for everything on the redirected path, including devices you cannot configure. The cost moves to the network team. A routing change made without coordination can take the control offline for everyone at once.
[TCP proxy](/use_cases/scaling_and_high_availability/tcp_proxy) operates at the TCP layer for non-HTTP protocols that still need inspection and control. Use it where an application will not honour an HTTP proxy but its traffic must still be governed.
[Reverse proxy](/use_cases/scaling_and_high_availability/reverse_proxy) protects internal web servers from direct internet access, terminating TLS and applying authentication in front of them. This is the inbound case — it does not replace an outbound egress control.
[Proxy chain](/use_cases/scaling_and_high_availability/proxy_chain) places SafeSquid in a multi-tier architecture, forwarding to or receiving from another proxy. Use it where an existing upstream proxy cannot be removed. Confirm which tier owns policy before splitting enforcement across both.
## Design the network placement
Once the mode is chosen, document where it sits:
* Explicit proxy for pilot clients and controlled validation.
* PAC file or managed OS proxy for browser rollout.
* Firewall or routing policy only when the network team can enforce bypass controls safely.
* Cloud egress placement for workloads or remote sites that already route through a cloud network.
Record source networks, proxy listener ports, DNS servers, NTP sources, upstream gateways, and firewall rules. Name an owner for every routing or firewall policy that forwards traffic toward SafeSquid. An unowned redirect is the one nobody restores after an outage.
## Capture the architecture decision
Store these artifacts with the deployment record:
* The chosen mode and the constraint that drove it.
* A network placement diagram showing the interception point.
* Source networks and listener ports, with the firewall change record.
* The named owner of any routing, [WCCP](/use_cases/scaling_and_high_availability/wccp), or redirect policy.
* The rollback path for the interception change, and its owner.
## Troubleshoot architecture choices
| Symptom | Likely cause | Fix |
| - | - | - |
| Some clients are never logged | Forward proxy rollout missed those endpoints | Reconcile the endpoint inventory against access-log sources before widening policy |
| Traffic bypasses the proxy after a network change | Redirect policy was modified without coordination | Name an owner for the redirect and add it to the network change process |
| An application breaks under inspection | Protocol will not honour an HTTP proxy, or pins its certificate | Move it to TCP proxy, or add a documented exclusion with a business owner |
| Policy applies twice, or not at all | Two tiers in a proxy chain both claim enforcement | Assign policy ownership to one tier and make the other pass through |
| Internal servers are exposed | Reverse proxy was assumed to cover outbound egress | Deploy a separate outbound mode; reverse proxy is inbound only |
## Next steps
* [Forward Proxy](/use_cases/scaling_and_high_availability/forward_proxy) - configure the explicit path used for most pilots.
* [Transparent Proxy](/use_cases/scaling_and_high_availability/transparent_proxy) - intercept without touching clients.
* [Hardware Sizing](/deployment/hardware_sizing) - size the node once placement is decided.
# Cloud Image or Cloud-Init
Source: https://docs.safesquid.com/deployment/cloud_image_or_cloud_init
Choose between the prebuilt SafeSquid cloud image and a cloud-init build, and provision either one without embedding secrets in instance metadata.
# Choose the Provisioning Path
Two provisioning paths reach the same running instance. The prebuilt image is faster and carries a known baseline; cloud-init is repeatable and fits an existing automation pipeline. The wrong choice is not slow — it is unowned, producing instances nobody can rebuild identically.
Both paths share one rule: no secret goes into instance metadata.
## Compare the two paths
| | Prebuilt cloud image | cloud-init build |
| - | - | - |
| Speed to first boot | Fastest | Slower, builds on launch |
| Baseline | Fixed by the published image | Defined by your configuration |
| Fits existing automation | Requires an image import step | Yes, native user data |
| Rebuild reproducibility | Depends on the image being retained | Reproducible from the configuration file |
| Main risk | Image source and update path unapproved | A silent cloud-init failure leaves a reachable instance with no proxy |
Use the prebuilt image only when the image source, release, checksum or publisher identity, and update path are approved.
## Provision the instance
The two paths diverge from here — prebuilt image for the fastest known-good baseline, cloud-init for a reproducible, automation-driven build. Follow whichever one the comparison above pointed to.
The prebuilt image is published at:
```text theme={null}
http://downloads.safesquid.com/appliance/cloud-img/safesquid-swg.img
```
Import it through the provider's custom-image path, then launch an instance from the imported image:
| Provider | Import path |
| - | - |
| AWS | Import as an AMI using VM Import/Export |
| Azure | Upload as a managed disk, then create an image from it |
| GCP | Create a custom image from the disk |
| DigitalOcean | Use the Custom Images feature |
The image ships with the account `administrator` and the password `safesquid`. Change it with `passwd` at first login, before the instance is reachable from any client network. A default credential on a reachable proxy is an immediate exposure, not a setup detail.
Record the image ID, region, launch date, SafeSquid version, disk mapping, and initial security group rules.
Retrieve the published cloud-init configuration:
```bash theme={null}
curl -O https://raw.githubusercontent.com/SafeSquid-Github/safesquid_cloud-init/main/safesquid_cloud-init.yaml
```
Review and adjust the network settings, hostname, and disk layout before use, then pass it as user data at launch:
| Provider | User-data field |
| - | - |
| AWS | User data, during EC2 launch |
| Azure | Custom data, during VM creation |
| GCP | Metadata, key `user-data` |
| DigitalOcean | User data section |
Keep cloud-init focused on baseline OS configuration, package source selection, network settings, log-forwarder bootstrap, and management hardening.
Do not embed activation keys, administrator passwords, or certificate private keys in cloud-init text. Instance metadata is readable from inside the instance and is frequently captured in provider logs and snapshots. Upload the `activation_key` through the approved activation workflow after the instance is reachable.
Follow provisioning from the instance:
```bash theme={null}
tail -f /var/log/cloud-init-output.log
```
Expected result: the log reaches completion without error.
A cloud-init failure often leaves a reachable instance running no proxy at all. So check this before assuming the launch succeeded. An instance that answers SSH is not an instance that is proxying.
## Verify after first boot
Whichever path was used, confirm before routing clients:
* Service and listener state — see [Service Health](/deployment/service_health).
* DNS resolution from the instance.
* Activation endpoint reachability — see [Ports and Firewall Rules](/deployment/ports_and_firewall_rules).
* Access-log creation under `/var/log/safesquid/extended/`.
* The default administrator password has been changed.
## Capture provisioning evidence
Store these artifacts with the deployment record:
* Image ID and region, or the cloud-init file and its version.
* SafeSquid version at first boot.
* Disk mapping and initial security group rules.
* Confirmation that the default password was changed, and by whom.
* `cloud-init-output.log` completion, where cloud-init was used.
## Troubleshoot provisioning
| Symptom | Likely cause | Fix |
| - | - | - |
| Instance is reachable but nothing proxies | cloud-init failed partway | Read `/var/log/cloud-init-output.log` from the start, not the tail |
| Image import fails | Provider-specific format requirement | Check the provider's import constraints; AWS and Azure differ in disk format and size limits |
| Activation fails on a fresh instance | Egress to the activation endpoints is blocked by the security group | Allow outbound `443` to `key.safesquid.com` and `api.safesquid.net` |
| Instance is compromised soon after launch | Default credential left in place on a reachable host | Rebuild, then change the password before exposing the instance |
| Rebuilt instance behaves differently | Image was replaced upstream, or cloud-init file drifted | Pin the image ID or the configuration file version in the deployment record |
## Next steps
* [Cloud Deployment](/getting_started/install_safesquid/cloud_deployment) - secure the surrounding cloud network.
* [Activate Your License](/getting_started/activate) - apply the key once the instance is reachable.
* [Service Health](/deployment/service_health) - confirm the instance is actually serving.
# Hardware Sizing
Source: https://docs.safesquid.com/deployment/hardware_sizing
Decide what to measure, then convert peak concurrent connections into CPU, RAM, NIC, and storage decisions for a SafeSquid node, including the AES-NI requirement and NVMe write path.
# Size Against Peak, Not Average
Averages hide the burst that drops sessions. A node sized for the mean sails through the working day. It fails between 09:00 and 11:00, when every browser tab, background application, and API client opens connections at once. Sizing from a user count alone produces a node that passes a demo and drops sessions at 09:30.
The inputs that actually drive capacity — peak concurrency, inspection scope, and log volume — are measurable. A short pilot measures them far more cheaply than a production rollback does.
## Measure before you size
Record these inputs before choosing an installation path:
* User count and expected concurrent users.
* Peak web throughput and business-hour traffic patterns.
* Expected HTTPS inspection scope.
* Authentication source and group-policy requirements.
* Log retention target and SIEM or reporting destination.
* Availability target for internet egress.
* Rollback method for client proxy settings and routing.
Use the first deployment as a measured pilot, not a blind production cutover.
| Deployment scale | Recommended planning focus |
| - | - |
| Pilot or branch | Prove traffic flow, activation, logs, and certificate trust with limited users |
| Single production node | Size CPU, RAM, disk I/O, NIC capacity, and log retention for peak sessions |
| High availability | Plan shared routing, health checks, same activation key, and synchronized configuration |
| Disaster recovery | Preserve activation key, configuration backup, certificate material, and rebuild procedure |
Size conservatively when HTTPS inspection, [malware scanning](/use_cases/malware_scanning/malware_scanners), [DLP](/use_cases/data_leakage_prevention/data_leakage_prevention), or detailed logging is enabled. These controls add security value, but they also increase CPU, memory, and disk-write demand. A node sized for plain forwarding will not carry the same user count once inspection is on.
Include these values in the sizing worksheet:
* Concurrent users and concurrent connections during peak hours.
* Expected inspected HTTPS percentage.
* Malware scanning and DLP scope.
* Average and peak bandwidth.
* Cache usage expectations.
* Log volume, reporting retention, and SIEM forwarding rate.
* Support-bundle and packet-capture storage needed during incidents.
## Validate prerequisites
Confirm:
* Peak concurrent connections are measured or estimated, not assumed.
* The HTTPS inspection scope is known — it changes CPU demand substantially.
* The log retention target is agreed. Use [Log-Retention Planning](/deployment/log_retention_planning).
* The candidate CPU supports AES-NI.
## Read the sizing matrix
Size against **peak** concurrent connections, not average.
| CPU | RAM | NICs (minimum) | Max concurrent connections |
| - | - | - | -: |
| 4 cores | 8 GB | 2 x 1 Gbps | 400 |
| 8 cores | 16 GB | 2 x 1 Gbps | 1,500 |
| 16 cores | 32 GB | 4 x 1 Gbps | 3,000 |
| 24 cores | 64 GB | 8 x 1 Gbps | 4,000 |
| 32 cores | 64 GB | 8 x 1 Gbps | 6,000 |
| 64 cores | 128 GB | 16 x 1 Gbps | 8,000 |
NIC counts are minimums. See the bonding guidance below.
Assume 3 to 5 concurrent connections per active user at peak. Heavy SaaS or streaming environments reach 6 to 8.
For example, 200 active users at 5 connections each is 1,000 concurrent connections. That maps to 8 cores and 16 GB above.
Average session duration is typically 3 to 5 minutes, with peaks between 09:00 and 11:00 and between 14:00 and 16:00. Size for the peak window, not the daily mean.
**Above 4,000 concurrent connections**, assign multiple WAN IP addresses to avoid outbound NAT pool exhaustion. Evaluate [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) rather than a single larger node.
## Require AES-NI
A CPU without AES-NI decrypts SSL 3 to 5 times slower. This produces latency spikes and dropped connections under HTTPS inspection load. Verify before committing to hardware:
```bash theme={null}
grep -m1 aes /proc/cpuinfo
```
Expected result: the flags line includes `aes`. An empty result means this CPU should not carry an inspecting proxy.
## Choose the storage media
SafeSquid writes continuously for session logging, behavioural analysis, and threat detection. Storage media choice is a correctness concern, not only a performance one. When writes fall behind, log entries are delayed or missed. The audit trail you depend on during an incident has holes in it.
**Use NVMe SSDs** — M.2 or PCIe-attached — for these paths:
| Path | Holds |
| - | - |
| `/var/log/safesquid` | Access, extended, and service logs |
| `/var/db/safesquid` | Database files |
| `/var/lib/safesquid` | Runtime state and cache |
SATA-connected SSDs have substantially lower write throughput than PCIe-attached NVMe and cause logging delays and missed entries under load. Verify the attachment type, not just the label "SSD".
Use one interface for simple pilot deployments unless a separate management or high-availability design has been approved. For production networks with bonded interfaces, confirm switch-side LACP configuration, VLAN tagging, and MTU. Also confirm gateway selection and failover behavior before routing users.
Evidence should include interface names, MAC addresses, bond mode, switch ports, VLAN IDs. Also record the owner of any routing or firewall policy that forwards traffic toward SafeSquid.
Link Aggregation Control Protocol (LACP) bonding combines physical interfaces into one logical link for bandwidth and redundancy. Without bonding, a single failed NIC can take the proxy offline entirely.
Match the bonding layout to the number of physical ports available:
| Physical ports | Recommended bonding configuration |
| - | - |
| 2 | One active-backup bond |
| 4 | Two bonded pairs |
| 8 | Two four-port bonds |
| 16 | Two eight-port LACP bonds |
Bonding is configured on both the host and the switch. A host-side bond without matching switch-side configuration fails open or drops frames. Treat the switch change as part of the same change record.
Pre-install connectivity checks prove the host can reach what it needs. They do not prove the host can carry the load you sized it for. Run a baseline after installation, before production users arrive. So you have a known-good reference to compare against during a later incident.
**Establish a light-load baseline.** Record session latency from `/var/log/safesquid/extended/extended.log`, CPU utilisation, and disk I/O wait. Do this while a small number of clients browse. Keep the figures with the deployment record — the absolute values matter less than having a comparison point.
**Stress test to the sizing target.** Simulate the peak concurrent connections you sized for. Use a load generator configured for HTTP proxy mode such as JMeter, or multiple concurrent browser sessions driven by Selenium. Confirm session counts hold without dropped connections.
**Check logs during and after the run:**
```bash theme={null}
journalctl -u safesquid --no-pager | tail -50
```
Expected result: no resource-exhaustion warnings or connectivity errors during the load window.
**If the test fails, read the symptom:**
| Symptom | Likely cause |
| - | - |
| CPU saturates well below the target connection count | Undersized CPU, or a CPU without AES-NI under HTTPS inspection |
| Sustained high disk I/O wait | SATA-attached storage where NVMe is required |
| Connections drop while CPU and disk are healthy | NIC saturation, or bonding configured on the host but not the switch |
Document the sizing decision, topology diagram, and stress-test result for change control and compliance review.
## Capture sizing evidence
Store these artifacts with the deployment record:
* The peak concurrent-connection figure and how it was measured or estimated.
* The matrix row chosen, and the inspection scope it assumes.
* `grep aes /proc/cpuinfo` output for the target CPU.
* Storage attachment type for each of the three write paths.
* Bond mode, switch ports, and VLAN IDs where bonding is used.
* Network placement diagram and firewall/routing approval.
* Rollout and rollback plan, and DR or rebuild assumptions.
## Troubleshoot sizing failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Sizing cannot be approved | User, throughput, or inspection scope is unknown | Run a pilot and record peak concurrent connections before production sizing |
| Node passes the pilot and fails in production | Pilot ran without inspection enabled | Re-measure with the production control set active, not just the proxy path |
| Latency spikes under HTTPS load | CPU lacks AES-NI | Confirm with `grep aes /proc/cpuinfo`; replace the CPU rather than reducing inspection scope |
| Sustained disk I/O wait | SATA-attached storage on a write path that needs NVMe | Move `/var/log/safesquid`, `/var/db/safesquid`, and `/var/lib/safesquid` to PCIe-attached NVMe |
| Connections drop while CPU and disk are healthy | NIC saturation, or host bond without switch-side LACP | Verify switch configuration matches the host bond, then re-test |
| Outbound connections fail above \~4,000 concurrent | NAT pool exhaustion on a single WAN IP | Assign additional WAN addresses, or cluster instead of scaling the node |
| Node meets the matrix but still drops sessions | Sized against average, not peak | Re-measure during the 09:00-11:00 window and resize |
| Logs cannot be retained | Disk or SIEM ownership is unclear | Assign a retention owner and capacity target before installation |
## Next steps
* [Log-Retention Planning](/deployment/log_retention_planning) - size the log volume deliberately against the retention target.
* [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) - scale out rather than up above 4,000 connections.
* [Choose an Architecture](/deployment/choose_an_architecture) - confirm placement before committing to hardware.
# HTTPS Inspection Validation
Source: https://docs.safesquid.com/deployment/https_inspection_validation
Prove SafeSquid is decrypting and inspecting HTTPS sessions rather than tunnelling them, using the certificate issuer as the positive test.
# Prove HTTPS Is Inspected, Not Tunnelled
An HTTPS site that loads through the proxy proves nothing about inspection. SafeSquid can tunnel the session untouched and the page still renders perfectly. The control appears to work while [malware scanning](/use_cases/malware_scanning/malware_scanners), [DLP](/use_cases/data_leakage_prevention/data_leakage_prevention), and content policy see nothing but an opaque stream.
The certificate issuer is the only reliable positive test. Everything else is a page that loaded.
## Validate prerequisites
Confirm:
* [Proxy Connectivity](/deployment/proxy_connectivity) passes for plain HTTP.
* The SafeSquid Root CA has been deployed to the pilot client's trust store, if inspection is enabled.
* The intended inspection scope is documented, including any destinations deliberately excluded.
* A rollback path exists for the client trust store.
## Request an HTTPS site through the proxy
From the pilot client:
```bash theme={null}
curl -I --proxy http://SAFESQUID-IP:8080 https://www.google.com
```
Expected result: the connection succeeds or fails with a known certificate-trust condition that matches the current [SSL inspection](/use_cases/ssl_inspection/ssl_inspection) stage.
Check the access log on the SafeSquid server:
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: the log records the HTTPS destination and policy action.
**TLS warning risk:** A browser certificate warning is not a successful production HTTPS inspection test. It is evidence that endpoint trust, SSL policy, or the test path still needs review.
If SSL inspection is not configured yet, do not normalise browser certificate-warning bypasses for production users. Limit any warning bypass to an isolated pilot test and record it in the change evidence. Complete Root CA deployment before production HTTPS inspection.
## Read the certificate issuer
Once SSL inspection is configured and the Root CA is deployed, the positive test is the certificate itself. Load an HTTPS site in the pilot browser and inspect the certificate issuer.
Expected result: the issuer is the SafeSquid CA, and no warning appears.
An issuer showing the original site's certificate authority means the connection is tunnelled rather than inspected. The page still loads normally. That is the failure this page exists to catch.
Check an excluded destination too. A destination on the bypass list should show its original issuer. If it shows the SafeSquid CA, the exclusion is not matching. Traffic the business agreed not to decrypt is being decrypted.
## Capture inspection evidence
Store these artifacts with the deployment record:
* Certificate issuer for an inspected destination, showing the SafeSquid CA.
* Certificate issuer for an excluded destination, showing the original CA.
* The matching access-log entries for both.
* The documented inspection scope, with the business owner of each exclusion.
* Root CA rollout evidence for the pilot client.
## Troubleshoot inspection failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Browser shows a certificate warning | Root CA is not in the client trust store | Complete Root CA deployment through GPO, MDM, or the approved trust process before retesting |
| Page loads but issuer is the original CA | Session is tunnelled, not inspected | Confirm the destination is in the inspection scope and that SSL inspection is enabled for that policy |
| An excluded destination shows the SafeSquid CA | Exclusion rule is not matching | Correct the bypass entry and re-test; a mis-scoped exclusion decrypts traffic the business excluded |
| Some applications fail while browsers work | Certificate pinning in the application | Add the application's destinations to the documented exclusion list with a named business owner |
| HTTPS fails entirely after enabling inspection | Firewall, trust, or service failure overlap | Re-run [Service Health](/deployment/service_health) first, then re-check Root CA rollout |
## Next steps
* [Policy Enforcement](/getting_started/configure_web_security_policies) - confirm controls act on the decrypted traffic.
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) - configure or adjust the inspection policy.
* [Import Certificate](/use_cases/ssl_inspection/import_certificate_chrome_ie) - deploy Root CA trust to clients.
# Licensing Requirements
Source: https://docs.safesquid.com/deployment/licensing_requirements
Understand what SafeSquid activation unlocks, how the free and commercial tiers differ, and what licensing state the deployment plan has to assume.
# Know What the Licence Buys
An unactivated instance runs with limited capability regardless of which tier you hold. A deployment planned around threat intelligence or categorization that the licence does not include passes the pilot. It fails the first real policy decision.
Settle the tier before sizing and before policy design — both depend on which feeds are available.
## Compare the tiers
SafeSquid offers two licensing tiers.
| Capability | Free | Commercial |
| - | :-: | :-: |
| Core proxy and filtering | Yes | Yes |
| SSL inspection | Yes | Yes |
| Custom policies and profiles | Yes | Yes |
| Real-time threat intelligence | No | Yes |
| URL categorization database | No | Yes |
| Disaster-recovery backup, 365 days | No | Yes |
| Email support | No | Yes |
The free licence has no time limit. Upgrade to commercial at any point through the [Self-Service Portal](https://key.safesquid.com); the deployment steps are the same for both tiers.
## Plan around what the tier excludes
The two exclusions that most often surprise a deployment:
* **[URL categorization](/use_cases/access_restriction/web_categorization).** Category-based access policy is central to most acceptable-use designs. On the free tier those rules have no categorization database behind them, so the policy exists but does not classify.
* **Disaster-recovery backup.** [Configure Cloud Restore](/use_cases/customisation/configure_cloud_restore) depends on the commercial tier. A DR plan built on it needs the licence to match.
Confirm which tier the deployment assumes, and record it, before policy design begins.
## Treat licence state as audit evidence
Activation also matters for audit. Licensed state is visible in the [Configuration Portal](/architecture/interface/configuration_portal) and serves as evidence that the gateway is correctly licensed. The activation key itself is not the audit artifact. Store the key securely and capture licence-state evidence from the interface instead.
## Capture licensing evidence
Store these artifacts with the deployment record:
* The tier the deployment assumes, and who approved it.
* The activation key storage location and its access control.
* A record of licensed state from the Configuration Portal.
* The subscription renewal owner, for commercial deployments.
## Troubleshoot licensing assumptions
| Symptom | Likely cause | Fix |
| - | - | - |
| Category rules match nothing | Free tier has no categorization database | Confirm the tier against the policy design; upgrade or redesign the rules |
| Threat intelligence feeds are absent | Free tier excludes real-time intelligence | Plan detection around the feeds the tier includes |
| Cloud Restore is unavailable | DR plan assumes a commercial capability | Confirm the tier before relying on Cloud Restore for recovery |
| Capability disappears after a period | Commercial subscription expired | See [Manage Subscription State](/deployment/manage_subscription_state) |
| Licence state cannot be evidenced | Only the key was stored, not the portal record | Capture licensed state from the Configuration Portal for the deployment record |
## Next steps
* [Register and Get Your Key](/getting_started/register) - obtain the activation key.
* [Activate Your License](/getting_started/activate) - apply it to the instance.
* [Manage Subscription State](/deployment/manage_subscription_state) - handle renewal and expiry.
# Log-Retention Planning
Source: https://docs.safesquid.com/deployment/log_retention_planning
Set the SafeSquid log retention target, choose local versus forwarded storage, and size the log volume so enforcement evidence survives an incident.
# Decide How Long Evidence Survives
SafeSquid deployment evidence must survive troubleshooting and audit review. The default retention is shorter than most compliance regimes require, and a full log volume truncates evidence silently. The gap is discovered during an incident, when the window you need turns out to have rolled off.
Set the target before installation. Retention is a storage decision, and storage is a sizing input.
## Plan what has to be retained
* Local access logs under `/var/log/safesquid/extended/`.
* Reporting Service or SIEM forwarding where required.
* Change records for activation, policy, Root CA rollout, and client routing.
* Time synchronization so log timestamps match incident timelines.
* Disk capacity for access logs, reports, support bundles, and packet captures used during incidents.
## Set the retention target
**Default local retention is 30 days.** For compliance regimes that require 90 days or more, forward logs rather than extending local disk alone:
* External syslog — rsyslog, Splunk, ELK.
* [Reporting Service](/architecture/interface/reporting_service).
* Cloud object storage such as S3 or Azure Blob.
Forwarding does not remove the need for local retention. Keep enough local history to diagnose an outage and to recover from a forwarder failure. The forwarder is exactly what breaks during the incident you need the logs for.
Separate high-write log and cache storage where the deployment model allows it. For production nodes, record the retention target for:
* `/var/log/safesquid/extended/` access logs.
* Configuration backups and exported reports.
* Support bundles and temporary diagnostics.
* OS logs, Monit logs, BIND9 logs, and package-manager logs.
If logs are forwarded to a SIEM, still preserve enough local retention for outage diagnosis and forwarder-failure recovery.
Monitor `/var/log/safesquid` usage on a schedule and alert before the volume fills. Storage media choice matters here too — see the NVMe write paths in [Hardware Sizing](/deployment/hardware_sizing).
## Assign the ownership
Retention fails on ownership more often than on capacity. Record:
* Who owns the retention target and reviews it.
* Who owns the SIEM or syslog destination.
* Who is alerted when the log volume approaches capacity.
* Who confirms, after an incident, that the relevant window was actually retained.
## Capture retention evidence
Store these artifacts with the deployment record:
* The agreed retention target and the requirement that drove it.
* `df -h /var/log/safesquid` output against that target.
* The forwarding destination and proof of receipt, where configured.
* The named owner of retention and the review cadence.
## Troubleshoot retention gaps
| Symptom | Likely cause | Fix |
| - | - | - |
| Log volume fills without warning | No capacity alert configured | Add monitoring on `/var/log/safesquid` with an owner for the alert |
| Required window has rolled off | Local retention shorter than the compliance requirement | Forward logs, and raise local retention to cover outage diagnosis |
| Forwarded logs are incomplete | Forwarder failed during the incident window | Keep local retention as the fallback; confirm receipt, not just forwarder state |
| Timestamps do not correlate across systems | NTP is unset or drifting | Fix time synchronization before treating logs as correlated evidence |
| Retention target cannot be approved | No named owner for storage or SIEM | Assign the owner before installation, not at the first audit |
## Next steps
* [Logging and Reporting](/deployment/logging_and_reporting) - prove the evidence path works once deployed.
* [Hardware Sizing](/deployment/hardware_sizing) - convert the retention target into a storage decision.
* [Reporting Service](/architecture/interface/reporting_service) - connect reporting and forwarding.
# Logging and Reporting
Source: https://docs.safesquid.com/deployment/logging_and_reporting
Confirm SafeSquid access logs are being written, retained, forwarded, and reportable before the deployment is treated as audit-ready.
# Prove the Audit Trail Exists
Enforcement you cannot evidence is enforcement you cannot defend. A deployment that blocks correctly but logs nothing fails the review that matters. The gap is usually discovered during an incident. The logs for the window in question turn out never to have been written or forwarded.
Confirm the evidence path end to end before declaring the deployment ready.
## Validate prerequisites
Confirm:
* [Proxy Connectivity](/deployment/proxy_connectivity) passes, so requests are reaching the log.
* The log-retention target and its owner are recorded. Use [Log-Retention Planning](/deployment/log_retention_planning) if this is not yet agreed.
* Time synchronisation is working, so log timestamps match incident timelines.
* Where forwarding is required, the SIEM or syslog destination is reachable and owned.
## Confirm logs are being written
On the SafeSquid server:
```bash theme={null}
ls -l /var/log/safesquid/extended/
```
Expected result: `extended.log` exists and its modification time is current.
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: recent entries record source, destination, timestamp, user where authentication is configured, matched policy, and action. Each record is one line of tab-separated, quoted fields. Read `date_time`, `client_ip`, `username`, `method`, `url`, `status`, and `filtering_reason`.
A log file with an old modification time while traffic is flowing means writes are failing or the path changed. Check disk capacity first — a full log volume truncates evidence silently.
## Confirm retention and forwarding
Check the volume that holds the logs:
```bash theme={null}
df -h /var/log/safesquid
```
Expected result: free capacity is consistent with the agreed retention target. There is headroom for support bundles and packet captures during an incident.
Where logs are forwarded, confirm arrival at the destination rather than departure from the host. A forwarder that is running is not proof that anything is being received.
## Confirm reports load
Open the [Configuration Portal](/architecture/interface/configuration_portal) and load a report covering the test window.
Expected result: the report renders and its contents match the access-log entries generated during validation.
Empty reports with healthy access logs mean the reporting path — not the proxy — is broken. Verify access logs first, then the reporting integration.
* [ ] `/var/log/safesquid/` contains current access logs.
* [ ] The host reaches its update servers.
* [ ] An update schedule is defined, whether automatic or manual.
* [ ] Log forwarding to the monitoring or SIEM platform works, where configured.
* [ ] Reports load in the Configuration Portal.
## Capture logging evidence
Store these artifacts with the deployment record:
* Access-log entries from `/var/log/safesquid/extended/extended.log` covering the validation window.
* `df -h` output for the log volume against the agreed retention target.
* Proof of receipt at the SIEM or syslog destination, where forwarding is configured.
* A report exported from the Configuration Portal for the same window.
* The named owner of log retention and the review cadence.
This evidence supports SOC 2 change management, ISO 27001 operational control review, and NIST SP 800-53 audit traceability. Collect it at first deployment.
## Troubleshoot logging failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Log file exists but is not growing | Log volume is full, or the write path changed | Check `df -h`, free capacity, and restart the service; confirm entries resume |
| Entries appear without usernames | Authentication is not configured or not matching | Confirm identity integration before relying on user-attributed evidence |
| Reports are empty, access logs are healthy | Reporting integration is not connected | Verify access logs first, then the Reporting Service connection |
| Forwarded logs never arrive | Forwarder is running but the destination rejects or drops them | Confirm receipt at the destination, not just forwarder state |
| Timestamps do not match other systems | NTP is unset or drifting | Fix time synchronisation before correlating evidence across systems |
## Next steps
* [Log-Retention Planning](/deployment/log_retention_planning) - set the retention target this evidence has to meet.
* [Reporting Service](/architecture/interface/reporting_service) - connect and operate reporting.
* [Production-Readiness Checklist](/getting_started/verify_your_setup) - close out the full validation sequence.
# Manage Subscription State
Source: https://docs.safesquid.com/deployment/manage_subscription_state
Handle SafeSquid commercial subscription expiry — what degrades, what keeps running, and how to renew or extend the conservation period.
# Handle Expiry Before It Degrades Enforcement
Expiry degrades the deployment; it does not stop it. Core proxy and filtering keep running, so nothing obvious breaks — and that is the risk. Threat feeds quietly drop to a weekly schedule while the deployment reports itself healthy. The gap only becomes visible when something current gets through.
Knowing which half still works prevents an unnecessary emergency. Knowing which half does not prevents a false sense of coverage.
## Know what expiry changes
**Continues working**
* Core proxy and filtering, uninterrupted.
**Reduces to the free-tier schedule**
| Feed | Update frequency after expiry |
| - | - |
| Anti-virus engine | Weekly |
| Web categorization | Weekly |
| SSL security updates | Weekly |
| Application and content signatures | Monthly |
**Becomes unavailable**
* Real-time threat intelligence, disaster-recovery backup, and email support.
Free licences do not expire, so this applies only to commercial subscriptions.
## Choose the recovery option
**Option 1 — renew.** Sign in to [key.safesquid.com](https://key.safesquid.com) and go to **Manage
Account**.
**Missing:** whether a "Renew Subscription" action is available there is unconfirmed —
it wasn't visible for a Trial-plan account when last checked (2026-09-02); a Commercial plan may
show it. If you don't see it, contact SafeSquid support rather than assuming renewal isn't
possible.
After renewing, download the updated activation key and upload it under
[Subscription](/configuration/infrastructure_and_access/subscription) using the same steps as the
initial activation.
**Option 2 — conserve the subscription.** From **Manage Account**, use **Conserve Subscription**
(this button was previously labeled "Extend Conservation Period" — confirm which label your
portal shows, since this has changed at least once).
It extends the support window and clears
the expiry banner for that period. It can be applied more than once, but it is a bridge to
renewal, not a substitute for it — treat repeated use as a signal that subscription ownership
needs attention.
Restart SafeSquid from the interface after either action — see
[Support](/configuration/infrastructure_and_access/support) — so the new state takes effect.
Identify who owns the subscription account before taking either action.
Confirm the account owner approves the renewal or conservation-period path.
If subscription ownership is unclear, pause and resolve it. An extension applied without an owner defers the problem without assigning it.
Use the Self-Service Portal workflow for the approved option.
Confirm the action completes and the updated key is downloaded, where renewing.
![Manage Account tab showing the Extend Conservation Period option, now labelled Conserve Subscription]()
Restart SafeSquid from the interface, then confirm subscription state in the [Configuration Portal](/architecture/interface/configuration_portal).
Confirm the expiry banner is cleared and feed schedules have returned to the commercial cadence.
If the state has not changed, re-check that the updated key was uploaded, not just downloaded.
## Capture subscription evidence
Store these artifacts with the deployment record:
* Which option was used, renewal or conservation period, and who approved it.
* The date of the action and the new expiry date.
* A record of subscription state from the Configuration Portal after the restart.
* The named owner of the subscription and the renewal review date.
## Troubleshoot subscription state
| Symptom | Likely cause | Fix |
| - | - | - |
| Expiry banner persists after renewal | Updated key was downloaded but not uploaded | Upload the new `activation_key` through the interface and restart |
| Feeds stay on the weekly schedule | SafeSquid was not restarted after the key upload | Restart from the interface and re-check subscription state |
| Conservation period cannot be extended | Extension already applied for the current window | Renew the subscription; extensions bridge to renewal, they do not replace it |
| Renewal succeeds, threat intelligence stays off | Outbound update endpoints are blocked | Confirm the update paths in [Ports and Firewall Rules](/deployment/ports_and_firewall_rules) |
| Nobody knows who owns renewal | Subscription ownership was never recorded | Assign an owner and a review date before the next expiry |
## Next steps
* [Licensing Requirements](/deployment/licensing_requirements) - confirm what the tier includes.
* [Activate Your License](/getting_started/activate) - re-apply an updated activation key.
* [Ports and Firewall Rules](/deployment/ports_and_firewall_rules) - confirm the update paths are reachable.
# Ports and Firewall Rules
Source: https://docs.safesquid.com/deployment/ports_and_firewall_rules
The single reference for SafeSquid inbound listeners and outbound endpoints, with the source scopes each rule must be restricted to.
# Open Only What the Proxy Needs
A proxy port open to `0.0.0.0/0` is an open relay waiting to be found. An outbound path left closed is an activation that fails at 02:00 on cutover night. Both failures come from the same gap: firewall rules agreed informally and never written down with a scope.
This page is the single reference for those rules. Agree them with the network owner before installation.
## Restrict the inbound listeners
Each rule has a named source scope. None should be opened to `0.0.0.0/0`.
| Port | Protocol | Purpose | Restrict to |
| - | - | - | - |
| `8080` | TCP | HTTP proxy listener | Approved client networks |
| `8443` | TCP | Management interface | Administrator workstations only |
| `53` | TCP/UDP | DNS, when [integrated DNS security](/use_cases/dns_security/dns_security) is used | Approved client networks |
The management interface is the highest-value target on the host — it changes policy for every user behind the proxy. Restrict it to administrator workstations, not to the client network.
## Allow the outbound paths
| Port | Purpose |
| - | - |
| `80`, `443` | Web access on behalf of clients, plus update and subscription paths |
| `53` | Upstream DNS resolution |
Outbound DNS goes to the root servers `A.ROOT-SERVERS.NET` through `M.ROOT-SERVERS.NET`, or to the upstream resolvers your network team designates. SafeSquid cannot categorize or resolve destinations without it.
### Endpoints that block activation
Activation fails without these. Confirm them before the cutover window, not during it.
| Endpoint | Port | Purpose |
| - | -: | - |
| `key.safesquid.com` | `443` | License management and Self-Service Portal |
| `api.safesquid.net` | `443` | License activation |
### Endpoints that block updates, not activation
The instance activates without these, then quietly stops receiving current data. Treat them as required for a production deployment even though activation succeeds.
| Endpoint | Port | Purpose |
| - | -: | - |
| `swgupdates2.safesquid.net` | `443` | Software and package updates |
| `swgupdates.safesquid.net` | `80` | Legacy update repository |
| `sslupdates.safesquid.com` | `443` | SSL inspection and security updates |
| `category.safesquid.net` | `443` | URL categorization |
| `download.quickheal.com` | `80` | Antivirus signature updates |
| Endpoint | Port |
| - | -: |
| `prourl.itsecure.co.in` | `8080` |
| `encurl.itsecure.co.in` | `8080` |
| `klassify.itsecure.co.in` | `8080` |
| `prourl.itonlinesecure.in` | `8080` |
Treat this page as a deployment checklist, not a firewall exception template. Confirm current endpoint requirements through the approved release or support channel before production allowlisting.
## Verify reachability before installing
```bash theme={null}
nslookup key.safesquid.com
ping -c 3 key.safesquid.com
```
Expected result: the host resolves and reaches the Self-Service Portal path needed for key and activation workflows.
## Capture firewall evidence
Store these artifacts with the deployment record:
* The firewall change record, with owner, source CIDRs, destination services, test window, and rollback.
* Confirmation that `8443` is scoped to administrator networks only.
* Reachability output for the activation endpoints.
* The date of the last review of the outbound allowlist, and its owner.
## Troubleshoot firewall failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Activation fails, proxy works | `key.safesquid.com` or `api.safesquid.net` is blocked | Allow outbound `443` to both, then retry activation |
| Categorization is stale, activation is fine | Update and category endpoints are blocked | Allow the update endpoints above; activation success does not imply they are reachable |
| Proxy port is exposed too broadly | Rule was written without a source scope | Restrict to the approved client CIDRs and re-record the change |
| Management interface reachable from user networks | `8443` scoped to the client network | Re-scope to administrator workstations immediately; treat as an exposure |
| Host cannot resolve portal names | Outbound `53` blocked or resolver unreachable | Fix DNS before installation; every later step depends on it |
## Next steps
* [Deployment Checklist](/getting_started/install_safesquid/prerequisites) - confirm the resolver, time source, and the rest of the readiness list.
* [Activate Your License](/getting_started/activate) - apply the key once the activation endpoints are reachable.
* [Hardware Sizing](/deployment/hardware_sizing) - size the node these rules will carry traffic for.
# Proxy Connectivity
Source: https://docs.safesquid.com/deployment/proxy_connectivity
Prove a client reaches the SafeSquid listener and that its requests appear in the access log, using client-side checks the server cannot perform on itself.
# Prove Traffic Reaches the Proxy
A healthy proxy that clients cannot reach passes every check run on the server. The failure only appears from the client side. By then users are already escalating. The fastest workaround an impatient administrator reaches for is removing the proxy setting entirely.
Run this check from a pilot client, not from the SafeSquid host.
## Validate prerequisites
Confirm:
* [Service Health](/deployment/service_health) passes on the SafeSquid node.
* At least one pilot client is configured to use SafeSquid as its proxy. Use [Connect Your Client](/getting_started/client_configuration/connect_your_client) for the routing path.
* You have shell access to the SafeSquid server to read the access log.
* The test window is approved in the change record.
## Request an HTTP site through the proxy
From the pilot client:
```bash theme={null}
curl -I --proxy http://SAFESQUID-IP:8080 http://example.com
```
Expected result: the request returns an HTTP response such as `200`, `301`, or `302`.
## Confirm the request was logged
The client response alone does not prove the request went through SafeSquid. A bypassed client reaches the site just as successfully. The access log is the proof.
On the SafeSquid server:
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: the log records the pilot client IP address, destination host, timestamp, and action. Each record is one line of tab-separated, quoted fields. Read `date_time`, `client_ip`, `username`, `method`, `url`, `status`, and `filtering_reason`.
If the request succeeded but no entry appears, the client is bypassing SafeSquid or the wrong proxy address is configured. Treat that as a failed test, not a logging problem.
Run this from a client workstation, not from the SafeSquid host. It catches the failures that server-side checks cannot see. A healthy proxy that clients cannot reach still passes every check on the server.
**Network connectivity**
* [ ] `ping ` succeeds from the client.
* [ ] The proxy port accepts connections. On Windows, PuTTY in raw mode serves the same purpose as `telnet`:
```bash theme={null}
telnet 8080
```
**Client configuration**
* [ ] Browser proxy points at `:8080`.
* [ ] OS-level proxy is configured, where all applications must be covered.
**Licence and interface access**
* [ ] `http://safesquid.cfg/` loads when the proxy is configured.
* [ ] The activation key has been uploaded through the interface.
* [ ] **Support → License Details** shows an active state.
**Remote management, where used**
* [ ] An SSH client is available on the administrator workstation.
* [ ] Public keys are installed on the SafeSquid host if key-based authentication is required.
* [ ] `ssh @` succeeds from the approved management network.
## Capture connectivity evidence
Store these artifacts with the deployment record:
* The `curl` command and its response headers.
* The matching access-log line from `/var/log/safesquid/extended/extended.log`, showing source, destination, timestamp, and action.
* The pilot client's proxy configuration.
* The completed client-side checklist, with the tester named.
## Troubleshoot client routing
| Symptom | Likely cause | Fix |
| - | - | - |
| `curl` fails to connect | Firewall blocks the client network, or the listener is bound elsewhere | Confirm the inbound rule for the client CIDR, then re-run [Service Health](/deployment/service_health) |
| Request succeeds but no log entry | Client bypasses the proxy, or the wrong log path was checked | Confirm proxy settings on the client and inspect `/var/log/safesquid/extended/extended.log` |
| Only some clients are logged | Bypass rule or PAC exception is matching more broadly than intended | Review PAC logic and bypass lists; narrow to named destinations |
| `safesquid.cfg` does not load | Pilot browser is not using SafeSquid | Configure explicit proxy and retry before investigating the portal |
| Connections work then drop under load | NIC saturation, or bonding configured on the host but not the switch | Compare against the sizing plan in [Hardware Sizing](/deployment/hardware_sizing) |
## Next steps
* [HTTPS Inspection Validation](/deployment/https_inspection_validation) - prove encrypted traffic is inspected, not tunnelled.
* [Logging and Reporting](/deployment/logging_and_reporting) - confirm evidence is retained and reportable.
* [Explicit Browser Proxy](/getting_started/client_configuration/explicit_proxy) - re-check the client routing method.
# Restore Configuration and Certificates
Source: https://docs.safesquid.com/deployment/restore_configuration_and_certificates
Restore SafeSquid policy and SSL material onto a rebuilt or new appliance, and verify what the restore did not bring back.
# Restore Policy, Then Rebuild the Rest
Cloud Restore brings back policy and SSL material bound to the activation key. It does not bring back the host — networking, OS configuration, and integration secrets stay missing. A restore declared complete before those are checked leaves a proxy that looks configured and cannot pass traffic.
Restore in two halves: what the backup covers, then what it does not. The two halves split like this:
```mermaid theme={null}
flowchart TB
Restore[Cloud Restore recovers] --> Policy[config.xml - all policies and settings]
Restore --> Cert[ROOT X509 certificate]
Restore --> Key[ROOT private key]
Rebuild[You rebuild manually] --> Net[Interface IP hostname and routing]
Rebuild --> DNSNTP[DNS and NTP configuration]
Rebuild --> Secrets[Directory integration and connector secrets]
Rebuild --> OS[OS configuration and hardening]
Rebuild --> Fwd[Log forwarding destinations and credentials]
```
## Validate prerequisites
Confirm:
* SafeSquid is installed on the new or rebuilt appliance.
* The **same** activation key used for the backup is available. The backup is bound to it.
* The build record for the original host is at hand, for the settings the backup excludes.
* Cloud Restore was configured on the original appliance. See [Configure Cloud Restore](/use_cases/customisation/configure_cloud_restore).
## Restore the backed-up material
Activate the rebuilt appliance using the same activation key that produced the backup.
Confirm activation succeeds and the licensed state is visible in the [Configuration Portal](/architecture/interface/configuration_portal).
If activation fails, resolve it before attempting restore — the restore prompt only appears for an activated instance.
Select **Cloud Restore** under **Support** in the Configuration Portal.
Confirm the restore prompt appears. It is shown only when SafeSquid finds a cloud backup matching the activation key.
If no prompt appears, the key does not match the backup. Check the key before assuming the backup is gone.
Restart SafeSquid so the restored configuration takes effect.
Confirm the service returns to a running state after the restart.
If the service fails to start, inspect the service log before re-running the restore.
These files are restored:
| Path | Holds |
| - | - |
| `/usr/local/safesquid/security/policies/config.xml` | All policies and settings |
| `/usr/local/safesquid/security/ssl/ROOT_X509File.cer` | SSL root certificate |
| `/usr/local/safesquid/security/ssl/ROOT_PrivateKeyFile.pem` | SSL private key |
Restoring the original Root CA is what keeps already-deployed client trust valid. A rebuilt appliance with a newly generated CA forces a fresh trust rollout to every endpoint. Teams usually discover this when users start seeing certificate warnings.
## Verify what was restored
1. Open the Configuration Portal.
2. Navigate to **Configure → Application Setup → Access restrictions**, or any configured section.
3. Confirm policies match the state from the original appliance.
4. Check the SSL certificate: there is no distinct "SSL Inspection" section in the console
(confirmed live, 2026-08-27/28, build `2026.0627.1344.3`) — HTTPS-inspection policy lives as
individual rule entries inside **Configure → Restriction Policies → Access Profiles** (for
example a `BYPASS SSL INSPECTION` Added Profile value). Confirm those entries match the
original appliance, and separately confirm the certificate details match the original CA by
inspecting the certificate in a client's browser.
5. Test a client connection through the rebuilt appliance.
Expected result: policies, user groups, and SSL certificates match the backed-up configuration. A pilot client's request appears in the access log.
## Restore what the backup excluded
These are not in the cloud backup. Re-apply each from the build record:
* Interface IP address, hostname, and routing.
* DNS and NTP configuration.
* Directory integration secrets and external connector settings.
* Operating system configuration and hardening.
* Log forwarding destinations and credentials.
Verify traffic flows end to end through the rebuilt appliance before returning it to production. See [Production-Readiness Checklist](/getting_started/verify_your_setup).
## Capture restore evidence
Store these artifacts with the incident or change record:
* The date of the restore and the backup version it recovered.
* Confirmation that the restored Root CA matches the original, with issuer detail.
* The list of excluded items re-applied, and by whom.
* Client-side proof that traffic passes through the rebuilt appliance.
* Any policy difference found between the restore and the expected state.
## Troubleshoot restore failures
| Symptom | Likely cause | Fix |
| - | - | - |
| No restore prompt appears | Activation key differs from the one that made the backup | Activate with the original key; the backup is bound to it |
| Policies restore, clients still fail | Network settings were not re-applied | Restore interface, routing, and DNS from the build record |
| Clients see certificate warnings after restore | A new Root CA was generated instead of restoring the original | Confirm the restored `ROOT_X509File.cer` matches the deployed CA; re-run the restore if it does not |
| Directory authentication fails | Integration secrets are outside the backup scope | Restore LDAP credentials from their own approved store |
| Restore recovers an unwanted configuration | Single-version retention overwrote the good backup | See the retention constraint in [Backup Strategy](/use_cases/scaling_and_high_availability/disaster_recovery) |
## Next steps
* [Configure Cloud Restore](/use_cases/customisation/configure_cloud_restore) - set up or repair the backup path.
* [Backup Strategy](/use_cases/scaling_and_high_availability/disaster_recovery) - understand what the backup covers.
* [Production-Readiness Checklist](/getting_started/verify_your_setup) - re-validate before returning to production.
# Service Health
Source: https://docs.safesquid.com/deployment/service_health
Prove the SafeSquid process, proxy listener, and local DNS resolver are running and healthy before routing user traffic through the node.
# Prove the Node Is Actually Serving
A node that answers `systemctl status` is not necessarily serving traffic. The process can be running while the listener never bound. The listener can also be up while local DNS resolution is dead. In both cases users see failures that look like network problems, so the proxy is the last thing anyone checks.
Run these checks first. Everything else in validation assumes the service is genuinely up.
## Validate prerequisites
Confirm:
* SafeSquid is installed on the host under test.
* You have shell access to the SafeSquid server.
* The approved proxy listener port is known and recorded in the change record.
## Prove the listener bound
Run the listener check on the SafeSquid server:
```bash theme={null}
ss -lntp | grep ':8080'
```
Expected result: SafeSquid listens on the approved proxy port.
An empty result with a healthy service means the process started but failed to bind. The cause is usually a port already in use, or a listener address that does not exist on this host. Check the service log before changing configuration.
## Prove the process is alive
```bash theme={null}
pidof safesquid
```
Expected result: one or more process IDs.
On systemd systems, confirm service state:
```bash theme={null}
systemctl status safesquid --no-pager
```
Expected result: `Active: active (running)` and no recent startup errors.
Read the startup lines even when the state is `active`. A service that restarted minutes ago is reporting health for a process that has not yet been under load.
## Prove local DNS resolution
SafeSquid cannot categorise or reach a destination it cannot resolve. Where [integrated DNS security](/use_cases/dns_security/dns_security) is deployed, BIND9 is part of the service, not a separate concern.
```bash theme={null}
nslookup example.com 127.0.0.1
```
Expected result: DNS returns a valid IP address for `example.com`.
If resolution fails:
* Check BIND9 service state with `systemctl status bind9 --no-pager`.
* Check `/etc/bind/named.conf` for syntax or forwarder errors.
* Use [BIND](/architecture/interface/bind) to repair local DNS service configuration.
## Capture service evidence
Store these artifacts with the deployment record:
* `ss -lntp` output showing the bound proxy listener.
* `systemctl status safesquid` output, including the startup lines.
* `nslookup` output from the SafeSquid host.
* The date of the check and the named owner of the node.
## Troubleshoot service failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Port `8080` is not listening | SafeSquid service is stopped or failed to bind | Start SafeSquid, then read the service log for a bind error before changing the port |
| Service is `active` but no PID | Process exited immediately after start | Inspect `journalctl -u safesquid` for a configuration parse failure |
| Service restarts repeatedly | Configuration error or a supervisor restart loop | Check Monit state and the SafeSquid startup log; fix the underlying error rather than disabling the supervisor |
| DNS resolution fails from the host | BIND9 is stopped or the forwarder is unreachable | Restart BIND9 and correct resolver settings before routing clients |
| Listener is bound to the wrong interface | Listener address does not match the client-facing NIC | Correct the listener address, restart, and re-run the `ss` check |
## Next steps
* [Proxy Connectivity](/deployment/proxy_connectivity) - prove a client can actually reach the listener.
* [Production-Readiness Checklist](/getting_started/verify_your_setup) - work through the full validation sequence.
* [Monit](/architecture/interface/supporting_services_monit) - keep the service supervised after validation passes.
# Verify Failover
Source: https://docs.safesquid.com/deployment/verify_failover
Test SafeSquid high-availability failover deliberately, confirm the VIP moves, and keep the evidence that proves the control survived a node loss.
# Untested Failover Is Not High Availability
A configured cluster proves nothing until a node has actually been taken away from it. Split-brain, a truncated `auth_pass`, a health check that never drops priority. Every one of these looks correct in the configuration file and fails only under the condition the cluster exists for.
Test it deliberately, on a schedule, and keep the output.
## Validate prerequisites
Confirm:
* An active-passive pair is configured. See [Monit and Keepalived](/use_cases/scaling_and_high_availability/ha_monit_keepalived).
* Both nodes are healthy and the VIP is currently held by the Master.
* The test window is approved, and clients affected by a brief handover are known.
* You have shell access to both nodes.
## Confirm the starting state
On the Master, confirm Keepalived owns the VIP and the health check passes:
```bash theme={null}
sudo systemctl status keepalived
sudo journalctl -u keepalived -n 30 --no-pager
```
Expected output on the Master includes:
```text theme={null}
(SAFESQUID_VIP) Entering MASTER STATE
VRRP_Script(check_safesquid) succeeded
```
Confirm the address is Keepalived-owned, not statically assigned:
```bash theme={null}
ip a show INTERFACE | grep VIP-ADDRESS
```
Expected output on the Master only:
```text theme={null}
inet VIP-ADDRESS/32 scope global proto keepalived INTERFACE
```
The `proto keepalived` tag confirms Keepalived owns the address and will withdraw it automatically on failover. An address without that tag was assigned statically and will not move.
## Trigger the failover
Open two terminals. Watch the log on the Backup while you stop SafeSquid on the Master.
```bash theme={null}
# Backup node: follow the Keepalived log
sudo journalctl -u keepalived -f
```
```bash theme={null}
# Master node: trigger the failure
sudo systemctl stop safesquid
```
Within 10–15 seconds the log shows the handover:
```text theme={null}
(SAFESQUID_VIP) Changing effective priority from 101 to 0
(SAFESQUID_VIP) Master received advert from BACKUP-IP with higher priority 100
(SAFESQUID_VIP) Entering BACKUP STATE
(SAFESQUID_VIP) Transition to MASTER STATE
Sending gratuitous ARP on INTERFACE for VIP-ADDRESS
```
Confirm the VIP moved:
```bash theme={null}
ip a show INTERFACE | grep VIP-ADDRESS
```
Expected result: the address now appears on the Backup and is gone from the Master.
Prove it from a client, not only from the nodes. Browse through the VIP and confirm the request appears in the surviving node's access log. A VIP that moved but carries no traffic is a half-successful failover.
## Restore the Master
```bash theme={null}
sudo systemctl start safesquid
```
`nopreempt` keeps the VIP on the Backup after the Master recovers. This avoids a second interruption during business hours. To move the VIP back deliberately, restart Keepalived on the Master: `sudo systemctl restart keepalived`.
## Capture failover evidence
Store these artifacts with the change record:
* `journalctl -u keepalived` extract covering the tested failover, showing the state transition and gratuitous ARP.
* `ip a` output before and after failover, showing VIP ownership on each node.
* `/var/log/keepalived_check.log` and `/var/log/monit.log` for the test window.
* Client-side proof that browsing resumed through the VIP, plus the access-log entries from the surviving node.
* The date of the last tested failover and the named owner of the next test.
Schedule a failover test on the same cadence as your disaster-recovery restore test. A cluster that has not failed over in a year is a configuration file, not a control.
## Troubleshoot failover tests
| Symptom | Likely cause | Fix |
| - | - | - |
| Both nodes report MASTER | `virtual_router_id` or `auth_pass` mismatch | Set an identical `virtual_router_id` and `auth_pass` on both nodes; `auth_pass` must be 8 characters or fewer |
| VIP does not move on failure | `weight` does not drop priority below the Backup | Use `weight -101` so the effective priority reaches 0 |
| VIP moves but clients still fail | Clients point at a node address, not the VIP | Repoint PAC, GPO, or MDM at the VIP; a profile naming the Master will not fail over |
| VIP present but tagged differently | Address was assigned statically | Remove the static assignment; only a `proto keepalived` address will move |
| Handover works, logs are empty on the survivor | Traffic is not reaching the surviving node | Confirm firewall rules permit the client network to both nodes, not just the Master |
## Next steps
* [Monit and Keepalived](/use_cases/scaling_and_high_availability/ha_monit_keepalived) - review or correct the cluster configuration.
* [Backup Strategy](/use_cases/scaling_and_high_availability/disaster_recovery) - pair failover testing with a restore test.
* [Configuration Sync](/use_cases/customisation/configuration_sync) - keep policy identical on both nodes.
# FAQs
Source: https://docs.safesquid.com/faqs/faqs
Frequently asked questions about SafeSquid Secure Web Gateway covering installation, configuration, licensing, and troubleshooting common issues.
# Find Answers to Common SafeSquid Questions
Common questions about SafeSquid SWG: installation, activation, licensing, proxy modes, reporting, transparent proxy, WCCP, DLP, SafeSearch, and troubleshooting. Use the list below to jump to a topic.
## FAQ index
* [What is SafeSquid for Windows?](#what-is-safesquid-for-windows)
* [Where to get a product activation key](#where-to-get-a-product-activation-key)
* [What is SafeSquid Self Service portal?](#what-is-safesquid-self-service-portal)
* [Who has access to the SafeSquid Web GUI](#who-has-access-to-the-safesquid-web-gui)
* [How to confirm SafeSquid is activated](#how-to-confirm-safesquid-is-activated)
* [Where to get license details](#where-to-get-license-details)
* [Why does Proxy Access Denied appear?](#why-does-proxy-access-denied-appear)
* [Does SafeSquid supports transparent proxy?](#does-safesquid-supports-transparent-proxy)
* [When to enable WCCP](#when-to-enable-wccp)
* [How does SafeSquid licensing work?](#how-does-safesquid-licensing-work)
* [How to purchase SafeSquid SWG](#how-to-purchase-safesquid-swg)
## What is SafeSquid for Windows?
SafeSquid for Windows is content filtering proxy server. SafeSquid for Linux has been natively ported for use on Microsoft Windows platform, and distributed as SafeSquid for Windows. It provides total access control, Total Content Control & Total Internet Security. SafeSquid for Windows can be installed on any desktop/server having Microsoft Windows based 64-bit Operating Systems.
## Where to get a product activation key
Obtain a product activation key **on SafeSquid self-service portal** - [https://key.safesquid.com/](https://key.safesquid.com/)
Register to create an account on **SafeSquid self-service portal** and **download the product activation key**
## What is SafeSquid Self Service portal?
The SafeSquid Self-Service Portal is the cloud-based management console for SafeSquid.
The SafeSquid Self-Service Portal manages these activities: cloud-backed features, Custom Web Categorization, and Web Security Clients for Roaming users (VPN). It also manages Confidential Data Signatures and Subscription management.
Read more: [Self-Service Portal](/architecture/interface/self_service_portal).
## Who has access to the SafeSquid Web GUI
SafeSquid has an intrinsic Web GUI. It enables administrators to manage the installation, set up required policies, and monitor the secure web gateway.
Configure SafeSquid policies to allow access of the Web GUI to only security administrators.
## How to confirm SafeSquid is activated
If all websites are accessible through the browser, the product is activated.
## Where to get license details
After successful activation, license details appear on the Support page of the SafeSquid Web GUI.
For more details see the [Support page](/configuration/infrastructure_and_access/support) (License Details panel, not under Reports) or [Activate your license](/getting_started/activate).
## Why does Proxy Access Denied appear?
"Proxy Access Denied" appears when access restriction policies are misconfigured or the administrator has not granted SafeSquid Interface access.
## Can I use SafeSquid Captive portal to monitor internet usage traffic?
Yes. SafeSquid captive portal can monitor internet usage traffic.
## What is SafeSquid Captive portal?
SafeSquid captive portal is works as same as general captive portal.
Used to enhance security of WIFI network by authenticating users before granting internet access.
Users receive the SafeSquid Captive Portal landing page when accessing the internet via the WIFI network and enter credentials there.
SafeSquid captive portal validates user credentials using various authentication mechanisms. It maintains a database of authenticated source IP addresses and usernames for lookup.
If a user from a source IP address authenticated through captive portal, SafeSquid picks the username from the database. It attaches that username to the traffic coming from the same source IP address.
This way SafeSquid captive portal secures WIFI network by only granting access to valid users
Combining SafeSquid Captive Portal with SafeSquid secure web gateway allows monitoring of internet usage and filtering of traffic. It also adds other security enhancements.
## Does SafeSquid supports transparent proxy?
Yes, SafeSquid supports transparent proxy.
SafeSquid support both HTTP and HTTPS websites in transparent mode. The HTTPS websites in transparent mode called as SSL transparent proxy
The traffic comes to the router. The router sends traffic to SafeSquid Secure web gateway on ports 80 and 443 respectively.
The **redirection rules on SafeSquid Secure web gateway** redirect traffic to SafeSquid Proxy. They use ports 8080 and 8443 (SSL transparent) respectively. This requires IP forwarding to be enabled.
## When to enable WCCP
To redirect traffic transparently, load balance and scale up, or assure service and high availability, enable WCCP in SafeSquid. Enable WCCP support on routers that support WCCP.
Ex: CISCO ASA routers.
Web Cache Communication Protocol (WCCP) is a Cisco-developed content-routing protocol that provides a mechanism to redirect traffic flows in real-time. It has built-in load balancing, scaling, fault tolerance, and service-assurance (failsafe) mechanisms.
Making SafeSquid go direct for some sites
Preventing access to porn sites
## Preventing access to social networking sites
Yes. SafeSquid can prevent users from accessing social networking sites. When configured, SafeSquid blocks all social networking sites by default. Administrators can allow those sites for specific times (e.g. lunch hour).
Allow social networking sites in lunch hours: [Allow Social Networking Sites During Lunch Hours](/use_cases/access_restriction/allow_social_networking_sites_during_lunch_hours).
Facebook is a social networking website. It allows users to interact with other users in a multimedia environment on the Web. Facebook users can install and use applications to enhance their experience. Many organizations want to allow Facebook access to maintain morale, increase retention, and boost hiring. But they also want to control access to it.
SafeSquid allows full Facebook access for a social media group and partial access to a customer service group. It allows read-only access to other groups. Access to Facebook can also be assigned by time of day. For more details: [Facebook Read-Only Mode](/use_cases/content_modifier/facebook_read_only_mode), [Allow Specific Page on Facebook](/use_cases/content_modifier/allowing_specific_page_on_facebook).
## Preventing users from uploading confidential data
Yes. SafeSquid can prevent users from uploading confidential data. When an organization has confidential information and an internal user leaks it intentionally or unintentionally, productivity loss can be large.
Data leakage can occur through many channels. Users can upload important documents to the internet. Even when content filtering blocks Microsoft Word and Excel files, users can create archives of those files. They can then attempt to upload them. Blocking all archives is not practical because staff use archives to transfer large log files.
Other users simply take information out of Microsoft Word and Microsoft Excel. They then send it by email to a third party.
In modern era, these kind of data leaks become a challenge for organizations. Organizations look for content filtering software that can deeply inspect archive files. It must also identify whether an archive or email contains certain keyword matches.
This challenge is also big for security experts. The post data format of an upload differs for Gmail, Google Drive, Mediafire, Dropbox, and similar services. The wide range of post data formats made it difficult for security experts to derive concrete solutions.
SafeSquid embeds an **Advanced DLP** solution in the **SafeSquid SWG**. It analyzes post data and inspects archives deeply using file decomposition methods. It identifies whether archives, emails, or social media posts contain certain keyword matches. Based on the match, the administrator can block uploads by user or by destination website. The Advanced DLP solution is managed from the SafeSquid Self-Service Portal, where administrators create keyword expression matches. SafeSquid SWG will download those keyword expressions and loads into memory. When an archive is uploaded or an email is written, SafeSquid SWG analyses the post data. It then transmits it to the ClamAV daemon for signature verification. If the keyword expression matches Clam AV daemon responds with match. SafeSquid will take respective action based on match.
## Preventing upload of specific file extensions
Yes. SafeSquid can prevent users from uploading specific file extensions.
SafeSquid DLP section is the **Data Loss Prevention module**. It protects against sending sensitive or critical information outside the corporate network.
It is possible by blocking specific file types or file extensions. The block is based on content type and file extension.
## Can I prevent users to use anonymous proxy?
Yes. SafeSquid can prevent users from using anonymous proxy.
An anonymous proxy lets users surf the web anonymously. It tunnels traffic through servers spread across the globe, which involve other IP addresses.
Anonymous Proxy service can enhance security and lets users access some restricted websites online.
For more detail: [Access Restriction](/use_cases/access_restriction/access_restriction) and [Use Cases](/use_cases/use_cases) for blocking anonymous proxies and application control.
## Should third-party cookies be blocked?
SafeSquid can block cookies for third-party domains. This controls tracking across sites and hides the referrer for third-party domains; SafeSquid can set referrer to match hostname. Administrators can also hide user agents for third-party domains; SafeSquid can use a default user agent (e.g. Mozilla/4.0 (compatible; MSIE 5.5; Windows 98; Win 9x 4.90)).
## Where to get SafeSquid default policies
SafeSquid default policies and how-to guides are in the "How To" section of [http://docs.safesquid.com](http://docs.safesquid.com)
## Where to get the performance plot
The performance plot is available on the Support page of the SafeSquid Web GUI. Administrators can generate a performance plot by range: last hour, last 7 days, last month, today, or a custom time.
## Where to get the support tarball
The support tarball is on the Support page of the SafeSquid Web GUI. Administrators can generate a new support tarball or search existing tarballs by year, month, day, or time.
## When to download the config file
The config file can be downloaded at any time. SafeSquid allows download by year, month, day, or time, and allows download of the default config for revert scenarios.
## Is SafeSquid provide dashboard for reporting?
SafeSquid provide dashboard which contain details of last 1000 transactions.
SafeSquid dashboard provides Ip address, Users, User groups, websites domains, profiles, application signature, categories, upload content, download content,
Administrators can edit the total number of transactions for the report. Reports support date-range selection.
Administrators can select any number of filtering options.
## How to get reports in PDF format
SafeSquid reporting supports export to PDF and Excel. Open the SafeSquid interface, go to Reports > Dashboard. The PDF button is at the bottom right, just above the SafeSquid version.
## Can reports be generated for specific dates?
Yes. SafeSquid has a reporting module that reduces processing time. It provides detailed reports, hour-wise reports, and filtering options. It also provides deeper data analysis, an automated data mining engine, and export to PDF and Excel.
## Why does SafeSquid become slow after running for some time?
Slowness after sustained operation is often due to resource exhaustion (disk, memory, or connection state). Check the [Troubleshooting](/troubleshooting/troubleshooting) guide for resource diagnostics and for clearing or rotating logs. Review the **Performance Plot** card on the [Support](/configuration/infrastructure_and_access/support) page for resource usage. Restart the proxy after freeing resources if needed.
## How does SafeSquid licensing work?
SafeSquid SWG is available with annual subscription.
**Base Subscription Plans**
Choose one of the following base subscription plans:
1. Named Users
2. Concurrent Connections
3. CPU Hours
Named Users and Concurrent Connection subscriptions are annual. Multi-year consecutive purchase is available.
**Premium Features Subscription**
1. Data Leakage Prevention
2. Support for Roaming (Windows Laptop) users
3. Log Aggregator
4. WCCP
## How to purchase SafeSquid SWG
Opt for a SafeSquid SWG subscription by paying online via PayPal or by wire or bank transfer.
## What happens if the subscription is not renewed?
**Missing:** whether the proxy stops passing traffic on expiry, or keeps running with reduced
threat-feed coverage, is stated two different ways elsewhere in this documentation set and hasn't
been reconciled.
See [Handle expiry before it degrades enforcement](/deployment/manage_subscription_state)
for the detailed, sourced breakdown of what keeps working and what doesn't — treat that page as
more current until this is confirmed, and don't assume the proxy goes down on expiry without
checking your own deployment's behavior first.
## Next steps
* [Troubleshooting](/troubleshooting/troubleshooting) - find the runbook that matches your symptom.
* [Getting Started](/getting_started/welcome) - learn what SafeSquid does before you configure it.
* [Self-Service Portal](/architecture/interface/self_service_portal) - manage activation keys and licensing.
# Access the Interface
Source: https://docs.safesquid.com/getting_started/access_the_interface
Access the SafeSquid Configuration Portal from an approved management path during onboarding.
# Access the Management Interface Safely
Management access controls who can activate SafeSquid, change policy, and affect web access. Exposing the interface broadly or testing from an unmanaged client creates credential risk and weak audit evidence.
## Validate prerequisites
Before opening the [Configuration Portal](/architecture/interface/configuration_portal), confirm:
* SafeSquid is installed and running.
* A pilot browser is configured to use SafeSquid as proxy.
* The administrator is on an approved management network.
* DNS can resolve the special interface name through the proxy path.
* The change record identifies who is allowed to activate and configure the instance.
## Choose the access path
Use a proxied browser for first access:
1. Configure a pilot browser to use the SafeSquid proxy listener.
2. Open `http://safesquid.cfg/`.
3. Sign in with the approved administrator account.
4. Confirm the page is the SafeSquid Configuration Portal before entering credentials.
Avoid direct broad network exposure of the management interface. The first access path should prove the same proxy path that pilot clients will use.
If the pilot browser is not proxied yet, use direct management access only from an approved administrator network:
```text theme={null}
https://SAFESQUID-SERVER-IP:8443/
```
Document which management path was used. Direct access changes the trust boundary and must not become the default user path.
## Verify baseline state
On the SafeSquid server, confirm the service is running:
```bash theme={null}
systemctl status safesquid --no-pager
```
Expected result: service state is `active` or the platform-specific running state is clear from the output.
From the pilot browser, confirm:
* `http://safesquid.cfg/` loads.
* The Configuration Portal signs in successfully.
* The interface shows expected sections for activation, support, and configuration.
* No certificate warning is used as a workaround for HTTPS testing.
## Capture access evidence
Store:
* Administrator account or role used for first access.
* Pilot client hostname or asset identifier.
* Proxy listener used by the client.
* Screenshot or change record confirming portal access.
* Service status output.
* Any access restriction applied to management networks.
## Troubleshoot access failures
| Symptom | Likely cause | Fix |
| - | - | - |
| `safesquid.cfg` does not load | Browser is not using SafeSquid as proxy | Configure explicit proxy and retry from the same browser |
| Login page appears from the wrong network | Management path is too broad | Restrict access to approved admin networks before continuing |
| Service is not running | Installation or restart failed | Check `systemctl status safesquid --no-pager` and service logs |
| Interface loads but activation fails | Activation key or outbound subscription path is not ready | Continue with [Activate Your License](/getting_started/activate) troubleshooting |
## Next steps
* [Activate Your License](/getting_started/activate) - apply the activation key.
* [Connect Your Client](/getting_started/client_configuration/connect_your_client) - prove pilot traffic flow.
* [Configure Web Security Policies](/getting_started/configure_web_security_policies) - configure controls after activation.
# Activate Your License
Source: https://docs.safesquid.com/getting_started/activate
Upload the SafeSquid activation key, verify licensed state, and capture evidence before configuring production policy.
# Activate Before Policy Rollout
SafeSquid must be activated before the deployment can be treated as ready for enforcement. Activation ties the instance to the Self-Service Portal, unlocks licensed capability. It gives operators a checkpoint before SSL inspection, authentication, URL controls, malware scanning, and DLP are enabled.
## Know what activation unlocks
SafeSquid offers two licensing tiers, and an unactivated instance runs with limited
capability regardless of which tier you hold. See
[Licensing Requirements](/deployment/licensing_requirements) for the tier comparison and
what each one excludes.
## Validate prerequisites
Before activation, confirm:
* The `activation_key` file was downloaded from the [Self-Service Portal](/getting_started/register).
* SafeSquid service is running.
* A pilot browser can reach `http://safesquid.cfg/` through the proxy path.
* The administrator is on an approved management network.
* Outbound DNS and HTTPS access are available for license and subscription validation.
* The change record includes rollback steps for client routing and firewall changes.
## Allow subscription paths
Activation requires outbound reachability to `key.safesquid.com` and `api.safesquid.net`
on `443`. Updates and categorization need a wider set, which activation success does not
prove is reachable. Confirm both groups in
[Ports and Firewall Rules](/deployment/ports_and_firewall_rules) before the cutover window.
Only one endpoint has to be reachable for activation itself to succeed. The rest affect ongoing updates. So a blocked path there produces a licensed gateway with stale intelligence rather than a failed activation. It is a quieter failure, and an easier one to miss.
**Required for activation**
| Host | Port | Purpose |
| - | -: | - |
| `api.safesquid.net` | `443` | License activation |
**Required for ongoing updates**
| Host | Port | Purpose |
| - | -: | - |
| `swgupdates2.safesquid.net` | `443` | Subscription and malware definitions |
| `swgupdates.safesquid.net` | `80` | Seqrite updates |
| `sslupdates.safesquid.com` | `443` | SSL certificate updates |
| `category.safesquid.net` | `443` | Category database updates |
| `download.quickheal.com` | `80` | Virus signature updates |
**URL categorization engines, commercial licence only**
Each of these is reached on port `8080` at the path `/URLCategorizerService/URLCategorize`:
| Host |
| - |
| `prourl.itsecure.co.in` |
| `encurl.itsecure.co.in` |
| `klassify.itsecure.co.in` |
| `prourl.itonlinesecure.in` |
| `encurl.itonlinesecure.in` |
If categorization is blocked while everything else is reachable, policies that depend on category matching fail open. They do not error. Verify this group explicitly rather than inferring it from a working activation.
## Upload the activation key
Configure the pilot browser to use SafeSquid as proxy, open `http://safesquid.cfg/`, and sign in with the approved administrator account.
Confirm the [Configuration Portal](/architecture/interface/configuration_portal) loads through the SafeSquid proxy path.
If `safesquid.cfg` does not load, recheck pilot browser proxy settings and SafeSquid listener reachability.
![Upload activation key prompt in the SafeSquid Configuration Portal]()
When the first-run activation prompt appears, click **Choose File** or the file-selector control. Then select the `activation_key` file from the approved secure location.
Confirm the selected file is named exactly `activation_key`.
If the key is missing or renamed, retrieve the original file from approved secure storage. You can also re-download it from the Self-Service Portal.
![Select the activation key file and upload it]()
Click **Upload**, then click **Restart** when the interface prompts you to apply the license.
Confirm the interface accepts the upload and presents the restart action.
If upload fails, verify file name, file contents, and outbound subscription reachability before retrying.
![Restart SafeSquid after activation key upload]()
Wait for SafeSquid to restart and reload the Configuration Portal before running evidence checks.
Confirm the portal reloads after restart and accepts administrator sign-in.
If the proxy refuses connections, check service state from the server console before routing users.
Do not route production users until activation has been verified and logged.
**License evidence:** The activation key is not the audit artifact. Store the key securely, and capture license-state evidence from the Configuration Portal plus service, listener, and access-log checks.
## Verify activation evidence
Run these checks immediately after activation.
Run the service-state check and confirm there are no recent startup errors.
```bash theme={null}
systemctl status safesquid --no-pager
```
Expected result: the first lines read `safesquid.service - SafeSquid Secure Web Gateway Proxy Server`, `Loaded: loaded` and `Active: active (running)`.
Confirm the service is active and no startup error appears in the recent log.
If the service is inactive, inspect the service journal and restart SafeSquid from the server console after correcting the cause.
Verify that `/usr/local/safesquid/security/activation_key` exists and has not been renamed.
```bash theme={null}
ls -l /usr/local/safesquid/security/activation_key
```
Confirm a file named exactly `activation_key` exists.
If it is missing or renamed, re-upload the downloaded key file.
Confirm SafeSquid listens on the approved proxy port.
```bash theme={null}
ss -lntp | grep ':8080'
```
Expected result: a `LISTEN` line for `*:8080` (the proxy listener). No line means nothing is listening on 8080, so check the service state first.
Confirm SafeSquid listens on the approved proxy port.
If no listener appears, verify service state, startup logs, and the configured proxy port.
Open **Support** and inspect **License Details** for product and subscription state.
![Open the Support menu to view activation status]()
![License Details showing product and subscription state]()
Confirm product type, subscription state, or activation details are populated.
If details are missing, verify subscription reachability and re-upload the correct activation key.
Send one pilot HTTP request through SafeSquid and confirm a new record appears in `/var/log/safesquid/extended/extended.log`.
```bash theme={null}
curl -I --proxy http://SAFESQUID-IP:8080 http://example.com
```
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Confirm the access log records source, destination, timestamp, and action.
If no log appears, confirm the client is using SafeSquid and inspect `/var/log/safesquid/extended/extended.log`.
## Capture activation evidence
Store these artifacts with the deployment record:
* Activation key ownership record from the Self-Service Portal.
* Screenshot or change record showing active license state.
* SafeSquid service status output.
* Listener check for the approved proxy port.
* Access-log entry for a pilot HTTP request.
* Subscription path reachability result.
* Root CA rollout plan before HTTPS inspection.
## Troubleshoot activation
| Symptom | Likely cause | Fix |
| - | - | - |
| `safesquid.cfg` does not load | Browser is not using SafeSquid as proxy | Recheck pilot proxy settings and retry `http://safesquid.cfg/` |
| `Failed to set Subscription details` | Key file is missing, renamed, or not loaded | Verify `/usr/local/safesquid/security/activation_key` and re-upload the correct file |
| Proxy refuses connections after upload | Service restart failed | Check service state and start SafeSquid from the server console if needed |
| Subscription server is unreachable | DNS, routing, or firewall block | Test `nslookup swgupdates2.safesquid.net` and restore outbound access |
| HTTP request succeeds but no log appears | Client bypasses SafeSquid or wrong log path checked | Confirm proxy path and inspect `/var/log/safesquid/extended/extended.log` |
| HTTPS warning appears | Root CA is not trusted or SSL inspection is incomplete | Deploy the Root CA through the approved trust path before retesting HTTPS |
| Commercial subscription is expiring | Renewal or conservation period was not planned | Confirm renewal status in the Self-Service Portal and record any approved conservation-period action |
| Commercial features are inert after a successful activation | A free-tier key was uploaded, or the key has expired | Open **Support** and check **License Details**: Product Type should read Commercial and Expiry should be in the future. If not, download the correct key from the Self-Service Portal and re-upload it |
A commercial subscription that expires degrades the deployment rather than stopping it,
and the degradation is silent. See
[Manage Subscription State](/deployment/manage_subscription_state) for what changes and how
to renew or extend.
## Move toward production
Activation unlocks the controls; it does not configure them. Enable them in a deliberate
order so certificate, routing, and scanning failures do not overlap during troubleshooting:
SSL inspection, then authentication, then DNS and access controls, then content security,
then reporting.
[Policy Enforcement](/getting_started/configure_web_security_policies) carries that sequence
with a verification step for each control.
## Next steps
* [Policy Enforcement](/getting_started/configure_web_security_policies) - apply the baseline control sequence.
* [Connect Your Client](/getting_started/client_configuration/connect_your_client) - expand from pilot routing to managed rollout.
* [Troubleshooting](/troubleshooting/troubleshooting) - diagnose activation, routing, certificate, and policy failures.
# Application-Specific Configuration
Source: https://docs.safesquid.com/getting_started/client_configuration/application_specific_configuration
Configure proxy settings for tools that do not inherit browser or operating system proxy settings.
# Handle Applications That Bypass OS Proxy
Some applications ignore browser, PAC, or operating system proxy settings. Developer tools, package managers, containers, email clients, and command-line utilities can create unlogged egress. Configure them directly or block them from direct internet access.
## Use this method when
Use application-specific configuration when:
* A tool does not appear in SafeSquid access logs.
* Developers or administrators use package managers.
* Command-line tools need controlled internet access.
* Business applications require explicit proxy fields.
Do not use application exceptions to bypass security review. Every exception should have an owner, scope, and expiry or review date.
## Validate prerequisites
Confirm:
* Host or browser proxy routing has already been tested.
* Proxy host, port, and authentication requirements are known.
* Direct internet egress is restricted where possible.
* Tool-specific credentials are not stored in plain text unless the risk is accepted.
* Application owner can test normal business workflow after the change.
## Configure common tools
Use the tabs for frequently approved developer and operations tools. Replace `SAFESQUID-IP` with the approved proxy address and add authentication only through the organization's approved secret-handling method.
```bash theme={null}
git config --global http.proxy http://SAFESQUID-IP:8080
git config --global https.proxy http://SAFESQUID-IP:8080
git config --global --get http.proxy
```
Expected result: Git reports the configured proxy and repository requests appear in SafeSquid access logs.
Exempt internal Git hosts so they are not routed outward:
```bash theme={null}
git config --global http.noProxy "*.internal.example.com"
```
To remove the configuration during rollback:
```bash theme={null}
git config --global --unset http.proxy
git config --global --unset https.proxy
```
```bash theme={null}
npm config set proxy http://SAFESQUID-IP:8080
npm config set https-proxy http://SAFESQUID-IP:8080
npm config get proxy
```
Expected result: npm package requests route through SafeSquid and match package-management policy.
Set the registry explicitly where an internal mirror is in use. This stops package resolution depending on client defaults:
```bash theme={null}
npm config set registry https://registry.npmjs.org/
```
To remove the configuration during rollback:
```bash theme={null}
npm config delete proxy
npm config delete https-proxy
```
Use a per-user or managed configuration file where approved:
```ini theme={null}
[global]
proxy = http://SAFESQUID-IP:8080
```
The file location differs by platform: `~/.pip/pip.conf` on Linux and macOS, `%APPDATA%\pip\pip.ini` on Windows.
For a single command without changing configuration:
```bash theme={null}
pip install --proxy http://SAFESQUID-IP:8080
```
Verify:
```bash theme={null}
python -m pip config list
```
Configure Debian or Ubuntu package traffic through an approved APT proxy file:
```text theme={null}
Acquire::http::Proxy "http://SAFESQUID-IP:8080";
Acquire::https::Proxy "http://SAFESQUID-IP:8080";
```
Store the file through configuration management, then test with a controlled package metadata refresh.
Configure RHEL, CentOS, or Fedora package traffic in the approved package-manager configuration:
```ini theme={null}
proxy=http://SAFESQUID-IP:8080
```
Verify with a metadata refresh and confirm the source IP appears in SafeSquid logs.
Use direct proxy flags for one-off tests or scripted jobs:
```bash theme={null}
curl -I --proxy http://SAFESQUID-IP:8080 http://example.com
wget -e use_proxy=yes -e http_proxy=http://SAFESQUID-IP:8080 http://example.com
```
Expected result: the request succeeds and appears in SafeSquid access logs.
For persistent per-user configuration, both tools read a dotfile:
```text theme={null}
# ~/.curlrc
proxy = "http://SAFESQUID-IP:8080"
```
```text theme={null}
# ~/.wgetrc
http_proxy = http://SAFESQUID-IP:8080
https_proxy = http://SAFESQUID-IP:8080
use_proxy = on
```
Configure Docker proxy settings through the organization's approved daemon or systemd method. Use placeholders for authentication material and store credentials in the approved secret store.
```bash theme={null}
HTTP_PROXY=http://SAFESQUID-IP:8080
HTTPS_PROXY=http://SAFESQUID-IP:8080
NO_PROXY=localhost,127.0.0.1,.internal.example.com
```
Restart the container runtime only in an approved change window. Confirm image pulls and registry metadata requests appear in SafeSquid logs.
The daemon also reads a `proxies` block from `/etc/docker/daemon.json`, which survives service restarts without depending on the unit environment:
```json theme={null}
{
"proxies": {
"http-proxy": "http://SAFESQUID-IP:8080",
"https-proxy": "http://SAFESQUID-IP:8080",
"no-proxy": "localhost,127.0.0.1,.internal.example.com"
}
}
```
Reload the daemon in an approved window, then confirm it took effect:
```bash theme={null}
docker info | grep -i proxy
```
Expected result: the proxy values appear in the daemon configuration. Note that this configures the daemon, which pulls images — containers themselves receive proxy settings separately, through their own environment.
Outlook and Thunderbird can use operating-system proxy settings, but some profiles, add-ins, or mail transports bypass them. Configure proxy settings through the approved desktop-management path and test mailbox sign-in, attachment download, and autodiscover traffic.
Record the mail domains, identity method, and whether SSL inspection is bypassed because of certificate pinning or application behavior.
**Outlook on Windows** inherits the Windows proxy for Exchange and Microsoft 365 accounts, so no separate configuration is usually needed. Where it is:
1. **File → Account Settings → Account Settings**.
2. Select the account, then **Change → More Settings**.
3. On the **Connection** tab, select **Connect using Internet Explorer or a 3rd party dialer**. This routes Outlook through the Windows system proxy.
If Outlook will not connect after the change, temporarily disable Cached Exchange Mode. This isolates whether the failure is in the connection or the local cache.
**Thunderbird** keeps its own settings and ignores the OS configuration:
1. Menu (☰) **→ Settings → General**.
2. Scroll to **Network & Disk Space** and select **Connection Settings**.
3. Choose **Manual proxy configuration**, set the HTTP proxy and port `8080`, and enable **Use this proxy server for all protocols**.
4. Set **No Proxy for** to the approved internal entries, then select **OK**.
For anything else, work through these in order:
1. Check the application's own documentation for a proxy setting.
2. Try the standard environment variables — many tools honour them:
```bash theme={null}
export http_proxy=http://SAFESQUID-IP:8080
export https_proxy=http://SAFESQUID-IP:8080
```
3. Look for a configuration file: `~/.config//` or `~/./` on Linux and macOS, `%APPDATA%\\` on Windows.
4. Check for a command-line flag such as `--proxy`, `-x`, or `--http-proxy`.
Common runtime patterns:
| Runtime | Setting |
| - | - |
| Java | `-Dhttp.proxyHost=SAFESQUID-IP -Dhttp.proxyPort=8080` |
| Ruby gems | `gem install --http-proxy http://SAFESQUID-IP:8080 ` |
| Go modules | `export GOPROXY=http://SAFESQUID-IP:8080` |
Any tool that cannot be routed needs a recorded exception with an owner and a review date. Do not leave a silent direct path to the internet.
Do not store proxy passwords in plain text application config files unless the risk is documented and accepted.
## Verify application evidence
After configuring the tool:
1. Run one safe external request.
2. Run one internal request that should bypass SafeSquid, if applicable.
3. Inspect SafeSquid access logs.
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: external tool traffic appears with source, destination, timestamp, and action.
## Capture exception evidence
Store:
* Application name and owner.
* Hostname or managed group.
* Proxy setting applied.
* Bypass entries.
* Access-log sample.
* Credential-storage decision, if authentication is used.
* Review or expiry date for the exception.
## Troubleshoot application failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Tool still bypasses SafeSquid | Tool ignores OS settings and lacks direct proxy config | Apply the tool-specific proxy setting |
| Authentication fails | Tool cannot use the configured credential method | Use an approved credential mechanism or scoped service account |
| Internal repository fails | Missing bypass for internal destination | Add an exact internal bypass entry |
| Traffic appears without user context | Tool runs as service or system account | Document service identity and add authentication mapping if required |
| Package manager works outside SafeSquid | Direct egress is still open | Restrict direct internet routes and retest through SafeSquid |
| `SSL certificate verify failed` | SSL inspection is active and the tool does not trust the SafeSquid root CA | Install the root CA into the trust store the tool uses; language runtimes often keep their own, separate from the OS |
| `docker pull` fails while other traffic works | Registry host is not in the no-proxy list, or is being proxied when it should not be | Add the registry to `no-proxy`, or confirm the proxy path allows registry traffic |
| `git clone` is unusually slow | Large repository plus proxy overhead | Use SSH rather than HTTPS for large clones, or bypass the proxy for internal Git hosts |
## Next steps
* [Enterprise Deployment](/getting_started/client_configuration/enterprise_deployment) - enforce settings centrally.
* [Configure Web Security Policies](/getting_started/configure_web_security_policies) - apply controls to routed application traffic.
* [Troubleshooting](/troubleshooting/troubleshooting) - diagnose client and policy failures.
# Connect Your Client
Source: https://docs.safesquid.com/getting_started/client_configuration/connect_your_client
Choose the right client routing method and prove that pilot traffic reaches SafeSquid before production rollout.
# Prove Client Traffic Reaches SafeSquid
SafeSquid cannot enforce policy on traffic that bypasses the proxy. Client onboarding must prove that web requests traverse SafeSquid, appear in logs, and can later be tied to user identity. Start with a pilot client, then move to managed rollout.
## Validate prerequisites
Confirm:
* SafeSquid is installed and activated.
* The proxy listener is reachable from the pilot network.
* The pilot client can resolve DNS and reach the proxy IP.
* The operator can inspect `/var/log/safesquid/extended/extended.log`.
* Rollback steps exist for the selected client setting.
## Choose the routing method
Use explicit proxy settings on one browser or host.
Confirm one browser produces a SafeSquid access-log entry.
If no log appears, retest with `curl --proxy`.
Use a PAC file for controlled browser routing and bypass logic.
Confirm PAC evaluation sends internet traffic to SafeSquid.
If internal apps break, correct exact bypass logic.
Use system-wide settings when applications inherit operating-system proxy configuration.
Confirm OS-aware applications inherit the proxy setting.
If applications bypass OS settings, use application-specific configuration.
Use GPO, MDM, Jamf, Ansible, Puppet, or other managed rollout tooling.
Confirm the rollout tool applies settings only to the pilot ring.
If scope is too broad, roll back the profile or policy.
Configure Git, package managers, container runtimes, curl, wget, Outlook, Thunderbird, and other tools directly.
Confirm each application uses SafeSquid or has an approved exception.
If a tool still bypasses the proxy, configure its native proxy setting.
## Grant the matching Access restrictions right
Client routing only delivers traffic to SafeSquid. Whether that traffic is actually allowed through still depends on the Access restrictions entry that matches the client. Specifically, it depends on which rights that entry grants. Configuring the client correctly but leaving the matching right ungranted looks identical to a routing failure. The client reaches SafeSquid, and SafeSquid still blocks it.
| Delivery mode | How the client is configured | Right required |
| - | - | - |
| Explicit proxy | The browser or OS is given SafeSquid's address and port directly | Proxy requests |
| Transparent | Network-level redirection sends traffic to SafeSquid; the client has no proxy setting | Transparent proxying |
These two rights are independent: a client can be granted one and denied the other. Both are independent of CONNECT requests, which separately gates HTTPS tunnels regardless of which delivery mode got the traffic there.
Six rights exist on an Access restrictions entry, and none of them implies another:
* **Web interface** — permits requests to SafeSquid's own console. Block pages still display to a denied client rather than a broken connection.
* **Proxy requests** — permits explicit proxy requests.
* **HTTP requests** — permits plain HTTP traffic, independent of CONNECT requests.
* **Transparent proxying** — permits traffic that reached SafeSquid through network-level redirection.
* **CONNECT requests** — permits CONNECT tunnels (HTTPS and similar). A denied client fails HTTPS even when HTTP requests are allowed.
* **Allow bypassing** — permits a temporary continue after an Access Profiles Deny, using a bypass cookie. An Access Profiles entry marked "do not bypass" still blocks regardless of this right. This is narrower than it sounds, and distinct from the per-entry Bypass checkboxes that skip individual filtering modules.
Find SafeSquid's listen address and port in **Network settings → Listen**. Port 8080 is common, but it is set per deployment. Confirm it before assuming it.
An `ftp://` URL opened in a browser follows the same explicit-proxy or transparent path as HTTP. A standalone FTP client needs its own proxy configuration, if it supports one at all.
Configure the matching entry in [Access restrictions](/configuration/application_setup/access_restrictions) before troubleshooting client-side settings further.
## Start with a pilot
Configure one browser or host to use SafeSquid as its proxy.
Confirm the client has the approved SafeSquid IP, port, and bypass entries.
If the setting does not persist, check endpoint management policy and local browser overrides.
Browse to `http://example.com` and record whether the request is allowed or blocked as expected.
Confirm the request produces the expected browser result.
If browsing fails, confirm proxy reachability and the SafeSquid listener.
Browse to an internal site that should bypass the proxy, if a bypass is required.
Confirm the internal destination follows the approved bypass behavior.
If the internal app fails, add only an approved exact bypass entry.
Record whether traffic is allowed, blocked, or bypassed as expected, then compare the result with SafeSquid access logs.
Confirm `/var/log/safesquid/extended/extended.log` records proxied traffic with source, destination, timestamp, and action.
If no log appears, retest with `curl --proxy` and confirm the client is not bypassing SafeSquid.
## Verify traffic evidence
From a client:
```bash theme={null}
curl -I --proxy http://SAFESQUID-IP:8080 http://example.com
```
On the SafeSquid server:
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: the log records the pilot request with source, destination, timestamp, and action. Each record is one line of tab-separated, quoted fields. Read `date_time`, `client_ip`, `username`, `method`, `url`, `status`, and `filtering_reason`.
The access log is the authoritative check, but it needs shell access to the SafeSquid host. For a pilot user, or an endpoint you cannot log into, check the egress address from the browser instead.
Visit an address-reflection service such as `whatismyip.com` from the configured client.
Expected result: the address shown is the SafeSquid host's WAN address, not the client's own public address. If the client's own address appears, traffic is bypassing the proxy regardless of what the settings screen says.
Pair this with the internal-bypass test: an internal destination should load and should *not* appear in the SafeSquid log.
Method choice tracks fleet size more than anything else:
| Fleet | Method |
| - | - |
| One browser or host, first validation | Explicit proxy |
| A single user across several browsers | PAC file |
| One machine, all applications | System-wide proxy |
| Tens to thousands of endpoints | Enterprise deployment via GPO or MDM |
| Specific tools only, such as a container runtime | Application-specific configuration |
For production, the usual path is explicit proxy to prove the route, then enterprise deployment to enforce it.
## Prevent bypass
After the pilot passes, restrict direct internet egress where the network design allows it. A browser proxy setting alone is not a control if endpoints can still reach the internet directly.
## Capture onboarding evidence
Store:
* Pilot client and user.
* Proxy method and settings.
* Access-log sample.
* Internal bypass test result.
* Rollback command or management profile.
* Exception owner.
## Troubleshoot client routing
| Symptom | Likely cause | Fix |
| - | - | - |
| Client cannot reach proxy | Firewall, route, or wrong proxy IP | Test network reachability and confirm proxy listener |
| No access log appears | Client bypasses SafeSquid | Recheck proxy setting and retest with `curl --proxy` |
| Internal apps fail | Missing bypass or routing exception | Add an approved exact bypass entry |
| HTTPS warning appears | Root CA trust is missing | Complete Root CA deployment before testing HTTPS inspection |
\| Access-denied entry in logs | The matching Access restrictions entry lacks the right for this request type | Confirm Proxy requests, HTTP requests, CONNECT requests, or Transparent proxying is granted on the matching entry |
## Next steps
* [Explicit Proxy Configuration](/getting_started/client_configuration/explicit_proxy) - configure the first browser.
* [PAC File Configuration](/getting_started/client_configuration/pac_file) - move to controlled browser routing.
* [Enterprise Deployment](/getting_started/client_configuration/enterprise_deployment) - scale to managed endpoints.
# Enterprise Deployment
Source: https://docs.safesquid.com/getting_started/client_configuration/enterprise_deployment
Roll out SafeSquid proxy settings through central endpoint management with staged validation, rollback, and audit evidence.
# Roll Out Proxy Settings Safely
Enterprise proxy deployment turns a working pilot into enforceable web security. The risk is blast radius. A bad GPO, MDM profile, PAC URL, or configuration-management task can break web access across an entire business unit. Deploy in stages, prove traffic evidence, and keep rollback ready before expanding scope.
## Use this method when
Use enterprise deployment when:
* Explicit proxy or PAC pilot has passed.
* Endpoint management can enforce settings.
* The organization needs consistent routing and bypass control.
* Rollback can be applied quickly to the same scope.
Do not deploy to all users before testing a small representative pilot group.
## Validate prerequisites
Confirm:
* Proxy method and settings are approved.
* PAC URL or proxy IP/port is stable.
* Internal bypass list is reviewed.
* Pilot group, expansion rings, and rollback owner are named.
* Helpdesk and operations teams know expected symptoms and rollback steps.
## Choose the rollout method
Use for domain-joined Windows endpoints. Evidence is linked GPO scope, resultant settings, and pilot access logs.
Confirm GPO scope and resultant settings match the pilot ring.
If settings do not apply, inspect OU link, security filtering, and replication.
Use for macOS, Windows, and mobile fleets. Evidence is profile assignment, compliance state, and test traffic.
Confirm profile assignment and compliance state match the approved device group.
If devices miss the profile, verify enrollment, assignment filters, and sync state.
Use for Linux and mixed fleets. Evidence is job output, managed file state, and SafeSquid log entries.
Confirm job output shows the managed proxy file or setting was applied.
If drift remains, rerun the job and inspect local configuration precedence.
Use when only managed browsers need PAC or proxy enforcement. Evidence is policy result pages and controlled tests.
Confirm browser policy pages show the approved proxy or PAC setting.
If browser policy is ignored, check local overrides and policy precedence.
| Estate | Tool | Why |
| - | - | - |
| All Windows, domain-joined | Group Policy | Built into Active Directory; nothing extra to deploy |
| Mixed Windows and macOS, Entra ID | Microsoft Intune | One console for both platforms |
| macOS only | Jamf Pro or Intune | MDM designed for Apple devices |
| Linux servers and workstations | Ansible or Puppet | Standard configuration management |
| Mixed Windows and Linux, no directory | Ansible | Agentless, works over SSH |
| Existing SCCM deployment | SCCM | Reuse the infrastructure already in place |
## Stage the deployment
1. Deploy to IT pilot users.
2. Validate access logs, internal bypasses, and business apps.
3. Expand to one department or site.
4. Monitor helpdesk issues and SafeSquid logs.
5. Expand by rings only after evidence is clean.
6. Keep rollback active until the rollout is stable.
Rings only surface problems if each one runs long enough for users to hit their real workload. A ring that advances in a day catches outages but not the weekly finance app.
| Ring | Size | Dwell |
| - | - | - |
| Pilot | 5–10 users, IT and volunteers | 1 week |
| Early adopters | 50–100 users | 1 week |
| Department by department | One business unit at a time | 2–4 weeks total |
| Full deployment | Remainder | — |
Review SafeSquid logs and helpdesk tickets at each boundary before advancing.
**PAC hosting.** Host on redundant web servers rather than one host. Address it through internal DNS so the endpoint policy never has to change. Keep the file body in version control. Stage changes before production.
**Monitoring.** Use Group Policy Modeling in the Group Policy Management Console. It predicts which machines a change will affect before you link it. Run configuration-compliance reports on a schedule and alert on proxy configuration drift. Confirm through SafeSquid logs that managed endpoints are actually routing.
## Deploy with GPO
Use Group Policy to set proxy or PAC settings for a scoped pilot group.
Create a dedicated GPO for the pilot scope. Name it with the proxy method, site or group, and change record ID.
Confirm the GPO name and scope match the approved pilot ring.
If ownership is unclear, pause rollout until the change owner approves the scope.
Configure the explicit proxy address or PAC URL. Keep internal bypasses reviewed and exact.
Confirm the proxy address, PAC URL, and bypass list match the deployment record.
If users receive wrong settings, check policy precedence and inherited browser settings.
Link the GPO only to the pilot organizational unit or security-filtered group.
Confirm only pilot endpoints receive the setting.
If scope is too broad, unlink the GPO or tighten security filtering before retrying.
Run the checks below and confirm the pilot user appears in SafeSquid logs.
```powershell theme={null}
gpresult /r
netsh winhttp show proxy
```
Confirm the intended GPO applies and the proxy settings match approved values.
If the endpoint does not apply the GPO, refresh policy and inspect OU link, security filtering, and replication.
**Create the object** — open the Group Policy Management Console (`gpmc.msc`), right-click the target domain or OU. Select **Create a GPO in this domain, and Link it here**. Name it for the proxy method and change record, then right-click it and select **Edit**.
**Option A — deliver a PAC URL (preferred)**
Navigate to:
```text theme={null}
Computer Configuration → Policies → Administrative Templates →
Windows Components → Internet Explorer
```
1. Open **Use automatic configuration script**, enable it, and enter the PAC URL.
2. Open **Disable changing proxy settings** and enable it, so users cannot remove the configuration.
**Option B — set an explicit proxy**
Navigate to **Computer Configuration → Preferences → Windows Settings → Registry**, then create three registry items under `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings`:
| Value | Type | Data |
| - | - | - |
| `ProxyEnable` | `REG_DWORD` | `1` |
| `ProxyServer` | `REG_SZ` | `SAFESQUID-IP:8080` |
| `ProxyOverride` | `REG_SZ` | `*.local;*.internal.example.com;localhost;127.0.0.1` |
Set the action to **Update**, not **Create**. Create fails on reapply once the value exists, which produces confusing intermittent results across the fleet.
**Apply and verify**
Group Policy refreshes on its own within roughly 15 to 90 minutes. To test immediately on one endpoint:
```powershell theme={null}
gpupdate /force
gpresult /r
gpresult /h C:\gp-report.html
```
```powershell theme={null}
Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings"
```
Expected result: the SafeSquid GPO appears in the applied list, and `ProxyEnable` and `ProxyServer` hold the approved values.
**Roll back**
Delete the **link**, not the GPO itself. Removing the link stops enforcement while preserving the object and its settings for a corrected retry:
1. In the Group Policy Management Console, right-click the link and select **Delete link**.
2. Run `gpupdate /force` on affected endpoints, or wait for the normal refresh window.
## Deploy with MDM
Use MDM to deliver proxy or PAC profiles. Apply to a scoped pilot device group before broad assignment.
Create or update a device configuration profile that sets the approved proxy or PAC URL. Assign it to a pilot group, then verify device compliance and browser traffic.
Deliver a configuration profile for the approved network service or browser policy. Scope it to pilot Macs before production devices.
**Microsoft Intune**
1. Intune admin center **→ Devices → Configuration profiles**.
2. **Create profile**, platform **macOS**, profile type **Settings catalog**.
3. Search for **Proxy** and select **Network → Proxy → Web Proxy**.
4. Set the web proxy server and port, and the bypass list for hosts and domains.
5. Assign to the pilot macOS device group and create the profile.
Devices apply it at their next check-in, typically within about fifteen minutes.
**Jamf Pro**
1. **Computers → Configuration Profiles → New**.
2. Select **Network** and configure.
3. On the **Proxies** tab, enable **Web Proxy (HTTP)**, set the server and port, and set the bypass list.
4. Scope to the pilot computer group and save.
Devices apply the profile on their next check-in.
Verify on a managed macOS endpoint:
```bash theme={null}
profiles status -type enrollment
scutil --proxy
```
Expected result: the device is managed and the assigned profile is present.
Expected result for `scutil --proxy`: the reported proxy matches the approved SafeSquid listener.
## Deploy with configuration management
Use configuration management for Linux or mixed fleets. Keep settings explicit:
```yaml theme={null}
proxy:
http: "http://SAFESQUID-IP:8080"
https: "http://SAFESQUID-IP:8080"
bypass:
- "localhost"
- ".internal.example.com"
```
Capture the playbook run ID and managed host list.
```puppet theme={null}
file { '/etc/profile.d/proxy.sh':
ensure => file,
content => "export http_proxy=http://SAFESQUID-IP:8080\nexport https_proxy=http://SAFESQUID-IP:8080\n",
}
```
Capture the catalog report and changed resources.
For any tool, verify with a managed job output or local state check:
```bash theme={null}
env | grep -i proxy
```
Expected result: the endpoint receives the intended proxy values and generates SafeSquid access-log entries.
Covers the shell environment, both package managers, and a login-shell profile script, so terminal sessions and package operations route consistently.
```yaml theme={null}
---
- name: Deploy SafeSquid proxy configuration
hosts: all
become: yes
tasks:
- name: Configure system proxy in /etc/environment
lineinfile:
path: /etc/environment
line: "{{ item }}"
create: yes
loop:
- 'http_proxy="http://SAFESQUID-IP:8080"'
- 'https_proxy="http://SAFESQUID-IP:8080"'
- 'ftp_proxy="http://SAFESQUID-IP:8080"'
- 'no_proxy="localhost,127.0.0.1,.internal.example.com"'
- name: Configure APT proxy
copy:
dest: /etc/apt/apt.conf.d/95proxies
content: |
Acquire::http::Proxy "http://SAFESQUID-IP:8080";
Acquire::https::Proxy "http://SAFESQUID-IP:8080";
when: ansible_os_family == "Debian"
- name: Configure YUM proxy
lineinfile:
path: /etc/yum.conf
line: "proxy=http://SAFESQUID-IP:8080"
when: ansible_os_family == "RedHat"
- name: Create profile.d proxy script
copy:
dest: /etc/profile.d/proxy.sh
mode: '0644'
content: |
export http_proxy=http://SAFESQUID-IP:8080
export https_proxy=http://SAFESQUID-IP:8080
export no_proxy=localhost,127.0.0.1,.internal.example.com
```
Run against one host before the fleet:
```bash theme={null}
ansible-playbook -i inventory safesquid-proxy.yml --limit testhost
ansible-playbook -i inventory safesquid-proxy.yml
```
**Rollback.** Removing the playbook does not remove what it wrote. Keep a paired teardown and test it before the rollout, not during the incident:
```yaml theme={null}
---
- name: Remove SafeSquid proxy configuration
hosts: all
become: yes
tasks:
- name: Remove proxy lines from /etc/environment
lineinfile:
path: /etc/environment
regexp: '.*proxy.*'
state: absent
- name: Remove APT proxy config
file:
path: /etc/apt/apt.conf.d/95proxies
state: absent
- name: Remove YUM proxy setting
lineinfile:
path: /etc/yum.conf
regexp: '^proxy='
state: absent
- name: Remove profile.d proxy script
file:
path: /etc/profile.d/proxy.sh
state: absent
```
Capture the playbook run ID and the managed host list with the change record.
```puppet theme={null}
class safesquid_proxy (
String $proxy_server = 'SAFESQUID-IP:8080',
String $no_proxy = 'localhost,127.0.0.1,.internal.example.com',
) {
file { '/etc/profile.d/proxy.sh':
ensure => file,
mode => '0644',
content => epp('safesquid_proxy/proxy.sh.epp', {
'proxy_server' => $proxy_server,
'no_proxy' => $no_proxy,
}),
}
if $facts['os']['family'] == 'Debian' {
file { '/etc/apt/apt.conf.d/95proxies':
ensure => file,
content => "Acquire::http::Proxy \"http://${proxy_server}\";\nAcquire::https::Proxy \"http://${proxy_server}\";\n",
}
}
if $facts['os']['family'] == 'RedHat' {
ini_setting { 'yum_proxy':
path => '/etc/yum.conf',
section => 'main',
setting => 'proxy',
value => "http://${proxy_server}",
}
}
}
```
Template at `modules/safesquid_proxy/templates/proxy.sh.epp`:
```bash theme={null}
export http_proxy=http://<%= $proxy_server %>
export https_proxy=http://<%= $proxy_server %>
export no_proxy=<%= $no_proxy %>
```
Apply to scoped nodes in `site.pp`, keeping the match narrow enough to stay inside the current rollout ring:
```puppet theme={null}
node /^workstation.*\.example\.com$/ {
include safesquid_proxy
}
```
Capture the catalog report and the list of changed resources with the change record.
```yaml theme={null}
proxy:
http: "http://SAFESQUID-IP:8080"
https: "http://SAFESQUID-IP:8080"
bypass:
- "localhost"
- ".internal.example.com"
```
## Verify rollout evidence
On SafeSquid:
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: pilot users generate logs from intended source networks, and internal bypasses behave as designed.
## Roll back safely
Rollback must remove the same setting mechanism used for rollout:
* Disable or unlink the GPO.
* Remove the MDM profile.
* Revert the configuration-management state.
* Restore the previous PAC file version.
* Confirm clients stop receiving the failed setting.
## Monitor the rollout
Track SafeSquid access logs, helpdesk tickets, endpoint policy compliance, and business-app failures during every rollout ring. Pause expansion when logs show direct bypass, repeated authentication failures, or policy matches that block required business workflows.
Keep the PAC file URL stable and version the file contents. This lets endpoint policies stay unchanged while rollback restores a known-good PAC body.
## Troubleshoot rollout failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Users lose all web access | Proxy host, port, or PAC URL is wrong | Roll back the policy scope and fix the setting |
| Some users bypass SafeSquid | Scope or policy inheritance is incomplete | Check endpoint policy result and group assignment |
| Business app breaks | Missing PAC bypass or proxy incompatibility | Add a reviewed bypass or application-specific exception |
| Logs lack user context | Authentication is not configured or not matching | Verify authentication before expanding rollout |
| MDM profile reports an error state | Enrollment problem or a malformed profile | Check the MDM logs for the device, correct the profile, and re-send it |
| Ansible fails on a subset of hosts | SSH reachability or sudo rights | Test with `ansible all -m ping`, then confirm keys and privilege escalation on the failing hosts |
| Puppet nodes never receive the change | Agent stopped or cannot reach the master | Check `systemctl status puppet`, then run `puppet agent -t --verbose` to see the failure |
| PAC file does not load on managed clients | DNS or firewall blocks the hosting URL from the client network | Resolve and fetch the URL from an affected client: `nslookup` the host, then `curl` the file |
## Next steps
* [Application-Specific Configuration](/getting_started/client_configuration/application_specific_configuration) - handle tools that ignore managed proxy settings.
* [Configure Web Security Policies](/getting_started/configure_web_security_policies) - enforce controls after routing is stable.
* [Reporting Service](/architecture/interface/reporting_service) - preserve rollout and access evidence.
# Explicit Proxy Configuration
Source: https://docs.safesquid.com/getting_started/client_configuration/explicit_proxy
Use explicit proxy settings to validate SafeSquid traffic flow on one pilot browser or workstation before managed rollout.
# Validate One Client First
Explicit proxy configuration is the fastest way to prove that a client can reach SafeSquid. It also proves the client can send HTTP and HTTPS traffic through the proxy listener and generate access-log evidence. Use it for a pilot or troubleshooting session only. Do not rely on manual browser settings for production-wide enforcement.
## Use this method when
Use explicit proxy when:
* You need a fast pilot before GPO, MDM, or PAC rollout.
* You are testing one browser or workstation.
* You are isolating routing, DNS, certificate, or policy behavior.
Do not use manual explicit proxy as the final enterprise control. Users can remove it unless endpoint policy prevents changes.
## Validate prerequisites
Confirm:
* SafeSquid is installed and activated.
* Proxy listener IP and port are known.
* Pilot client can reach the proxy network.
* Access-log review is available.
* Root CA trust is planned before HTTPS inspection tests.
## Configure a pilot browser
Open **Settings** > **Network & Internet** > **Proxy** and enable manual proxy. Set HTTP proxy to `SAFESQUID-IP`, and set the port to `8080` or the approved listener port. Add only approved internal bypass entries.
Use the desktop environment proxy settings for a browser pilot, or use a command-line test with `curl --proxy`. For production desktop rollout, prefer PAC, GPO-equivalent endpoint management, or configuration management instead of manual user settings.
Open **System Settings** > **Network** > selected interface > **Details** > **Proxies** and enable Web Proxy and Secure Web Proxy. Then enter `SAFESQUID-IP` and the approved listener port.
Use browser proxy settings only for a controlled pilot or troubleshooting session. Apply the same proxy for HTTP and HTTPS traffic, save the settings, and browse to `http://example.com`.
Firefox maintains its own proxy settings and ignores the operating system configuration by default. A pilot that only sets the OS proxy will show Chrome and Edge routing through SafeSquid while Firefox goes direct. The traffic that bypasses the proxy is the traffic you will not see in any log.
Configure it explicitly, on every platform:
1. Open the menu (☰) and select **Settings**.
2. Scroll to **Network Settings** and select **Settings**.
3. Choose **Manual proxy configuration**.
4. Set **HTTP Proxy** to `SAFESQUID-IP` and **Port** to `8080`, or the approved listener port.
5. Enable **Also use this proxy for HTTPS**.
6. Set **No Proxy for** to the approved internal bypass entries, comma-separated.
7. Select **OK**.
For managed fleets, deliver these through Firefox enterprise policy rather than by hand — see [Enterprise Deployment](/getting_started/client_configuration/enterprise_deployment).
On older Windows builds, or where policy restricts the Settings app, the same WinINET configuration is reachable through Control Panel:
**Control Panel → Internet Options → Connections → LAN Settings**
Enter the proxy address and port there. The values apply to Chrome, Edge, and most Windows applications, because they read the same WinINET store.
**Bypass list syntax differs by platform.** Windows separates entries with semicolons (`;`); macOS and Linux use commas (`,`). Using the wrong separator makes the whole list parse as a single entry. Every internal destination then silently routes through the proxy instead of bypassing it.
Set HTTP proxy to `SAFESQUID-IP` and port `8080` or the approved listener port.
Confirm the client setting uses the approved proxy IP and listener port.
If the client cannot reach the proxy, confirm firewall policy, route, and listener state.
Apply the same proxy for HTTPS traffic before testing encrypted destinations.
Confirm HTTPS destinations use SafeSquid rather than direct internet access.
If HTTPS produces certificate warnings, deploy the SafeSquid Root CA before production testing.
Add only approved internal bypass entries and record the owner for each exception.
Confirm each bypass maps to an approved internal destination and owner.
If internal sites fail, add exact reviewed bypasses instead of broad wildcard entries.
Save the settings and browse to `http://example.com`.
Confirm the request returns an HTTP response through SafeSquid and appears in the access log.
If no log appears, retest with `curl --proxy http://SAFESQUID-IP:8080 http://example.com`.
For command-line validation, run:
```bash theme={null}
curl -I --proxy http://SAFESQUID-IP:8080 http://example.com
```
Expected result: the request returns an HTTP response through SafeSquid.
## Verify traffic evidence
On the SafeSquid server:
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: the access log shows the pilot client, destination, timestamp, and action. Each record is one line of tab-separated, quoted fields. Read `date_time`, `client_ip`, `username`, `method`, `url`, `status`, and `filtering_reason`.
For a negative check, remove or bypass the proxy setting only in the test window. Then confirm the request no longer appears in SafeSquid logs. Restore the proxy setting immediately after the test.
## Capture deployment evidence
Store:
* Pilot client hostname.
* Proxy IP and port.
* Browser or OS used.
* Internal bypass list.
* Access-log sample.
* Rollback steps.
## Troubleshoot pilot failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Browser cannot browse | Wrong proxy IP, port, or firewall rule | Confirm listener with `ss -lntp` and test reachability |
| Request does not appear in logs | Browser is not using the proxy | Reopen proxy settings and retest with `curl --proxy` |
| Internal site breaks | Missing bypass entry | Add exact internal host or suffix approved by the network owner |
| HTTPS warning appears | Root CA is not trusted | Deploy the SafeSquid Root CA before testing HTTPS inspection |
| Firefox ignores the proxy while other browsers use it | Firefox does not read the operating system proxy setting | Configure Firefox directly, or deliver the setting through Firefox enterprise policy |
| Sites load but noticeably slowly | Network latency to the proxy, or the proxy is loaded | Check round-trip time with `ping SAFESQUID-IP`, then check load on the SafeSquid host |
| Internal destinations still route through the proxy | Bypass-list separator is wrong for the platform | Use `;` on Windows and `,` on macOS and Linux |
Before assuming the proxy is at fault, confirm the client is actually applying the setting you think it is:
```powershell theme={null}
# Windows
netsh winhttp show proxy
```
```bash theme={null}
# macOS
scutil --proxy
```
```bash theme={null}
# Linux
echo $http_proxy
```
Expected result: the reported proxy matches the approved SafeSquid listener. A setting that was entered but not applied looks identical to a proxy that is not answering.
## Next steps
* [PAC File Configuration](/getting_started/client_configuration/pac_file) - automate browser routing.
* [System-Wide Proxy Settings](/getting_started/client_configuration/system_wide_proxy) - test host-level settings.
* [Enterprise Deployment](/getting_started/client_configuration/enterprise_deployment) - roll out through endpoint management.
# PAC File Configuration
Source: https://docs.safesquid.com/getting_started/client_configuration/pac_file
Deploy a Proxy Auto-Configuration file so managed browsers route approved web traffic through SafeSquid with controlled exceptions.
# Route Browsers With PAC
A Proxy Auto-Configuration (PAC) file gives managed browsers a repeatable routing decision. Use it when explicit proxy testing has passed. You then need controlled exceptions for internal sites, cloud services, or pilot groups.
## Use this method when
Use PAC when:
* Browser routing needs centralized logic.
* Internal destinations must bypass SafeSquid.
* Different networks need different proxy decisions.
* Rollout will later be managed through GPO, MDM, or browser policy.
Do not use complex PAC logic without change control. A small syntax error can send users direct to the internet or break business apps.
## Validate prerequisites
Confirm:
* Explicit proxy pilot passed.
* PAC hosting location is approved and highly available.
* Browsers can retrieve the PAC URL.
* Internal bypass list is reviewed.
* Rollback method is documented.
## Create a controlled PAC file
Use exact internal bypasses and a default SafeSquid proxy route:
```javascript theme={null}
function FindProxyForURL(url, host) {
if (isPlainHostName(host)) {
return "DIRECT";
}
if (dnsDomainIs(host, ".internal.example.com")) {
return "DIRECT";
}
return "PROXY SAFESQUID-IP:8080";
}
```
Replace `SAFESQUID-IP` and `.internal.example.com` with approved values. Avoid wildcarding public domains unless the exception has a business owner.
A single `PROXY` return means every browser loses web access when that node is unavailable. The return value accepts an ordered, semicolon-separated list. The browser tries each in turn and moves on when one does not answer.
```javascript theme={null}
return "PROXY SAFESQUID-A:8080; PROXY SAFESQUID-B:8080";
```
Order the list deliberately — it is the failover order, not a load-balancing hint.
Appending `DIRECT` as a final element makes browsers bypass the proxy entirely when no node answers:
```javascript theme={null}
return "PROXY SAFESQUID-A:8080; PROXY SAFESQUID-B:8080; DIRECT";
```
**A trailing `DIRECT` fails open.** If every SafeSquid node is unreachable, clients browse the internet unfiltered and unlogged. Nothing in the browser tells the user or the operator that enforcement stopped. Use it only where an availability requirement has been weighed against losing the control. The decision must also have a named owner. Omitting `DIRECT` fails closed instead: users lose web access, which is visible and reported immediately.
## Host the PAC file
Host the PAC file on an approved web location. Choose a method that operations can monitor and roll back.
Host `proxy.pac` on a highly available internal HTTP or HTTPS service. Use this when all managed endpoints can reach the internal network before browsing.
Host the PAC file on approved object storage or CDN when remote users need access before VPN or office connectivity.
Deliver the PAC URL through GPO, MDM, or browser policy. Keep the URL stable and version the file body.
Confirm clients can retrieve it:
```bash theme={null}
curl -I http://proxy-config.example.com/proxy.pac
```
Expected result: the server returns a successful response and the PAC file content is current.
**Serve the file with the correct MIME type.** Browsers expect `application/x-ns-proxy-autoconfig`. Served as `text/plain` or `text/html`, some browsers silently ignore the file and fall back to direct connections. This is the most common reason a correct PAC file appears to do nothing.
```apache theme={null}
# Apache
AddType application/x-ns-proxy-autoconfig .pac
```
```nginx theme={null}
# Nginx
types { application/x-ns-proxy-autoconfig pac; }
```
Verify the header before rollout:
```bash theme={null}
curl -I http://proxy-config.example.com/proxy.pac
```
Expected result: the response includes `Content-Type: application/x-ns-proxy-autoconfig`.
Hosting the file does nothing until clients are told where it is. Disable auto-detection at the same time, or WPAD discovery can override the URL you set.
**Windows — Chrome, Edge, and most applications**
1. **Settings → Network & Internet → Proxy**.
2. Turn **Automatically detect settings** off.
3. Turn **Use setup script** on.
4. Enter the PAC URL and select **Save**.
**Firefox — all platforms**
1. Menu (☰) **→ Settings → Network Settings → Settings**.
2. Select **Automatic proxy configuration URL**.
3. Enter the PAC URL and select **OK**.
Firefox keeps its own settings and will not pick up the Windows or macOS configuration.
**macOS — Safari, Chrome, and most applications**
1. **System Settings → Network →** select the active service **→ Details → Proxies**.
2. Enable **Automatic Proxy Configuration**.
3. Enter the PAC URL, then select **OK** and **Apply**.
**Linux desktops**
```bash theme={null}
# GNOME
gsettings set org.gnome.system.proxy mode 'auto'
gsettings set org.gnome.system.proxy autoconfig-url 'http://proxy-config.example.com/proxy.pac'
```
```bash theme={null}
# KDE
kwriteconfig5 --file kioslaverc --group 'Proxy Settings' \
--key 'Proxy Config Script' 'http://proxy-config.example.com/proxy.pac'
```
For anything beyond a pilot, deliver the URL through GPO, MDM, or browser policy. Do not set it per machine. See [Enterprise Deployment](/getting_started/client_configuration/enterprise_deployment).
## Deploy to pilot clients
1. Configure one pilot browser with the PAC URL.
2. Browse to an internet site that should route through SafeSquid.
3. Browse to an internal site that should bypass SafeSquid.
4. Inspect SafeSquid logs for the internet request.
5. Confirm the internal request does not create unwanted proxy traffic.
Use simple PAC functions first. Keep logic short enough for operations to review during incidents.
```javascript theme={null}
isPlainHostName(host)
dnsDomainIs(host, ".internal.example.com")
shExpMatch(host, "*.trusted.example.com")
isInNet(host, "10.0.0.0", "255.0.0.0")
```
Avoid broad `DIRECT` matches for public domains unless the exception has a business owner and review date.
Every function below is available inside `FindProxyForURL(url, host)`.
| Function | Purpose | Example |
| - | - | - |
| `isInNet(host, pattern, mask)` | Test whether the resolved IP falls in a subnet | `isInNet(host, "10.0.0.0", "255.0.0.0")` |
| `dnsDomainIs(host, domain)` | Test whether the host is in a domain | `dnsDomainIs(host, ".example.com")` |
| `shExpMatch(str, pattern)` | Shell-style wildcard match | `shExpMatch(url, "*.pdf")` |
| `localHostOrDomainIs(host, domain)` | Exact host match, or subdomain of it | `localHostOrDomainIs(host, "www.example.com")` |
| `isResolvable(host)` | Test whether the host resolves in DNS | `isResolvable(host)` |
| `isPlainHostName(host)` | True when the hostname contains no dots | `isPlainHostName(host)` |
| `dnsDomainLevels(host)` | Count the domain levels in a hostname | `dnsDomainLevels(host) > 0` |
| `weekdayRange(day1, day2)` | Match a day-of-week range | `weekdayRange("MON", "FRI")` |
| `timeRange(hour1, hour2)` | Match an hour-of-day range | `timeRange(9, 17)` |
`isInNet` and `isResolvable` force DNS lookups on every evaluation. Prefer `dnsDomainIs` and `shExpMatch` in hot paths, and keep DNS-dependent tests below the cheap string tests.
Time-based and day-based routing belongs in SafeSquid [Time Profiles](/use_cases/profiling_engine/time_profiles), not in the PAC file. A PAC rule is enforced by the client and can be bypassed; a SafeSquid profile cannot.
Test PAC retrieval and browser behavior before assigning the file broadly.
```bash theme={null}
curl -I http://proxy-config.example.com/proxy.pac
curl http://proxy-config.example.com/proxy.pac
```
Use browser proxy diagnostics such as `chrome://net-export` or Firefox `about:networking` only on approved pilot endpoints. Store the export with the change record if it proves a routing defect.
Test routing decisions offline, before any endpoint receives the file. `pactester` evaluates `FindProxyForURL` without a browser:
```bash theme={null}
sudo apt install pacparser
pactester -p proxy.pac -u http://example.com -h example.com
```
Expected result: the command prints the proxy string the client would use, such as `PROXY SAFESQUID-IP:8080` or `DIRECT`.
`pactester` ships in the `pacparser` package. On other distributions, search for `pacparser` or `pactester`.
Run one test per routing rule you added, including at least one destination that must go `DIRECT`. Save the output with the change record as proof the file was validated before rollout.
A PAC file is JavaScript, so a syntax error breaks proxy selection for every rule, not only the faulty one. The common causes are a missing semicolon, bracket, or quote and a misspelled function name. A file served with the wrong MIME type or from an unreachable URL also fails.
Web Proxy Auto-Discovery (WPAD) can reduce manual configuration, but it expands the trust boundary to DNS and DHCP discovery. Use WPAD only when DNS, DHCP, and endpoint teams approve ownership, spoofing controls, and rollback.
Required evidence includes the WPAD DNS or DHCP record, PAC file checksum, pilot endpoint result, and rollback record.
If WPAD is approved, three conditions must all hold or discovery silently fails:
1. A DNS A record for `wpad.` points at the host serving the file.
```text theme={null}
wpad.example.com. IN A PAC-SERVER-IP
```
2. The file is served as `wpad.dat`, not `proxy.pac`. Browsers request that exact name.
```text theme={null}
http://wpad.example.com/wpad.dat
```
3. Clients are set to **Automatically detect settings**.
Verify retrieval before enabling it broadly:
```bash theme={null}
curl -I http://wpad.example.com/wpad.dat
```
Expected result: the server returns a successful response for the `wpad.dat` path specifically.
## Verify routing decisions
On the SafeSquid server:
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: proxied internet requests appear; intended internal bypasses do not.
## Capture rollout evidence
Store:
* PAC file URL.
* PAC file version or checksum.
* Approved bypass entries.
* Pilot browser and user.
* Positive proxy log sample.
* Internal bypass test result.
* Rollback method.
## Troubleshoot PAC rollout
| Symptom | Likely cause | Fix |
| - | - | - |
| Browser ignores PAC | PAC URL is wrong or blocked | Confirm URL retrieval from the client network |
| All traffic goes direct | PAC logic returns `DIRECT` too broadly | Narrow bypass rules and retest |
| Internal sites route to SafeSquid | Missing internal bypass rule | Add exact internal suffixes and avoid broad public-domain bypasses |
| Changes do not apply | Browser cached the PAC file | Clear browser cache or change PAC version path according to endpoint policy |
| Remote users cannot retrieve PAC | Hosting path is internal-only | Use approved public hosting or VPN-reachable hosting for remote cohorts |
| Browser reports the PAC script failed | JavaScript syntax error in the file | Open the browser console and correct the reported error; validate offline with `pactester` before redeploying |
| Browser fetches the file but behaves as if there is none | Wrong MIME type on the response | Confirm `Content-Type: application/x-ns-proxy-autoconfig` with `curl -I` and fix the web server type mapping |
| Pages load slowly across the board | PAC logic performs DNS lookups on every evaluation | Move `isInNet` and `isResolvable` below the cheap string tests, or remove them |
## Next steps
* [Enterprise Deployment](/getting_started/client_configuration/enterprise_deployment) - deploy PAC through endpoint management.
* [System-Wide Proxy Settings](/getting_started/client_configuration/system_wide_proxy) - test host-level routing.
* [Application-Specific Configuration](/getting_started/client_configuration/application_specific_configuration) - handle tools that ignore browser PAC.
# System-Wide Proxy Settings
Source: https://docs.safesquid.com/getting_started/client_configuration/system_wide_proxy
Configure one managed operating system to send browser and supported application traffic through SafeSquid.
# Route One Host Through SafeSquid
System-wide proxy settings help validate how a workstation behaves when OS-aware applications use SafeSquid. This method is useful for controlled workstations, developer endpoints, and pilot hosts. It is not a substitute for enterprise policy enforcement unless settings are managed and protected.
## Use this method when
Use system-wide proxy when:
* You need more coverage than one browser setting.
* The host is managed by the organization.
* Applications honor operating system proxy settings.
* You can roll back quickly if business apps fail.
Do not assume all applications will use these settings. Some tools need application-specific proxy configuration.
## Validate prerequisites
Confirm:
* Explicit proxy pilot passed.
* Proxy IP, port, and bypass entries are approved.
* User or device is in a pilot group.
* Root CA rollout is ready before HTTPS inspection tests.
* Rollback commands are documented.
* WPAD auto-detection is disabled on the host, so discovery cannot override the manual setting.
## Configure by operating system
Use approved endpoint management where possible. For a controlled pilot, set WinHTTP proxy from an elevated shell:
```powershell theme={null}
netsh winhttp set proxy SAFESQUID-IP:8080 "localhost;*.internal.example.com"
```
Verify:
```powershell theme={null}
netsh winhttp show proxy
```
Expected result: the proxy and bypass list match the approved pilot values.
Set proxy variables for a pilot shell:
```bash theme={null}
export http_proxy=http://SAFESQUID-IP:8080
export https_proxy=http://SAFESQUID-IP:8080
export no_proxy=localhost,127.0.0.1,.internal.example.com
```
Persist settings only through the organization's approved profile, package-manager, or configuration-management process.
Verify:
```bash theme={null}
curl -I http://example.com
```
Expected result: the request succeeds and appears in SafeSquid access logs.
Use MDM for managed rollout. For a pilot, configure the active network service:
```bash theme={null}
networksetup -setwebproxy "Wi-Fi" SAFESQUID-IP 8080
networksetup -setsecurewebproxy "Wi-Fi" SAFESQUID-IP 8080
```
Verify:
```bash theme={null}
networksetup -getwebproxy "Wi-Fi"
```
Expected result: proxy settings match the approved SafeSquid listener.
**Windows keeps two separate proxy stores.** The `netsh winhttp` command above configures **WinHTTP**. Services and some background components use it. Browsers and most desktop applications read **WinINET**, configured through the Settings app, Internet Options, or the `HKCU` registry values below.
Setting one does not set the other. A host configured only through `netsh winhttp` shows a correct proxy in `netsh winhttp show proxy`. Chrome and Edge continue to browse direct. For host-wide coverage, set both.
**Settings app — Windows 10 and 11**
1. **Settings → Network & Internet → Proxy**.
2. Turn **Automatically detect settings** off, which disables WPAD.
3. Turn **Use a proxy server** on.
4. Enter the SafeSquid address and port `8080`, or the approved listener port.
5. Under **Edit**, add the approved bypass entries, separated with semicolons (`;`).
6. Select **Save**.
Confirm it applied by opening `edge://net-internals/#proxy` in Edge.
**Internet Options — all supported Windows versions**
Use this path when the Settings app is restricted by policy, or when per-protocol values are needed.
1. **Control Panel → Internet Options → Connections → LAN Settings**.
2. Clear **Automatically detect settings**.
3. Select **Use a proxy server for your LAN** and enter the address and port.
4. Select **Advanced** for separate HTTP, HTTPS (Secure), and FTP entries. Leave SOCKS blank unless it is specifically required.
5. Add the bypass list, semicolon-separated, then confirm each dialog.
**Registry values**
These are the underlying WinINET values, useful for automation or for confirming what a host actually has set. Under `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings`:
| Value | Type | Data |
| - | - | - |
| `ProxyEnable` | `REG_DWORD` | `1` |
| `ProxyServer` | `REG_SZ` | `SAFESQUID-IP:8080` |
| `ProxyOverride` | `REG_SZ` | `*.local;*.internal.example.com;localhost;127.0.0.1` |
Deploy these through Group Policy preferences rather than by hand where more than one machine is involved. See [Enterprise Deployment](/getting_started/client_configuration/enterprise_deployment).
Shell exports last only for the current session. Use one of these files when the pilot must survive a reboot. Record which one you changed so it can be reverted.
**All users on the host** — edit `/etc/environment`:
```text theme={null}
http_proxy="http://SAFESQUID-IP:8080"
https_proxy="http://SAFESQUID-IP:8080"
ftp_proxy="http://SAFESQUID-IP:8080"
no_proxy="localhost,127.0.0.1,.internal.example.com"
```
**One user only** — append the same `export` lines to `~/.profile` or `~/.bashrc`, then `source` the file.
Package managers do not read these variables. Configure them separately or updates fail while browsing works.
**APT (Debian, Ubuntu)** — create `/etc/apt/apt.conf.d/95proxies`:
```text theme={null}
Acquire::http::Proxy "http://SAFESQUID-IP:8080";
Acquire::https::Proxy "http://SAFESQUID-IP:8080";
```
**YUM or DNF (RHEL, CentOS, Fedora)** — add to `/etc/yum.conf`:
```ini theme={null}
proxy=http://SAFESQUID-IP:8080
```
Verify after any change:
```bash theme={null}
env | grep -i proxy
sudo apt update
```
Expected result: the variables show the approved proxy, and the package index refreshes through SafeSquid with matching access-log entries.
For applications that ignore both the environment and the package-manager configuration, see [Application-Specific Configuration](/getting_started/client_configuration/application_specific_configuration).
Use these paths when walking a pilot user through the change. Use them also when confirming what an endpoint is actually set to.
**GNOME (Ubuntu and derivatives)**
1. Open **Settings** and select **Network**.
2. Open **Network Proxy** and select **Manual**.
3. Set **HTTP Proxy**, **HTTPS Proxy**, and **FTP Proxy** to the SafeSquid address and port `8080`.
4. Set **Ignore Hosts** to `localhost,127.0.0.1,*.local,*.internal.example.com`.
5. Select **Apply system-wide**, then sign out and back in.
**macOS**
1. Open **System Settings** and select **Network**.
2. Select the active service, Wi-Fi or Ethernet, then **Details**.
3. Open **Proxies** and clear **Auto Proxy Discovery** to disable WPAD.
4. Enable **Web Proxy (HTTP)** and **Secure Web Proxy (HTTPS)**, and set both to the SafeSquid address and port `8080`.
5. Set **Bypass proxy settings for these Hosts & Domains** to a comma-separated list such as `*.local, localhost, 127.0.0.1, *.internal.example.com`.
6. Enable **Exclude simple hostnames**, then select **OK** and **Apply**.
On macOS, create separate network locations for office and remote use under **System Settings → Network → Location**. A user can then switch proxy settings without editing fields, which reduces mistyped exceptions during a pilot.
These paths configure the graphical session only. Terminal applications still need the environment variables above.
Use registry-based proxy settings only through approved endpoint management or an administrator-controlled pilot. Manual registry edits are hard to audit and easy to leave behind.
```powershell theme={null}
reg query "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings" /v ProxyServer
```
Expected result: the registry value matches the approved proxy or PAC deployment. Prefer GPO or MDM for production enforcement.
## Verify host coverage
On the SafeSquid server:
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: OS-aware applications from the pilot host generate log entries.
Also test one internal destination that should bypass SafeSquid.
Confirm the host is applying the setting, per platform:
```powershell theme={null}
# Windows: WinHTTP store, then the store browsers read
netsh winhttp show proxy
[System.Net.WebRequest]::DefaultWebProxy
```
```bash theme={null}
# macOS
scutil --proxy
```
```bash theme={null}
# Linux
env | grep -i proxy
```
Expected result: the reported values match the approved SafeSquid listener and bypass list.
Something else on the host is usually overriding the proxy. Check, in order:
* **Browser extensions** — proxy switchers and privacy extensions override browser-level settings without changing anything visible in the OS.
* **VPN clients** — split-tunnel and full-tunnel configurations reroute traffic before it reaches the proxy setting.
* **Security software** — endpoint agents that inspect traffic locally can intercept connections ahead of the configured proxy.
* **WPAD** — if auto-detection is still enabled, a discovered PAC file takes precedence over the manual entry.
Test the proxy path directly to separate a client problem from a proxy problem:
```bash theme={null}
curl -I --proxy http://SAFESQUID-IP:8080 http://example.com
```
Expected result: the request succeeds. If it does, the proxy is healthy and the fault is in the client configuration.
## Capture deployment evidence
Store:
* Hostname and operating system.
* Proxy settings and bypass list.
* Management tool or manual pilot method.
* Access-log sample.
* Internal bypass test result.
* Rollback command.
## Troubleshoot host routing
| Symptom | Likely cause | Fix |
| - | - | - |
| Browser works but CLI bypasses proxy | Tool ignores OS proxy or environment is missing | Configure application-specific proxy settings |
| Internal sites break | Missing bypass entry | Add approved internal suffixes |
| Settings disappear | User or policy overwrote manual settings | Move rollout to GPO, MDM, or configuration management |
| HTTPS warning appears | Root CA is missing | Install Root CA through approved trust path |
| Settings are lost after a reboot | Applied as a session export rather than persisted | Use `/etc/environment` on Linux, or the Settings app and registry on Windows, rather than shell exports |
| Proxy setting is silently replaced | WPAD auto-detection is still enabled and a discovered PAC file takes precedence | Disable **Automatically detect settings** on Windows, or **Auto Proxy Discovery** on macOS |
| Browsers use the proxy but Windows services do not, or the reverse | Only one of the WinHTTP and WinINET stores was configured | Set both; see the Windows accordion above |
## Next steps
* [Enterprise Deployment](/getting_started/client_configuration/enterprise_deployment) - move from host pilot to managed rollout.
* [Application-Specific Configuration](/getting_started/client_configuration/application_specific_configuration) - configure tools that bypass OS settings.
* [Configure Web Security Policies](/getting_started/configure_web_security_policies) - apply controls after routing is proven.
# Policy Enforcement
Source: https://docs.safesquid.com/getting_started/configure_web_security_policies
Production sequence for turning SafeSquid proxy traffic into inspected, attributed, logged, and auditable web security controls, with a verification step per control.
# Turn Proxy Traffic Into Enforced Controls
Routing traffic through SafeSquid proves reachability, but it does not finish the deployment. Production value starts when SafeSquid decrypts approved HTTPS sessions and attributes requests to users. It then applies policy, blocks unsafe activity, and records evidence for operations, audit, and incident response.
## Validate prerequisites
Before enabling baseline controls, confirm:
* SafeSquid is installed and activated.
* A pilot client generates access-log entries.
* Root CA rollout ownership is assigned.
* Authentication source and group mapping are known.
* Log retention or forwarding is approved.
* A rollback path exists for each policy stage.
## Apply controls in order
Use this sequence to reduce outage risk and preserve evidence quality.
| Step | Control | Why it comes here |
| - | - | - |
| 1 | SSL inspection readiness | HTTPS must be visible before content controls can inspect encrypted traffic |
| 2 | Authentication | User attribution improves policy scope and audit value |
| 3 | DNS security | Name-resolution controls reduce exposure before HTTP policy decisions |
| 4 | Access restriction | Category and application rules enforce acceptable use |
| 5 | Malware scanning | Downloads and content streams are inspected before delivery |
| 6 | DLP | Uploads and posts are inspected after identity and inspection are stable |
| 7 | Reporting | Logs and reports prove control effectiveness |
## Start with inspection
Deploy Root CA trust before enabling broad HTTPS inspection. Do not ask users to bypass certificate warnings; that normalizes man-in-the-middle risk and weakens audit defensibility.
Verification:
* A pilot HTTPS site loads without browser certificate warnings.
* SafeSquid logs the HTTPS transaction.
* Excluded destinations are documented with business justification.
## Add user context
Connect authentication before writing broad user or group policies. Use directory integration where possible so logs identify the user, group, source, destination, policy, and action.
Verification:
* A test user appears in the access log.
* Group-scoped policy applies only to the intended pilot group.
* Failed authentication has a clear user-facing and operator-facing signal.
## Enforce acceptable use
Start with pilot groups and high-confidence categories. Block only what the business has approved, and keep a documented exception path for business-critical sites.
Verification:
* A blocked category produces the expected block page.
* An allowed business site remains reachable.
* The access log records the matched policy and action.
## Scan content before delivery
Enable [malware scanning](/use_cases/malware_scanning/malware_scanners) and content controls after routing, activation, inspection, and identity are stable. This prevents noisy troubleshooting where certificate, routing, and scanning failures overlap.
Verification:
* A safe test download is allowed and logged.
* A controlled malware-test file or approved test pattern is blocked according to policy.
* Scan failures produce actionable logs.
## Control outbound data
Enable DLP only after HTTPS inspection and user attribution are validated. DLP without decrypted traffic and identity produces weak enforcement and weak evidence.
Verification:
* A test upload containing the approved test pattern is blocked.
* The log records the source user, destination, matched control, and action.
* Business-approved uploads still work.
## Prove the baseline
Store:
* Root CA rollout evidence.
* Authentication test result.
* Allowed and blocked URL category tests.
* Malware scanning test result.
* DLP test result.
* Access-log samples from `/var/log/safesquid/extended/extended.log`.
* Reporting Service or SIEM forwarding evidence.
* Rollback steps for every enabled control.
## Troubleshoot policy rollout
| Symptom | Likely cause | Fix |
| - | - | - |
| HTTPS sites show warnings | Root CA trust is missing | Deploy Root CA through GPO, MDM, or approved trust process before retesting |
| Policy does not match user | Authentication or group mapping is incomplete | Verify the user identity in access logs before changing policy |
| Block rule affects business apps | Scope is too broad or bypass is missing | Narrow the rule to target categories, users, or destinations and document exceptions |
| DLP does not trigger | HTTPS inspection is missing or test content does not match | Confirm decrypted traffic and use an approved test pattern |
| Reports are empty | Traffic bypasses SafeSquid or reporting is not connected | Verify access logs first, then reporting integration |
## Next steps
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) - deploy trusted HTTPS inspection.
* [Authentication](/use_cases/authentication/authentication) - add user and group attribution.
* [Reporting Service](/architecture/interface/reporting_service) - preserve operating and audit evidence.
# Cloud Deployment
Source: https://docs.safesquid.com/getting_started/install_safesquid/cloud_deployment
Deploy SafeSquid SWG in a cloud network with controlled ingress, resilient storage, and production evidence checks.
# Deploy SafeSquid in Cloud
Cloud deployment places SafeSquid near cloud workloads, remote users, or hybrid egress paths. The main risks are exposed proxy ports, undersized instances, weak storage planning, and missing high availability. Treat cloud deployment as a network security change, not just an instance launch.
## Avoid backhauling remote traffic
Routing remote and branch traffic back to an on-premises gateway adds a round trip to every request. This happens before the traffic reaches the internet. It consumes bandwidth twice through the gateway link. It also degrades the experience for exactly the users who are least able to report it well.
Placing the gateway in the cloud removes that detour:
* Remote workers reach the nearest instance rather than head office.
* Branch traffic consolidates at an edge device, such as an SD-WAN appliance, before reaching the gateway.
* Inspected traffic egresses to the internet directly from the cloud.
* Capacity scales with demand instead of being provisioned for peak.
* Cost shifts from capital purchase to consumption.
* No single site becomes the dependency for every user's internet access.
SafeSquid is cloud-agnostic. The same deployment model applies on AWS, Azure, GCP, DigitalOcean, or a private cloud, without vendor lock-in.
## Use this method when
Use cloud deployment when:
* Cloud workloads must egress through SafeSquid.
* Remote sites or users already route through a cloud network.
* The organization needs fast pilot capacity without hardware procurement.
* Security groups, routing, logging, and snapshots are centrally managed.
Do not use this path when the cloud network cannot restrict proxy access to approved sources.
## Validate prerequisites
Confirm:
* VPC or virtual network routing is approved.
* Security groups restrict proxy and management ports.
* Instance size matches the sizing plan.
* Persistent disk capacity supports logs and updates.
* DNS, NTP, activation, and update paths are reachable.
* Snapshot and rebuild procedures are documented.
## Choose a deployment pattern
Use a Cloud-IMG, marketplace, or prebuilt SafeSquid image only when the image source and release are approved. The checksum or publisher identity and update path must be approved too.
Record the image ID, region, launch date, SafeSquid version, disk mapping, and initial security group rules. After first boot, verify service state, listener state, DNS resolution, activation reachability, and log creation.
The prebuilt image is published at:
```text theme={null}
http://downloads.safesquid.com/appliance/cloud-img/safesquid-swg.img
```
Import it through the provider's custom-image path, then launch an instance from the imported image:
| Provider | Import path |
| - | - |
| AWS | Import as an AMI using VM Import/Export |
| Azure | Upload as a managed disk, then create an image from it |
| GCP | Create a custom image from the disk |
| DigitalOcean | Use the Custom Images feature |
The image ships with the account `administrator` and the password `safesquid`. Change it at first login with `passwd`, before the instance is reachable from any client network.
Use cloud-init when automated instance build is required. Review user data before launch and avoid embedding activation keys, administrator passwords, or certificate private keys in cloud-init text.
Keep cloud-init focused on baseline OS configuration, package source selection, network settings, log-forwarder bootstrap, and management hardening. Upload the `activation_key` through the approved SafeSquid activation workflow after the instance is reachable.
Retrieve the published cloud-init configuration:
```bash theme={null}
curl -O https://raw.githubusercontent.com/SafeSquid-Github/safesquid_cloud-init/main/safesquid_cloud-init.yaml
```
Review and adjust the network settings, hostname, and disk layout before use, then pass it as user data at launch:
| Provider | User-data field |
| - | - |
| AWS | User data, during EC2 launch |
| Azure | Custom data, during VM creation |
| GCP | Metadata, key `user-data` |
| DigitalOcean | User data section |
Follow provisioning from the instance:
```bash theme={null}
tail -f /var/log/cloud-init-output.log
```
Expected result: the log reaches completion without error. A cloud-init failure often leaves a reachable instance running no proxy at all. So check this before assuming the launch succeeded.
Use an existing cloud VM only when the operating system lifecycle is already owned. Confirm dependencies, hardening, backup, monitoring, and rollback before installing SafeSquid.
Existing VMs need extra review. Check for local services that can conflict with the proxy listener. Also check for disk layouts that cannot handle logs and security groups created for a different workload.
## Secure cloud networking
Before routing clients, enforce:
* No public `0.0.0.0/0` access to proxy or management ports.
* Management access limited to approved admin networks.
* Egress allowed only where needed for activation, updates, DNS, NTP, and business routing.
* Cloud flow logs or equivalent network evidence enabled where required.
* Route tables reviewed by the network owner.
**Topology.** Place SafeSquid in a private subnet with no direct inbound internet path. Give it outbound access through a NAT gateway. Front it with a load balancer when clients must reach it from outside the VPC. The proxy needs to reach the internet; the internet does not need to reach the proxy.
**Instance identity.** Do not embed long-lived cloud credentials on the instance. Use the platform's workload identity mechanism instead:
| Provider | Mechanism |
| - | - |
| AWS | IAM role attached to the EC2 instance |
| Azure | Managed Identity assigned to the VM |
| GCP | Service account with least-privilege scopes |
**Encryption at rest.** Enable volume encryption — EBS encryption, Azure Disk Encryption, or GCP persistent-disk encryption. SafeSquid volumes hold access logs that identify users and destinations. Treat them as sensitive data at rest, not as operational scratch.
**Transport for management.** Require TLS 1.2 or higher on the management interface.
**Logging.** Forward SafeSquid logs to the platform's logging service (CloudWatch, Azure Monitor, or Cloud Logging). Enable VPC or VNet flow logs for network-level visibility. Alert on proxy downtime and on sustained connection-drop rates.
Use load balancers only when the selected traffic model is compatible with proxy semantics, source attribution, health checks, and authentication. Record how clients reach the proxy, how failed nodes are removed, and how logs preserve user and source identity.
Auto-scaling is suitable only when configuration, activation context, certificate trust, logging, and policy state can be synchronized. They must be synchronized before a node receives traffic. Do not scale out stateless instances that cannot enforce the same policy and logging behavior as the active node.
Where a load balancer is used, configure the health check against the proxy listener on port `8080`. Use an HTTP `GET` to `/`. A check that only tests TCP reachability will keep sending traffic to an instance whose proxy has stopped answering.
Per-platform options are the Network or Application Load Balancer on AWS, Azure Load Balancer or Application Gateway. The TCP/UDP load balancer on GCP.
Production cloud deployments need a repeatable way to keep policy and operational state consistent:
* Use the same activation context where cluster or synchronized behavior requires it.
* Preserve configuration backups outside the instance disk.
* Define when policy is promoted from pilot to production nodes.
* Test restore into a replacement instance before relying on snapshots for DR.
* Confirm certificates, Root CA material, and logging configuration are included or deliberately excluded.
## Verify deployment
Check DNS and activation reachability:
```bash theme={null}
nslookup key.safesquid.com
```
Expected result: a `Non-authoritative answer` with `Name: key.safesquid.com` and an `Address` line. A `server can't find` or timeout means DNS resolution is broken.
Check service health:
```bash theme={null}
systemctl status safesquid --no-pager
```
Expected result: the first lines read `safesquid.service - SafeSquid Secure Web Gateway Proxy Server`, `Loaded: loaded` and `Active: active (running)`.
Check listener state:
```bash theme={null}
ss -lntp | grep ':8080'
```
Expected result: DNS resolves, SafeSquid runs, and the proxy listener is present only on approved interfaces.
When the instance was launched from a prebuilt image, confirm the dedicated volumes actually mounted:
```bash theme={null}
lsblk
```
Expected result: `/var/log/safesquid` and `/var/lib/safesquid` appear as mounted filesystems. If they are folded into the root volume instead, log growth fills the OS disk. The service then goes down with it.
## Plan availability
For production cloud egress, document:
* Availability zone placement.
* Health-check method.
* Failover route or load-balancer behavior.
* Same activation key usage across nodes where synchronization is required.
* Snapshot and restore procedure.
* Log forwarding destination.
## Capture deployment evidence
Store:
* Cloud account and region.
* Instance identifier, image source, and launch method.
* Security group and route table approvals.
* Service and listener checks.
* Activation key storage reference.
* Snapshot or rebuild plan.
* First pilot access-log entry.
## Troubleshoot cloud issues
| Symptom | Likely cause | Fix |
| - | - | - |
| Proxy is reachable publicly | Security group source is too broad | Restrict source CIDRs before continuing |
| Activation fails | Egress or DNS is blocked | Restore DNS and outbound subscription reachability |
| Clients cannot reach proxy | Route table or security group is wrong | Verify source network, route, and listener port |
| Logs fill disk | Disk size or retention is too small | Increase disk, adjust retention, or forward logs |
| Image import is rejected | Format or size is outside the provider's limits | Check the provider's import constraints and convert the image with `qemu-img` if a different format is required |
| Remote users see high latency | The instance is in a distant region | Deploy instances in regions close to the user population rather than routing everyone to one region |
| Auto-scaled instances fail the health check | New nodes serve traffic before policy and activation state sync | Ensure instances pull configuration on startup and only join the pool once the proxy answers |
| cloud-init instance is reachable but not proxying | Provisioning failed partway | Check `/var/log/cloud-init-output.log` for the failing step |
## Next steps
* [Access the Interface](/getting_started/access_the_interface) - verify management access.
* [Activate Your License](/getting_started/activate) - apply the activation key.
* [Enterprise Deployment](/getting_started/client_configuration/enterprise_deployment) - roll out client routing safely.
# Linux Server Install
Source: https://docs.safesquid.com/getting_started/install_safesquid/linux_server
Install SafeSquid SWG on an existing supported Linux server when the appliance path is not suitable.
# Install on a Managed Linux Host
Use the Linux server path only when the organization already owns the operating system lifecycle. It must also own the hardening baseline, monitoring, backup, and rollback. For new deployments, the SafeSquid Appliance Builder is the standard path. It provides a repeatable appliance build and supporting services.
## Use this method when
Use an existing Linux host when:
* The host is dedicated to SafeSquid or the security exception is approved.
* The OS version, packages, services, and hardening baseline are managed.
* Operations can install dependencies and troubleshoot service failures.
* Backup and rollback are already defined.
Do not use this method as a shortcut around appliance planning. A poorly managed host creates unstable inspection, missing logs, and difficult incident response.
## Validate prerequisites
Confirm:
* Root or approved sudo access is available.
* The host has static IP, DNS, gateway, and NTP configuration.
* Required outbound paths are reachable.
* Required packages and libraries can be installed.
* No local service conflicts with the approved SafeSquid proxy port.
* Activation key and rollback plan are available.
## Prepare the host
Record OS details:
```bash theme={null}
uname -a
cat /etc/os-release
```
Update package metadata according to the organization's change process:
```bash theme={null}
sudo apt update
```
Check disk and memory:
```bash theme={null}
df -h
free -m
```
Expected result: disk and memory match the sizing plan, with enough free space for logs, reports, updates, and support bundles.
Use the organization's approved package repositories and change window:
```bash theme={null}
sudo apt update
sudo apt install -y bind9 monit
```
Confirm that local hardening does not block SafeSquid, Monit, or BIND9 service management.
Use the organization's approved repository and package names for the target distribution:
```bash theme={null}
sudo dnf makecache
sudo dnf install -y bind monit
```
Confirm SELinux, firewalld, and local hardening rules before starting SafeSquid.
SafeSquid links against these libraries. Install them before running the installer, using the organization's approved repositories.
```bash theme={null}
sudo apt update
sudo apt install -y wget tar libssl-dev libpcre3 libpcre3-dev zlib1g-dev \
build-essential libc6 libgcc-s1 libstdc++6
```
```bash theme={null}
sudo yum install -y wget tar openssl-devel pcre-devel zlib-devel \
gcc gcc-c++ make glibc libgcc libstdc++
```
```bash theme={null}
sudo zypper install -y wget tar libopenssl-devel pcre-devel zlib-devel \
gcc gcc-c++ make glibc libgcc_s1 libstdc++6
```
Package names drift between releases. If one is not found, locate the equivalent for your distribution rather than skipping it. A missing library surfaces later as a service that installs cleanly and then refuses to start.
**Create the data directories** so the installer writes into a known layout. This also lets you mount dedicated volumes underneath them:
```bash theme={null}
sudo mkdir -p /var/log/safesquid /var/lib/safesquid /var/db/safesquid
```
**Open the proxy and management ports** using whichever firewall the host runs. Restrict the source scope in the same change, as described in [Deployment Checklist](/getting_started/install_safesquid/prerequisites):
```bash theme={null}
# firewalld (RHEL family)
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload
```
```bash theme={null}
# ufw (Debian, Ubuntu)
sudo ufw allow 8080/tcp
sudo ufw allow 8443/tcp
sudo ufw reload
```
```bash theme={null}
# iptables
sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8443 -j ACCEPT
sudo iptables-save
```
**Set SELinux to permissive for the setup window** on RHEL-family hosts. Then write a targeted policy once the deployment is stable:
```bash theme={null}
sudo setenforce 0
```
**Confirm time synchronisation.** SSL certificate validation and log correlation both depend on it:
```bash theme={null}
timedatectl status
```
Expected result: NTP synchronisation is active. If it is not, enable it before continuing:
```bash theme={null}
sudo systemctl enable --now systemd-timesyncd
```
## Install SafeSquid
Use the approved SafeSquid package or TAR source for the target release. Preserve the source URL, checksum if provided, and install date in the change record.
Retrieve and unpack the package:
```bash theme={null}
cd /usr/local/src
wget http://downloads.safesquid.net/appliance/binary/safesquid_latest.tar.gz
tar -zxvf safesquid_latest.tar.gz
```
Expected result: a `_mkappliance` directory is extracted, containing the installation scripts.
Run the installer from the directory you extracted into:
```bash theme={null}
sudo _mkappliance/installation/setup.sh
```
The installer checks dependencies, creates the `safesquid` system user and group, installs binaries under `/opt/safesquid/`. It also writes init and systemd service units and places default configuration under `/etc/safesquid/`.
Confirm every linked library resolved:
```bash theme={null}
ldd /opt/safesquid/bin/safesquid
```
Expected result: no line reads `not found`. Any that does names a package still to install — resolve it before starting the service. The failure otherwise appears at runtime as an immediate exit rather than a missing dependency.
If the installer itself fails, the usual causes are a missing library, running without `sudo`, or insufficient free space. Check the terminal output first, then `df -h`.
On a Debian-based system, `setup.sh` above carries out the whole post-install sequence on its own. In order, it:
* Suspends any existing process-monitoring service for the duration of the install.
* Detects the distribution family, to decide which remaining steps apply.
* Creates the service account SafeSquid runs as (**not** `root`).
* Removes leftovers from a previous installation on the same machine, if one existed.
* Installs the supporting packages SafeSquid depends on.
* Stops the service if it is already running (relevant on a re-install or upgrade).
* Configures a local DNS resolver tuned for appliance use, with IPv6 disabled. The zone data **DNS Blacklist** depends on is already in place.
* Copies the appliance file tree into place.
* Stands up a local DNS blacklist server bound only to loopback.
* Enables and starts the service.
**On a Red Hat-based system only the dependency-package installation step runs automatically.** The DNS resolver and DNS Blacklist setup is **not** configured for you. Do it separately. If DNS Blacklist does not appear to resolve anything, confirm the local resolver and blacklist server were actually set up. On a RHEL-family install this is a manual step, not an assumption.
Some features need no extra setup on this path for two reasons. That step installs the Kerberos and SASL components. That is why Kerberos/SSO and LDAP authentication need no extra package installation. The OCR components are installed there too. That is why DLP and Image analyzer can score text in images without extra setup. If Kerberos/SSO or LDAP authentication misbehaves, confirm you are on the fully-automated Debian-based path.
After extracting or installing the package, start SafeSquid:
```bash theme={null}
sudo systemctl start safesquid
```
If the platform uses the legacy service script, use the approved service command for that build:
```bash theme={null}
sudo /etc/init.d/safesquid start
```
## Verify service health
Check service state:
```bash theme={null}
systemctl status safesquid --no-pager
```
Expected result: the first lines read `safesquid.service - SafeSquid Secure Web Gateway Proxy Server`, `Loaded: loaded` and `Active: active (running)`.
Check listener state:
```bash theme={null}
ss -lntp | grep ':8080'
```
Expected result: a `LISTEN` line for `*:8080` (the proxy listener). No line means nothing is listening on 8080, so check the service state first.
Check access-log creation after a pilot request:
```bash theme={null}
tail -20 /var/log/safesquid/extended/extended.log
```
Expected result: SafeSquid runs, listens on the approved port, and records pilot traffic.
## Configure supporting services
Monit helps operators detect and restart failed services when it is part of the approved operations baseline. Confirm Monit is installed, enabled, and configured to monitor SafeSquid before relying on UI-triggered restarts or unattended recovery.
```bash theme={null}
systemctl status monit --no-pager
systemctl enable monit
systemctl restart monit
```
Expected result: Monit runs, starts after reboot, and its configuration is included in the deployment record.
BIND9 is commonly used as the local DNS service on SafeSquid appliance-style deployments. On managed Linux hosts, confirm whether local DNS is required or whether enterprise resolvers will be used directly.
```bash theme={null}
systemctl status bind9 --no-pager
named-checkconf
nslookup example.com 127.0.0.1
```
Expected result: BIND9 runs when required, configuration syntax passes, and local resolution succeeds. If the distribution uses a different service name, use the approved equivalent and record it.
## Harden before rollout
Before routing users:
* Restrict proxy access to approved client networks.
* Restrict management access to approved administrators.
* Enable log forwarding or retention.
* Confirm OS patching and backup ownership.
* Confirm Root CA rollout path.
* Document service restart and rollback steps.
Change the shipped administrator password before the host is reachable from any client network.
1. Open the management interface at `https://SERVER-IP:8443/` from an approved administrator network.
2. Go to **System** and open **User Management**.
3. Change the password on the `administrator` account.
Record that the change was made in the deployment evidence. A proxy carrying all corporate web traffic on a default credential is a direct compromise path.
Without rotation, SafeSquid logs grow until the volume fills and evidence is silently truncated. Create `/etc/logrotate.d/safesquid`:
```text theme={null}
/var/log/safesquid/*.log {
daily
rotate 30
compress
delaycompress
missingok
notifempty
sharedscripts
postrotate
/etc/init.d/safesquid reload > /dev/null
endscript
}
```
Adjust `rotate` to the retention target agreed in [Log-Retention Planning](/deployment/log_retention_planning), and use the service reload command appropriate to your build. Test the configuration before relying on it:
```bash theme={null}
sudo logrotate -d /etc/logrotate.d/safesquid
```
Expected result: the dry run reports the files it would rotate, with no configuration errors.
## Capture deployment evidence
Store:
* OS release and kernel details.
* Package or TAR source.
* Install date and operator.
* Service status output.
* Listener check.
* Pilot access-log sample.
* Firewall and management-access approval.
* Rollback or rebuild procedure.
## Troubleshoot installation
| Symptom | Likely cause | Fix |
| - | - | - |
| Package installation fails | Dependency or repository issue | Resolve package source and dependency errors before retrying |
| Service does not start | Port conflict or incomplete install | Check service logs and confirm no service owns the proxy port |
| Listener is missing | SafeSquid is stopped or bound differently | Verify service status and configured listener |
| No traffic is logged | Client bypasses proxy | Configure explicit proxy on a pilot client and retest |
| `ldd` reports a library as `not found` | A system dependency is missing | Install the package providing that library with the host's package manager, then recheck |
| Logs show permission denied, but file ownership looks correct | SELinux is enforcing and blocking SafeSquid | Set permissive mode for the setup window with `sudo setenforce 0`, then author a targeted policy |
## Next steps
* [Access the Interface](/getting_started/access_the_interface) - open `http://safesquid.cfg/` safely.
* [Activate Your License](/getting_started/activate) - upload the activation key and run smoke tests.
* [Connect Your Client](/getting_started/client_configuration/connect_your_client) - route pilot traffic.
# Install SafeSquid
Source: https://docs.safesquid.com/getting_started/install_safesquid/main
Installation path for deploying SafeSquid SWG on an appliance build, cloud instance, or existing Linux server.
# Install SafeSquid on the Right Platform
Installation quality determines whether SafeSquid can inspect traffic safely under production load. Pick the deployment method that matches your ownership model, then verify service health before routing users.
## Choose the install path
Build a new VM or hardware appliance from the standard ISO. Use this when the target disk can be dedicated to SafeSquid.
Confirm the VM or hardware can be rebuilt and the selected disk is disposable.
If existing data must be preserved, do not use Appliance Builder.
Place SafeSquid near cloud workloads, remote sites, or hybrid egress with restricted security groups and route-table ownership.
Confirm route tables and security groups restrict proxy access to approved clients.
If the proxy is public, tighten source networks before rollout.
Install on an existing supported Linux host when your team owns OS hardening, monitoring, dependency lifecycle, and rollback.
Confirm host lifecycle, packages, monitoring, and rollback are already owned.
If dependencies fail, correct the baseline or rebuild with Appliance Builder.
| Environment | Method | Why |
| - | - | - |
| New bare metal server | [SafeSquid Appliance Builder](/getting_started/install_safesquid/safesquid_appliance_builder) | Turnkey image with hardened OS and all dependencies |
| New VM on VMware, Hyper-V, or KVM | [SafeSquid Appliance Builder](/getting_started/install_safesquid/safesquid_appliance_builder) | Pre-configured networking, monitoring, and DNS |
| Private cloud on OpenStack or Proxmox | [SafeSquid Appliance Builder](/getting_started/install_safesquid/safesquid_appliance_builder) | Complete appliance for self-managed infrastructure |
| AWS, Azure, GCP, or DigitalOcean | [Cloud Deployment](/getting_started/install_safesquid/cloud_deployment) | Cloud-optimised images and cloud-init support |
| Existing Linux server | [Linux Server Install](/getting_started/install_safesquid/linux_server) | Minimal footprint; you keep ownership of the OS and services |
If the environment is not listed, choose by ownership rather than by platform. Use Appliance Builder when SafeSquid can own the whole host. Use Linux Server when something else already does.
## Installation sequence
Confirm host resources, static addressing, DNS, NTP, firewall rules, and activation key readiness in [Deployment Checklist](/getting_started/install_safesquid/prerequisites).
Confirm prerequisite evidence is attached to the deployment record.
If a prerequisite is missing, block installation until the owner corrects it.
Build the appliance, launch the cloud instance, or install on the managed Linux host according to the selected deployment model.
Confirm the installed host matches the approved deployment model and asset record.
If installation assumptions differ from the plan, stop and select the correct install path.
Confirm SafeSquid service health and the approved proxy listener before any managed rollout.
Confirm service status and listener output show SafeSquid is ready for activation.
If listener state is missing, inspect service logs and network binding configuration.
Send one browser or test client through SafeSquid and prove that traffic appears in `/var/log/safesquid/extended/extended.log`.
Confirm the access log records source, destination, timestamp, and action.
If no log appears, recheck proxy settings and bypass rules before adding users.
Open `http://safesquid.cfg/` through the proxy path, then complete [Activate Your License](/getting_started/activate).
Confirm the Configuration Portal loads and activation evidence is captured.
If the portal fails, confirm the pilot browser uses SafeSquid as proxy.
## Evidence to capture
Store:
* Install method and version source.
* Hostname, IP address, and deployment environment.
* CPU, RAM, disk, and NIC allocation.
* Service status output.
* Listener check for the approved proxy port.
* Pilot client test and first access-log entry.
* Rollback or rebuild procedure.
## Troubleshoot install choice
| Symptom | Likely cause | Fix |
| - | - | - |
| Installer path is disputed | Ownership model is unclear | Use Appliance Builder for new appliances; use Linux only when OS lifecycle is already owned |
| Cloud proxy is reachable from the internet | Security group is too broad | Restrict source networks before any client rollout |
| Existing Linux host fails dependencies | Baseline OS differs from supported assumptions | Fix dependencies or rebuild with Appliance Builder |
## Next steps
* [Deployment Checklist](/getting_started/install_safesquid/prerequisites) - confirm install readiness.
* [SafeSquid Appliance Builder](/getting_started/install_safesquid/safesquid_appliance_builder) - build a standard appliance.
* [Connect Your Client](/getting_started/client_configuration/connect_your_client) - route the first pilot client.
# Deployment Checklist
Source: https://docs.safesquid.com/getting_started/install_safesquid/prerequisites
Confirm host, network, trust, licensing, and evidence requirements are satisfied and owned before running any SafeSquid installer.
# Confirm Readiness Before Install
Most failed SafeSquid pilots are caused by missing prerequisites. These include wrong sizing, blocked proxy ports, and no DNS or NTP. They also include no activation key and no plan for Root CA deployment. Every one of them is cheaper to fix now than during the cutover window.
Work this checklist to completion before starting any installer.
Capture the current egress path before selecting a SafeSquid design:
* Internet circuits, firewalls, NAT devices, and cloud egress points.
* User networks, server networks, guest networks, VPN users, and remote branches.
* Existing proxy, PAC, WPAD, DNS, and browser-management policies.
* Authentication sources, group naming, privileged-user exceptions, and service accounts.
* Internal destinations that must bypass proxy inspection.
* Current log destinations, SIEM ownership, and incident-retention requirements.
Record these named values before installation starts. Each one blocks a specific install or activation step if it is missing:
**Portal and keys**
* Registered email on the Self-Service Portal.
* C-Code, required for license generation.
* Activation key, downloaded to the administrator workstation.
* Root CA certificate decision: self-signed or enterprise-issued, for HTTPS inspection.
**Network parameters**
* Proxy hostname or FQDN, for example `proxy.example.com`.
* Proxy IP address and CIDR, for example `10.200.5.100/24`.
* Default gateway address.
* Primary and secondary DNS servers.
**Directory integration**
* AD or LDAP server IP address or FQDN.
* Bind account in UPN format, with its password held under approved credential handling.
* Base DN, for example `dc=example,dc=com`.
* LDAP domain name.
## Validate platform readiness
Confirm:
* CPU, RAM, disk, and NIC allocation match the sizing plan from [Hardware Sizing](/deployment/hardware_sizing).
* Storage can handle access logs, reports, support bundles, and update files.
* The host has a stable hostname and static IP address.
* Administrative access is available through an approved management path.
* Backup, snapshot, or rebuild procedure is documented.
Do not start production installation on a temporary address or unmanaged host. That creates later certificate, logging, and routing rework.
## Validate network readiness
Confirm:
* DNS resolution works from the SafeSquid host network.
* NTP is reachable and synchronized.
* The approved proxy listener port is open only to intended client networks.
* Outbound access exists for activation, updates, category data, and subscription checks.
* The management path is restricted to approved administrators.
The specific ports, endpoints, and source scopes are listed in [Ports and Firewall Rules](/deployment/ports_and_firewall_rules). Agree them with the network owner before installation.
SELinux or AppArmor in enforcing mode can block proxy operations during initial setup. The failure presents as unexplained permission errors rather than a clear policy denial.
Set permissive mode for the setup window, or author a policy that covers SafeSquid before you start:
```bash theme={null}
getenforce
```
Expected result: the current mode is known and recorded before installation begins.
Once the deployment is operational, review the audit log. Write a targeted policy rather than leaving mandatory access control permanently disabled. Record which choice was made and who owns the follow-up. A "temporarily permissive" setting that is never revisited is a finding waiting to happen.
Agree these rules with the network owner before installation. Each has a named source scope; none should be opened to `0.0.0.0/0`.
**Inbound to the SafeSquid host**
| Port | Protocol | Purpose | Restrict to |
| - | - | - | - |
| `8080` | TCP | HTTP proxy listener | Approved client networks |
| `8443` | TCP | Management interface | Administrator workstations only |
| `53` | TCP/UDP | DNS, when integrated DNS security is used | Approved client networks |
**Outbound from the SafeSquid host**
| Port | Purpose |
| - | - |
| `80`, `443` | Web access on behalf of clients, plus update and subscription paths |
| `53` | Upstream DNS resolution |
[Ports and Firewall Rules](/deployment/ports_and_firewall_rules) and [Activate Your License](/getting_started/activate) list the licensing, update, and categorization hosts. Those hosts must be reachable on 80 and 443.
## Validate identity and trust
Confirm:
* Activation key is available from [Register and Get Your Key](/getting_started/register).
* Root CA rollout owner is assigned for HTTPS inspection.
* Authentication source is known if user-based policy will be enabled.
* Log-retention owner is assigned. See [Log-Retention Planning](/deployment/log_retention_planning).
* Change and rollback owners are named.
## Verify readiness
Run these checks before installation:
```bash theme={null}
ping -c 3 key.safesquid.com
nslookup key.safesquid.com
```
Expected result: DNS resolves and the host can reach the Self-Service Portal path required for activation-key workflows.
Also confirm:
* DNS and NTP are reachable from the SafeSquid host network.
* Firewall rules allow required outbound update and subscription paths.
* Proxy listener ports are approved.
* Root CA deployment owner is assigned.
* Rollback owners exist for routing, PAC, GPO, MDM, and firewall changes.
## Choose the install method
Use SafeSquid Appliance Builder for a new VM or hardware appliance with a dedicated target disk.
Confirm the target disk is dedicated and can be overwritten.
If any existing workload must remain, do not use Appliance Builder.
Use cloud deployment when security groups, route tables, snapshots, and egress paths are controlled.
Confirm route tables, security groups, snapshots, and egress paths have named owners.
If proxy exposure is broad, restrict source networks before rollout.
Use Linux Server Install only when OS lifecycle, dependencies, monitoring, and rollback are owned.
Confirm OS lifecycle, dependencies, monitoring, and rollback are documented.
If host dependencies are unmanaged, rebuild with Appliance Builder.
## Verify prerequisite evidence
Store:
* Host resource allocation.
* Static IP and DNS record.
* NTP source.
* Firewall approval.
* Activation key storage reference.
* Root CA rollout owner.
* Log retention target.
* Rollback plan.
## Troubleshoot readiness failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Host cannot resolve portal names | DNS is missing or blocked | Fix DNS before installation; every later step depends on it |
| Time is wrong | NTP is blocked or unset | Configure NTP before activation and logging tests |
| Proxy port is exposed too broadly | Firewall rule is unsafe | Restrict source networks; see [Ports and Firewall Rules](/deployment/ports_and_firewall_rules) |
| Activation key is missing | Registration is incomplete | Complete [Register and Get Your Key](/getting_started/register) before installing |
| A checklist item has no owner | Ownership was assumed, not assigned | Assign it now; unowned prerequisites are what stall the rollout later |
## Next steps
* [SafeSquid Appliance Builder](/getting_started/install_safesquid/safesquid_appliance_builder) - install the standard appliance.
* [Cloud Deployment](/getting_started/install_safesquid/cloud_deployment) - deploy in a cloud network.
* [Linux Server Install](/getting_started/install_safesquid/linux_server) - install on an existing Linux host.
# SafeSquid Appliance Builder
Source: https://docs.safesquid.com/getting_started/install_safesquid/safesquid_appliance_builder
Build a security-hardened Debian appliance with SafeSquid, Monit, and BIND9 preinstalled, using the SAB ISO on new bare metal or a virtual machine.
# Build the Standard Appliance
Installing SafeSquid by hand means hardening the OS and partitioning disks correctly. It also means resolving dependency libraries, configuring networking, and standing up Monit and BIND9. One mistake in partitioning or networking costs hours. It costs them again on the next node, because nothing about the build is repeatable.
SafeSquid Appliance Builder (SAB) is a security-hardened Debian ISO that does all of it from one boot. You answer a short sequence of prompts; a preseed script does the rest and reboots into a working appliance.
## Use this method when
Use SAB when:
* You are building a new dedicated SafeSquid appliance.
* The deployment can boot from an ISO.
* The organisation wants a repeatable baseline instead of adapting an existing server.
* You need a clean VM or hardware appliance for production, pilot, or DR testing.
Do not use SAB when the host must preserve an existing OS, application stack, or custom hardening image. The install erases the target disk. Use [Install on a Managed Linux Host](/getting_started/install_safesquid/linux_server) instead.
## Know what SAB automates
| SAB does | So you do not have to |
| - | - |
| Installs a security-hardened Debian base | Harden the OS by hand |
| Partitions the disk with separate volumes for `/`, `/var/log/safesquid`, and `/var/lib/safesquid` | Design a layout that keeps log writes off the root volume |
| Installs SafeSquid and every dependency | Resolve library versions per distribution |
| Pre-configures Monit for process supervision and BIND9 for local DNS | Stand up supporting services separately |
| Disables unnecessary services and configures the host firewall | Apply a hardening baseline manually |
| Sets SafeSquid to start on boot | Remember to enable the unit |
The separate log and cache volumes matter more than they look. A shared root volume that fills stops the appliance and truncates the audit trail at the same time.
## Validate prerequisites
Before booting the ISO, confirm:
* CPU, RAM, disk, and NIC allocation match the sizing plan in [Hardware Sizing](/deployment/hardware_sizing).
* The CPU exposes AES-NI. SSL inspection performance depends on it.
* The VM or hardware can boot from the SAB ISO.
* Static IP, gateway, DNS, and NTP values are approved and unique within the subnet.
* Outbound access is available for packages, updates, activation, and subscription checks. See [Ports and Firewall Rules](/deployment/ports_and_firewall_rules).
* The activation key is available for post-install activation. Obtain it from [Register Your Key](/getting_started/register).
* A rollback or rebuild plan exists for the VM or hardware.
Obtain the ISO from the SafeSquid appliance download path:
```text theme={null}
https://downloads.safesquid.com/appliance/safesquid.iso
```
Record the download date in the change record. Where the organisation's process requires it, record a checksum of the retrieved image too.
1. Write the ISO to USB or DVD. Rufus, Etcher, and `dd` all work for USB; ImgBurn for CD or DVD. Use whichever is approved for the administrator workstation.
2. Set the BIOS or UEFI boot order so the removable media is tried **before** the internal disk. Disable Secure Boot if the installer will not start.
3. Confirm the CPU exposes AES-NI before committing the hardware:
```bash theme={null}
lscpu | grep aes
```
Expected result: `aes` appears in the CPU flags. If it does not, HTTPS inspection will be substantially slower on this host. See the AES-NI requirement in [Hardware Sizing](/deployment/hardware_sizing).
SAB runs on both Type 1 and Type 2 hypervisors. On a Type 2 hypervisor such as VirtualBox or VMware Workstation, host-to-VM connectivity has to be established deliberately.
1. Create the VM on VMware, Hyper-V, KVM, or VirtualBox.
2. Attach the ISO as a virtual CD or DVD drive.
3. Choose the network mode:
| Mode | Behaviour | Use when |
| - | - | - |
| **Bridged adapter** | The VM gets its own address on the network, bypassing the host | Production and any deployment clients must reach |
| **NAT** | The VM sits behind the host, routing through the host's address | Isolated lab only |
Bridged is the recommended choice. NAT complicates client routing and certificate testing later.
4. Allocate CPU, RAM, and disk according to the approved sizing plan. Confirm the hypervisor actually reserves them rather than overcommitting.
**Destructive disk operation:** SAB erases and repartitions the selected disk. Back up any existing data first. Do not continue unless the VM or hardware is dedicated to SafeSquid and rollback means a rebuild, not data recovery.
Obtain the ISO from the SafeSquid appliance download path:
```text theme={null}
https://downloads.safesquid.com/appliance/safesquid.iso
```
Record the download date in the change record. Where the organization's process requires it, record a checksum of the retrieved image too.
1. Write the ISO to USB or DVD. Rufus, Etcher, and `dd` all work; use whichever is approved for the administrator workstation.
2. Set the BIOS or UEFI boot order so removable media is tried before the internal disk.
3. Confirm the CPU exposes AES-NI before committing the hardware. SSL inspection performance depends on it:
```bash theme={null}
lscpu | grep aes
```
Expected result: `aes` appears in the CPU flags. If it does not, HTTPS inspection will be substantially slower on this host.
1. Create the VM on VMware, Hyper-V, KVM, or VirtualBox.
2. Attach the ISO as a virtual CD or DVD drive.
3. Configure networking as **bridged** so the appliance holds a routable address on the client network. NAT works for an isolated lab but complicates client routing and certificate testing later.
4. Allocate CPU, RAM, and disk according to the approved sizing plan. Confirm the hypervisor actually reserves them rather than overcommitting.
**Default credentials:** the appliance ships with the account `administrator` and the password `safesquid`. Change the password at first login, before the host is reachable from any client network:
```bash theme={null}
passwd
```
Record that the change was made in the deployment evidence. Leaving the shipped password in place on a proxy that sees all corporate web traffic is a direct compromise path.
## Install the appliance
Attach the SAB ISO and boot the target host from it. The menu offers **Standard Installation**, **Expert Installation**, **Serial Console Installation (Standard)**, and **Serial Console Installation (Expert)**.
Confirm **Standard Installation** is selected. It is the recommended path and the one this page documents.
If the host is reachable only over a serial console, use the matching serial variant. The prompt sequence is the same.
![SafeSquid Appliance Builder boot menu showing Standard, Expert, and two Serial Console installation modes]()
Select **Yes** to configure networking automatically by DHCP, or **No** to assign a static address manually.
Confirm the choice matches the approved network plan. Production appliances use a static address.
If DHCP is selected for a production host, restart the installer. A proxy whose address moves breaks every client that points at it.
![Network autoconfiguration prompt asking whether to use DHCP]()
The language applies to both the installer and the installed system. The location sets the appliance **time zone**. The keyboard layout follows the keyboard's country of origin.
Confirm the time zone matches the one your log timestamps must correlate against, and the keyboard layout matches the hardware.
If the time zone is wrong, log entries will not line up with other systems during an incident. A mismatched keyboard layout causes input errors on non-standard keyboards, which is easy to misdiagnose while typing a password.
![Installer language selection screen]()
![Installer location selection screen, which sets the appliance time zone]()
![Installer keyboard layout configuration screen]()
Skip this step if DHCP was selected. Otherwise enter the address with its CIDR prefix appended, in the form `IP/subnet` — for example `192.168.1.50/24`.
Confirm the address falls inside the subnet range the network team defined, and is unique on that network.
If the address collides with an existing host, the conflict surfaces intermittently after rollout rather than at install time. Check the allocation record before continuing.
![Installer prompt for the static IP address with CIDR netmask]()
Enter the default gateway address. Where a router forwards traffic from the local network to other networks, that router's address is the gateway.
Confirm the gateway is reachable **from the address you just assigned**, not merely that it is correct in general.
If the gateway is unreachable, the installer fails later at mirror selection rather than here. So the real cause surfaces several screens away.
![Installer prompt for the default gateway address]()
Enter the DNS servers, space-separated. Provide a primary and a secondary for redundancy.
Confirm both resolve names correctly from the appliance network.
If only one resolver is given and it fails, categorization and update paths fail with it. SafeSquid cannot categorise a destination it cannot resolve.
![Installer prompt for name server addresses]()
Set a hostname that fits your naming convention, then the domain name.
Confirm the resulting fully qualified domain name is the one you intend. That both forward and reverse DNS entries exist for it.
If the FQDN is wrong, directory integration is the first thing to break — Active Directory integration depends on it. Changing the hostname later means revisiting certificate and logging references, so settle it now.
![Installer prompt for the appliance hostname]()
![Installer prompt for the domain name]()
Choose the Debian archive mirror geographically closest to the server, preferring one known for bandwidth and uptime. Leave the HTTP proxy field blank unless your network requires an upstream proxy; the expected form is `http://[[user][:pass]@]host[:port]/`.
Confirm the installer reaches the mirror and begins retrieving packages.
If mirror selection hangs, outbound HTTP and HTTPS are blocked or an upstream proxy is required. Fix reachability before retrying.
![Installer prompt to choose a Debian archive mirror by country]()
![Installer prompt for HTTP proxy information, blank for none]()
SAB auto-partitions the selected disk. Select the target drive for partitioning, typically `/dev/sda` or `/dev/nvme0n1`. Then select the same drive again for the GRUB bootloader.
Confirm the selected disk matches the allocation approved for SafeSquid, and that the GRUB target is the same internal disk.
If you are installing from a USB stick, unselect the USB drive at the partitioning prompt. This stops it being chosen by mistake.
![Disk partitioning prompt listing available disks]()
![GRUB bootloader installation prompt listing available disks]()
The preseed script partitions the disk, installs the Debian base with security updates. It then installs SafeSquid with Monit and BIND9, applies hardening, and sets SafeSquid to start on boot. The host reboots by itself when it finishes.
Confirm the progress screen advances and the host reboots without installer errors.
If installation stops, capture the console error, correct package or network reachability, and rebuild from a clean boot.
![Installer progress screen showing base system installation]()
Remove the ISO, let the appliance boot, and log in at the console with the default credentials `administrator` / `safesquid`. The appliance requires a password reset on first login: re-enter the current password, then set and confirm a new one.
Confirm the reset completes and the new password is stored under approved credential handling.
If the host returns to the installer, remove the ISO from virtual media and check the boot order.
![Console login prompt showing the default credentials and first-login password reset notice]()
**Do not defer the password reset.** The appliance ships with `administrator` / `safesquid`. Those credentials are printed on the login screen. Complete the reset before the host is reachable from any client network. Record that it was done in the deployment evidence. Leaving the shipped password in place on a proxy that sees all corporate web traffic is a direct compromise path.
**Confirm the GRUB target disk.** The bootloader prompt is separate from the partitioning prompt. It is easy to accept an external USB device instead of the internal disk. Installing GRUB to the wrong drive leaves the appliance unbootable once the media is removed.
Once network configuration completes, the installer offers to continue remotely. It displays the appliance address and a host-key fingerprint, and accepts a session as the user `installer`:
```bash theme={null}
ssh installer@SAFESQUID-SERVER-IP
```
Expected result: the installer resumes in the SSH session at the prompt the console had reached.
Compare the displayed SHA256 fingerprint before accepting the host key. This is useful for a headless server or a remote data centre. Treat it as a management-network action and connect from an approved administrator workstation, not from a general user network.
![Installer notice offering to continue the installation remotely over SSH]()
The installer runs on a virtual console. Switch between consoles to see what it is actually doing, which matters when the main screen appears stuck.
| Keys | Console |
| - | - |
| **ALT + F1** | Main installation interface, the default view |
| **ALT + F2** | Live installation log, real-time progress and errors |
| **ALT + F3** | Shell prompt for troubleshooting |
| **ALT + F4** | System messages |
Switch to the live log (**ALT + F2**) when installation appears stuck, network configuration fails, or partitioning errors appear. It distinguishes a slow step from a failed one.
From the shell (**ALT + F3**):
```bash theme={null}
tail -f /var/log/syslog
ping -c 3 8.8.8.8
lsblk
```
Expected result: the log advances, outbound connectivity succeeds, and the intended target disk is present and the size you expect.
## Verify installation
After reboot, run these checks from the appliance console or over SSH.
Confirm the service is running:
```bash theme={null}
systemctl status safesquid --no-pager
```
Expected result: `Active: active (running)` with no recent startup errors.
Confirm the proxy listener is bound:
```bash theme={null}
ss -lntp | grep ':8080'
```
Expected result: SafeSquid is listening on `0.0.0.0:8080`.
Confirm the management interface answers, from an approved administrator network:
```text theme={null}
https://SAFESQUID-SERVER-IP:8443/
```
Expected result: the SafeSquid admin login loads. If it prompts for license activation, the installation succeeded and the appliance is ready for [Activate Your License](/getting_started/activate).
| Component | Location or detail |
| - | - |
| SafeSquid proxy | `/opt/safesquid/` — listens on port `8080` |
| Security, policy, and UI material | `/usr/local/safesquid/` |
| Monit | Process monitoring and automatic restart for SafeSquid |
| BIND9 | Local DNS resolver on port `53` |
| Logs | `/var/log/safesquid/` |
| Configuration Portal | `http://safesquid.cfg/` — an embedded interface reachable only through the proxy, and deliberately not resolved by SafeSquid's own DNS resolver |
| Direct management access | `https://SAFESQUID-SERVER-IP:8443/` — before a proxy is configured, or when the proxy path is unavailable |
Use the direct `:8443` path only from an approved administrator network. It bypasses the proxy path that every other client uses. So it changes the trust boundary and should not become the routine way in.
## Hand off to activation
The appliance is built but not yet enforcing. Complete these before treating it as a control:
1. Configure a browser to use the appliance as its proxy — see [Explicit Browser Proxy](/getting_started/client_configuration/explicit_proxy). The Configuration Portal is only reachable through the proxy path.
2. Activate the instance from the portal — see [Activate Your License](/getting_started/activate).
3. Set up HTTPS inspection and configure policy for your environment — see [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection).
4. Install the SafeSquid certificate in the clients' desktop trust store — see [Import Certificate](/use_cases/ssl_inspection/import_certificate_chrome_ie).
5. Convert the appliance to SSH key-based login and disable password authentication for administrative access.
## Capture appliance evidence
Store these artifacts with the deployment record:
* Appliance hostname, FQDN, and IP address.
* VM or hardware asset identifier.
* ISO source, download date, and checksum where the process requires it.
* Disk and NIC allocation, and the disk selected for partitioning and GRUB.
* Service status and proxy listener output.
* Confirmation that the first-login password reset was completed, and by whom.
* First Configuration Portal access test.
* Activation key storage reference.
## Troubleshoot installation
| Symptom | Likely cause | Fix |
| - | - | - |
| Host does not boot from media | Boot order wrong, or Secure Boot enabled | Set removable media ahead of the internal disk and disable Secure Boot |
| Installation hangs at mirror selection | Outbound access blocked, an upstream proxy is required, or the gateway is unreachable from the assigned IP | Confirm outbound HTTP and HTTPS and gateway reachability; enter proxy details if the network requires one |
| `Failed to partition disk` | Disk in use, too small, or the wrong drive was selected | Confirm the target disk against the approved allocation; unselect the USB installation media and detach other drives |
| Appliance unbootable after removing media | GRUB was installed to the removable device | Reinstall, selecting the internal disk for the bootloader as well as for partitioning |
| Port `8080` not listening after reboot | SafeSquid failed to start | Run `systemctl status safesquid --no-pager` and check `/var/log/safesquid/native/safesquid.log` |
| Management interface unreachable on `:8443` | Host or network firewall blocks the port | Check host firewall rules with `iptables -L` and permit the port from the administrator network only |
| SSH connection refused after reboot | SSH is not running, or the address changed | Confirm the address with `ip addr`, then check `systemctl status ssh` |
| Directory integration fails after install | Hostname or domain does not produce the expected FQDN, or reverse DNS is missing | Correct the FQDN and confirm both forward and reverse DNS entries resolve |
| Log timestamps do not match other systems | Time zone set incorrectly at the location prompt | Correct the time zone before correlating evidence across systems |
## Next steps
* [Access the Interface](/getting_started/access_the_interface) - open the Configuration Portal safely.
* [Activate Your License](/getting_started/activate) - apply the activation key.
* [Connect Your Client](/getting_started/client_configuration/connect_your_client) - prove pilot traffic flow.
# Quickstart
Source: https://docs.safesquid.com/getting_started/quickstart
Start SafeSquid with a controlled pilot that restores legacy onboarding essentials and produces production-ready evidence.
# Start SafeSquid With a Controlled Pilot
## Confirm System Requisites
Before installation, confirm the platform choice and pilot capacity baseline:
* Preferred path: SafeSquid Appliance Builder for clean appliance-style deployment
* Alternate path: Linux package deployment when platform standards require it
* Minimum pilot hardware: `4` CPU cores, `4 GB` RAM, `160 GB` storage
* Recommended production starting point: `8` CPU cores and `8 GB` RAM
For full platform prerequisites, sizing decisions, and network dependencies, use [Deployment Checklist](/getting_started/install_safesquid/prerequisites) and [Deployment](/deployment/licensing_requirements).
## Prepare A Controlled Pilot
Before onboarding users, confirm:
* A deployment owner and change record are defined
* The `activation_key` storage location is approved and access-controlled
* Topology, sizing, firewall, DNS, NTP, and rollback decisions are documented
* A Root CA rollout path exists for managed endpoints
* Log retention and reporting ownership are assigned
Use [Deployment](/deployment/licensing_requirements) and [Deployment Checklist](/getting_started/install_safesquid/prerequisites) to complete these controls before installation.
Create an account in the [SafeSquid Self-Service Portal](/getting_started/register) and download the `activation_key`.
Confirm the key is stored in approved secure storage with controlled access.
If the file is missing or renamed, re-download it before activation.
Choose the approved install path in [Install SafeSquid](/getting_started/install_safesquid/main), then complete that platform guide.
Confirm SafeSquid service health and listener readiness before client routing.
If platform ownership or baseline requirements are unresolved, stop rollout and return to deployment planning.
Open the Configuration Portal from a proxied pilot browser at `http://safesquid.cfg/`.
If the proxied path is unavailable during controlled setup, use direct administrator access at `https://SAFESQUID-SERVER-IP:8443/` from an approved management network.
If neither path works, pause activation and resolve listener, proxy, or administrator network controls first.
Use [Connect Your Client](/getting_started/client_configuration/connect_your_client) to configure explicit proxy, PAC, system-wide proxy, or managed rollout.
Confirm one pilot request appears in `/var/log/safesquid/extended/extended.log`.
If traffic bypasses the proxy, verify proxy settings, PAC output, and bypass rules.
Complete [Activate Your License](/getting_started/activate), then run [Configure Web Security Policies](/getting_started/configure_web_security_policies).
Confirm a test request produces the expected allow, block, inspect, or log action.
If policy outcome differs from design, check rule order, identity attribution, and bypass entries.
## Prove Production Readiness
Before expanding beyond pilot users, collect and attach evidence to the deployment record:
* Activation proof: license details visible in the Configuration Portal
* Routing proof: first pilot transaction in `/var/log/safesquid/extended/extended.log`
* HTTPS trust proof: pilot endpoint trusts the SafeSquid Root CA and browses without trust warnings
* Policy proof: at least one expected allow or block event mapped to a known policy rule
* Audit proof: report or log export includes user, source, URL, action, and timestamp
Use [Production-Readiness Checklist](/getting_started/verify_your_setup) for the full production sign-off workflow.
## Immediate Next Controls
After pilot evidence is stable, apply these two controls first:
1. HTTPS inspection with trusted Root CA rollout for managed endpoints.
2. Identity integration with Active Directory or OpenLDAP for accountable policy enforcement.
Use [Configure Web Security Policies](/getting_started/configure_web_security_policies) to sequence these controls without breaking pilot stability.
## Troubleshoot First Pilot
If a pilot check fails, use the matching symptom below and capture corrected evidence before expanding rollout.
The pilot client is not routing through SafeSquid, so policy and audit controls are not being enforced.
**Likely cause:** Browser or host proxy settings, PAC output, or bypass rules are directing traffic around SafeSquid.
**Fix:**
1. Reapply the selected routing method using [Connect Your Client](/getting_started/client_configuration/connect_your_client).
2. Retest with a single pilot request.
3. Confirm the client is pointing to the approved proxy IP and port.
4. Remove unapproved bypass entries from pilot settings.
**Verify:** `/var/log/safesquid/extended/extended.log` records a new pilot entry with source, destination, action, and timestamp.
Operators cannot complete activation and policy setup when `http://safesquid.cfg/` is unreachable through the proxy path.
**Likely cause:** Pilot browser bypasses the proxy or SafeSquid listener access is blocked.
**Fix:**
1. Follow [Access the Interface](/getting_started/access_the_interface) from a proxied pilot browser.
2. Confirm the pilot browser proxy settings are active.
3. Validate SafeSquid listener state on the gateway.
4. Retry `http://safesquid.cfg/` from the same pilot path.
5. If needed, test direct management fallback from an approved administrator network at `https://SAFESQUID-SERVER-IP:8443/`.
**Verify:** `http://safesquid.cfg/` or approved direct fallback `https://SAFESQUID-SERVER-IP:8443/` allows Configuration Portal access.
HTTPS controls cannot be trusted in production when endpoints do not trust the SafeSquid Root CA. The same applies when inspection scope is too broad for the pilot stage.
**Likely cause:** Root CA deployment is incomplete, or inspection policy includes destinations not ready for decryption.
**Fix:**
1. Complete Root CA rollout for the pilot endpoint.
2. Keep inspection scope limited to approved pilot destinations.
3. Re-run the HTTPS pilot test from the managed client.
4. Review SSL policy scope in [Configure Web Security Policies](/getting_started/configure_web_security_policies).
**Verify:** HTTPS pilot sessions complete without trust warnings and logs show expected policy action.
Missing user, action, or timestamp details reduce incident response quality and delay audit acceptance.
**Likely cause:** Identity mapping, retention policy, or reporting export configuration is incomplete.
**Fix:**
1. Use [Production-Readiness Checklist](/getting_started/verify_your_setup) to confirm log and evidence requirements.
2. Enable identity-aware policy attribution for pilot users.
3. Configure log retention and export path before expansion.
4. Re-run one controlled pilot request and capture output.
**Verify:** Exported evidence includes user, source, URL, action, and timestamp for the new pilot request.
## Next steps
* [Deployment](/deployment/licensing_requirements) - finalize ownership, topology, and rollback decisions.
* [Install SafeSquid](/getting_started/install_safesquid/main) - deploy the approved platform path.
* [Production-Readiness Checklist](/getting_started/verify_your_setup) - run production-readiness checks before expansion.
# Register Your Key
Source: https://docs.safesquid.com/getting_started/register
Create a SafeSquid Self-Service Portal account, activate it by email, and download the activation_key file required for deployment.
# Register and Download the Activation Key
SafeSquid activation starts before installation. The Self-Service Portal issues the `activation_key` file that binds a SafeSquid deployment to licensing, subscription, update, and cloud-linked operational workflows. Without this key, operators cannot complete the activation checkpoint. That checkpoint comes before SSL inspection, URL filtering, malware scanning, DLP, or production policy rollout.
Treat the key as deployment evidence and operational secret material. Keep it under the same change-control and storage discipline used for firewall credentials, certificate private keys, and recovery runbooks.
**Activation key handling:** Do not paste activation keys into tickets, chats, screenshots, emails, or public documentation. If the key must be referenced in a change record, record the secure storage reference instead of the key contents.
## Control the activation path
The activation key establishes the trust path between the organization, the Self-Service Portal, and the SafeSquid instance. A controlled registration process reduces deployment delays, prevents key loss. It gives operations teams a clear audit trail for who created the account and where the key is stored.
Use one portal account ownership model for the deployment. Do not let individual engineers register independent keys for the same production environment. Make an exception only when the change record explicitly requires separate test, staging, or production activation contexts.
## Validate prerequisites
Before registering, confirm:
* The deployment owner has an approved business email address.
* The organization has assigned a team or role to own the Self-Service Portal account.
* The activation key will be stored in an approved secret vault or deployment-evidence repository.
* The deployment record has a target instance, cluster, or environment name.
* The operator can receive external email from SafeSquid.
* The SafeSquid instance will later have outbound access for license and subscription validation.
Beyond traceability, register from a corporate email domain, not a personal one such as Gmail, Yahoo, or personal Outlook. A corporate domain enables enterprise account handling on the portal:
* Priority support during a proof of concept.
* The ability to invite team members to the same account.
* Extended trial options.
An evaluation registered under a personal address cannot be transferred cleanly to the organization later. Decide the owning identity before the first registration rather than after.
## Create the portal account
Open the [SafeSquid Self-Service Portal](https://key.safesquid.com) from an approved administrator workstation.
Confirm the portal registration form loads over HTTPS.
If the page does not load, verify DNS, outbound HTTPS access, and the administrator workstation network path.
![SafeSquid Self-Service Portal registration form with email, name, captcha, and Sign up fields]()
Enter the approved email address, first name, last name, and captcha, then click **Sign up**.
Confirm the portal accepts the registration request and prompts the operator to check email.
If submission fails, recheck the email address, captcha, required fields, and browser session state.
![SafeSquid Self-Service Portal message asking the user to check email to activate the account]()
Add the registration request to the deployment record so the account owner and target environment are traceable.
Confirm the deployment record includes the registered email address, operator, date, and target environment.
If ownership is unclear, pause activation until the account owner and storage process are approved.
## Activate the account
Open the activation email sent to the registered address and click **Click here to activate your account**.
Confirm the activation page opens for the registered account.
If the email does not arrive, check spam, quarantine, and the registered address before retrying registration.
On the activation page, keep the suggested username or choose an approved username.
Confirm the username matches the deployment owner or approved operational mailbox.
If the username conflicts with an existing account, use the portal reset workflow or register with the approved shared account.
![SafeSquid account activation page with username, new password, and confirm password fields]()
Enter a new password and confirm it. The password must be at least 6 characters; use the organization's password and vaulting requirements when they are stricter.
Confirm the account activates and the portal accepts sign-in with the approved credentials.
If sign-in fails, confirm the account was activated and use the portal password reset workflow.
![SafeSquid account activation page with the Activate button selected]()
Return to `https://key.safesquid.com`, enter the username and password, and click **Sign in**.
![SafeSquid Self-Service Portal sign-in form after account activation]()
## Complete the profile
After first sign-in, complete the profile and contact details required to generate the activation key.
Review the first name and last name. Confirm the account represents the approved owner or shared operational mailbox.
Confirm the portal identity matches the deployment record owner.
If the owner is wrong, stop and register the correct approved account before key generation.
Select the correct subscription option. For first setup, select **Freemium** unless the organization has a commercial subscription entitlement.
Confirm the selected subscription matches the approved deployment context.
If entitlement is unclear, confirm subscription status with the account owner before saving the profile.
![SafeSquid Self-Service Portal profile form with user information and subscription selection]()
Enter the required contact details, including phone, address, state, city, and country.
Complete any remaining optional contact fields required by the organization's process, then click **Save Profile**.
Confirm the portal saves the profile and allows key generation.
If the key is not visible, complete missing profile fields and save the profile again.
![SafeSquid Self-Service Portal contact information form with Save Profile button]()
## Generate and download the key
After the profile is saved, the portal generates the activation key.
In the **New Activation Key generated** dialog, record the generation event in the deployment record, then click **Close**.
Confirm the deployment record includes the generation event and portal account owner.
If the dialog does not appear, confirm the profile was saved and the account subscription state is ready.
![SafeSquid Self-Service Portal dialog confirming a new activation key was generated]()
On the **Manage Key** tab, click **Download Key**.
Confirm the browser downloads an activation key file.
If download is blocked, allow the browser download from the portal or retry from an approved administrator workstation.
![SafeSquid Self-Service Portal Manage Key tab with Download Key button]()
Confirm the downloaded file is named exactly `activation_key`.
Confirm the file name is exactly `activation_key` with no extension or renamed copy suffix.
If the file was renamed, re-download the key and preserve the exact file name and contents.
Store the file in the approved secure location and record only the storage reference in deployment evidence.
Confirm the deployment record stores only the secure storage reference, not the key contents.
If the key was pasted into an unapproved channel, treat it as a secret-handling incident. Regenerate or replace it through the approved process.
Do not rename, edit, or reformat the `activation_key` file. SafeSquid expects the file name and contents to remain intact during license activation.
The same activation key can be used across multiple SafeSquid instances when the deployment requires synchronized instance behavior. An example is cluster members sharing the same activation context.
Two further properties affect how the key should be handled operationally:
* **The key does not expire.** It can activate a SafeSquid instance at any time, including a rebuild months later. Subscription entitlement is separate and does expire; see [Activate Your License](/getting_started/activate).
* **It can be downloaded again.** Sign in to the [Self-Service Portal](https://key.safesquid.com) to retrieve the key if the stored copy is lost. Re-downloading is preferable to circulating a copy through unapproved channels.
## Store registration evidence
Capture the following evidence with the deployment record:
* Portal account owner.
* Registered email address.
* Registration date.
* Subscription choice.
* Target deployment, instance, or cluster name.
* Secure storage reference for `activation_key`.
* Operator responsible for activation.
This evidence helps operations teams prove activation ownership, recover during rebuilds, and avoid uncontrolled keys during audits or incident response.
## Verify the key is ready
Before moving to installation or activation, confirm:
* The `activation_key` file was downloaded successfully.
* The file name is exactly `activation_key`.
* The key was stored in the approved secure location.
* The deployment record identifies the environment that will use the key.
* The activation operator can retrieve the file without copying it through unapproved channels.
When SafeSquid is installed, use [Activate Your License](/getting_started/activate) to upload the key and verify licensed state.
## Troubleshoot key and activation failures
| Symptom | Likely cause | Fix |
| - | - | - |
| Activation email does not arrive | Mail filtering, quarantine, or wrong address | Confirm the registered email address, check spam and quarantine, then retry registration if needed |
| Cannot sign in | Account was not activated or password is wrong | Open the activation email first; if already activated, use the portal password reset workflow |
| Activation key is not visible | Profile is incomplete or subscription/account state is not ready | Complete the profile, save it, and confirm the selected subscription option |
| Key upload later fails | File was renamed, edited, or downloaded incorrectly | Re-download the key and preserve the exact `activation_key` file name and contents |
| SafeSquid shows `Failed to set Subscription details` | The key file is missing, misnamed, or not loaded by the instance | On the SafeSquid server, verify `/usr/local/safesquid/security/activation_key`; re-upload the correct file if missing |
| Subscription server is unreachable | DNS, routing, or firewall controls block subscription validation | Test DNS and connectivity to `swgupdates2.safesquid.net`; allow required outbound access before retrying activation |
| Browser shows proxy refusing connections after upload | SafeSquid did not restart cleanly or Monit/service state is unhealthy | Verify service state, confirm Monit is configured if using UI restart, then restart SafeSquid from the server console if required |
For detailed post-install activation steps, service checks, listener checks, and log evidence, continue with [Activate Your License](/getting_started/activate).
## Next steps
* [Deployment](/deployment/licensing_requirements) - size and prepare the deployment.
* [Deployment Checklist](/getting_started/install_safesquid/prerequisites) - confirm host, network, and trust readiness.
* [Activate Your License](/getting_started/activate) - upload the key after SafeSquid is installed.
# Production-Readiness Checklist
Source: https://docs.safesquid.com/getting_started/verify_your_setup
Work through the full SafeSquid validation sequence and confirm every control is enforcing, not merely enabled, before routing production traffic.
# Confirm the Deployment Is Ready
SafeSquid is not production-ready until service state, proxy routing, license status, inspection, policy, and log evidence all agree. This page is the sequence that ties those checks together and the record you keep when they pass.
Each step links to the detailed check. Work them in order — a failure early on makes every later result unreliable.
## Validate prerequisites
Before running the sequence, confirm:
* SafeSquid is installed and activated. Use [Activate Your License](/getting_started/activate) if the license is not active.
* At least one pilot client uses SafeSquid as its proxy. Use [Connect Your Client](/getting_started/client_configuration/connect_your_client) for the routing path.
* You have shell access to the SafeSquid server.
* The test window is approved in the change record.
* Rollback exists for proxy settings, firewall rules, and client routing.
## Run the validation sequence
Confirm the proxy listener, process ID, service state, and local DNS resolution in [Service Health](/deployment/service_health).
Confirm the listener, process, and resolver checks all show SafeSquid is running.
If any check fails, inspect service logs before routing more users.
Load the [Configuration Portal](/architecture/interface/configuration_portal) from an approved management path, following [Access the Management Interface](/getting_started/access_the_interface).
Confirm the portal loads and the management path used is recorded.
If the portal does not load, verify browser proxy settings, listener state, and network ACLs.
Check product type, subscription state, and expiry, following [Activate Your License](/getting_started/activate).
Confirm product, subscription, and expiry details are populated.
If activation details are missing, re-upload the activation key and test subscription reachability.
Run the client-side checks in [Proxy Connectivity](/deployment/proxy_connectivity).
Confirm the request returns a response and a matching access-log entry appears.
If the request succeeds with no log entry, the client is bypassing SafeSquid. Treat that as a failure.
Read the certificate issuer as described in [HTTPS Inspection Validation](/deployment/https_inspection_validation).
Confirm the issuer is the SafeSquid CA for inspected destinations, and the original CA for excluded ones.
If HTTPS fails with trust warnings, finish Root CA deployment before production inspection.
Confirm logs, retention, forwarding, and reports in [Logging and Reporting](/deployment/logging_and_reporting).
Confirm the evidence path works end to end, not just that the log file exists.
If reports are empty while access logs are healthy, the reporting integration is the fault.
## Validate production controls
Before routing broad user traffic, confirm these controls are planned or already complete:
* SSL inspection is configured and the SafeSquid Root CA is deployed to managed endpoints.
* Authentication integrates with the approved identity source.
* Baseline access policies block malware, high-risk categories, and unauthorized applications.
* Reporting or log export captures access evidence for incident response.
* High availability is planned with [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) when uptime requirements demand it.
* Support and rollback owners are documented.
Use this once controls are configured, to confirm each one is actually enforcing rather than merely enabled.
**Authentication and identity**
* [ ] Users authenticate with domain credentials through the configured AD or LDAP integration.
* [ ] Usernames, not just IP addresses, appear in `/var/log/safesquid/extended/extended.log`.
* [ ] Where group policies are configured, different groups receive demonstrably different policy.
**Policy enforcement**
* [ ] A blocked category is genuinely blocked from a client.
* [ ] Sites are categorized as expected.
* [ ] Time-based policies activate and deactivate on schedule, where configured.
* [ ] HTTPS sites present the SafeSquid certificate once the CA is deployed.
**Security and content filtering**
* [ ] An EICAR test file download is blocked, confirming antivirus scanning is live.
* [ ] Keyword-based content blocking triggers, where enabled.
* [ ] Restricted file types are blocked on upload and download.
**Testing and documentation**
* [ ] Multiple client devices browse successfully through SafeSquid.
* [ ] A documented test case exists for each policy rule.
* [ ] Configuration is backed up, including `/usr/local/safesquid/config/`.
* [ ] A failover and restore procedure is written down and has been tested.
Use the EICAR test file rather than live malware. It is an industry-standard, inert string designed for exactly this check and is safe to transmit on a production network.
Operations and monitoring checks — current logs, update reachability, forwarding, and reports — are covered in [Logging and Reporting](/deployment/logging_and_reporting).
## Capture readiness evidence
Store these artifacts with the deployment record:
* Service, listener, and resolver output from [Service Health](/deployment/service_health).
* Screenshot or record showing active license state.
* HTTP and HTTPS access-log entries from `/var/log/safesquid/extended/extended.log`.
* Certificate issuer evidence for an inspected and an excluded destination.
* Pilot client proxy configuration.
* The completed integration checklist above, with the tester named.
* Change record with rollback owner.
This evidence supports SOC 2 change management, ISO 27001 operational control review, and NIST SP 800-53 audit traceability. Collect it at first deployment.
## Troubleshoot failed checks
| Symptom | Likely cause | Fix | Verify |
| - | - | - | - |
| A step fails before the sequence completes | An earlier control is not yet stable | Stop and fix in order; later results are unreliable until earlier steps pass | The failed step's own page reports a pass |
| License is inactive | Key was not uploaded or subscription path is blocked | Re-upload `activation_key`; allow HTTPS to `api.safesquid.net` | Activation details show active state |
| Controls are enabled but nothing is blocked | Policy scope does not match the pilot group | Confirm user attribution in the access log before changing policy | A blocked category returns the expected block page |
| Different clients get different results | Bypass or PAC exception matches inconsistently | Review bypass lists and PAC logic against the documented scope | All pilot clients produce matching log entries |
| Checklist passes but an auditor query cannot be answered | Evidence was not captured at the time of the test | Re-run the affected check and attach the output to the deployment record | The record contains the artifact for every step |
Escalate to the operations owner if service restart, DNS repair, or activation upload changes production traffic behavior.
## Verification is complete
The setup is ready for policy rollout when service state, interface access, and activation status all pass. Client routing, HTTPS inspection, and log evidence must pass too. Attach every artifact above to the deployment record.
## Next steps
* [Policy Enforcement](/getting_started/configure_web_security_policies) - enforce the baseline controls in order.
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) - enable HTTPS decryption after CA rollout.
* [Access Restriction](/use_cases/access_restriction/access_restriction) - enforce category and time-based policies.
# Welcome to SafeSquid
Source: https://docs.safesquid.com/getting_started/welcome
What SafeSquid is, why it exists, and how it converts network reachability into Layer 7 transaction-level authorization.
# Understand What SafeSquid Does and Why
## What is SafeSquid?
SafeSquid is a multi-threaded, SMP-aware HTTP/1.1 application proxy daemon built for Zero-Trust web-security enforcement.
Every HTTP exchange routed through SafeSquid crosses an inline Layer-7 policy boundary. The proxy accepts downstream connections, parses requests, establishes identity and application context, evaluates access and security policy. It then manages upstream connections, processes origin responses, and records enforcement decisions.
HTTPS follows the same control path. Policy can permit `CONNECT` tunnelling or invoke [TLS interception](/use_cases/ssl_inspection/ssl_inspection). Interception terminates downstream TLS, validates and establishes independent upstream TLS, then submits decrypted HTTP to the normal request-processing pipeline.
SafeSquid therefore controls web activity after network connectivity succeeds.
## Why SafeSquid exists
Enterprise activity now concentrates in browsers, SaaS platforms, cloud services, and HTTP APIs. Credentials, files, session tokens, business records, application commands, and administrative operations routinely traverse HTTPS.
Phishing, malware delivery, credential abuse, command-and-control traffic, application misuse, and data exfiltration exploit the same permitted channels.
Network firewalls authorize connections. URL filters classify destinations. Endpoint controls enforce host-local policy. TLS protects transport confidentiality. Authentication establishes identity.
None of those controls, independently, determines whether a specific request satisfies security policy. That applies to any HTTP request, upload, download, API call, or application action.
The resulting gap appears inside already permitted traffic. A trusted SaaS service can receive prohibited data. An authenticated account can perform prohibited operations. A valid TLS session can carry malware. A newly registered destination can evade reputation-based filtering.
SafeSquid places enforcement inside the HTTP processing path.
## From connection to decision
Processing starts at a configured listener.
[Access Restrictions](/use_cases/access_restriction/access_restriction) controls permission to use the proxy and can apply network-based access rules or authentication. Supported identity sources include [local credentials](/use_cases/authentication/basic), [PAM](/use_cases/authentication/pam), [LDAP directories](/use_cases/authentication/openldap), [Active Directory](/use_cases/authentication/active_directory), and [Kerberos](/use_cases/authentication/ad_sso_authentication).
Explicit HTTPS proxying begins with `CONNECT`. Policy can allow tunnelling or invoke [HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection). [Transparent HTTPS](/use_cases/scaling_and_high_availability/transparent_proxy) reaches an `SSL_TRANSPARENT` listener without an explicit proxy request. TLS interception creates separate downstream and upstream TLS sessions and exposes decrypted HTTP to Layer-7 processing.
HTTP parsing exposes method, request target, headers, [cookies](/use_cases/cookie_inspection/cookie_inspection), content metadata, and application characteristics. Content processing can identify [true MIME type](/use_cases/data_leakage_prevention/true_mime_fingerprints), decode supported transfer representations, inspect compressed payloads and archives. It can also [analyse text](/use_cases/data_leakage_prevention/text_analyser) and [images](/use_cases/data_leakage_prevention/image_analyser_ai), [scan malware](/use_cases/malware_scanning/malware_scanners), and examine uploaded or downloaded data.
Additional context can include user identity, group membership, source network, destination classification, [application signatures](/use_cases/profiling_engine/application_signatures), and [DNS intelligence](/use_cases/dns_security/dns_security). Further context includes TLS certificate state, content signatures, malware results, session state, cross-site activity, transfer properties, and behavioural indicators.
The [Polymath Profiling Engine](/use_cases/profiling_engine/profiling_engine) correlates applicable context before enforcement.
Policy can authenticate, permit, deny, [redirect](/use_cases/url_redirection/url_redirection), rate-limit, control cookies, [modify headers](/use_cases/header_rewrite/header_obfuscation), or [rewrite payloads](/use_cases/content_modifier/content_modifier). Policy can also scan malware, restrict uploads or downloads, [enforce data-loss controls](/use_cases/data_leakage_prevention/data_leakage_prevention), sanitize content, or invoke external [ICAP services](/use_cases/integrations/icap).
Origin responses cross response-side parsing, profiling, inspection, and enforcement before downstream delivery.
The resulting decision reflects the application exchange, not destination reputation alone.
## What SafeSquid can enforce
SafeSquid combines multiple security functions inside one HTTP policy boundary:
* [Access Control](/use_cases/access_restriction/access_restriction) — identity, group, source network, destination, time, application, transfer size, and request characteristics.
* [HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection) — `CONNECT` control, TLS interception, certificate validation, trust-anchor management, and inspection bypass policy.
* [Application Control](/use_cases/profiling_engine/application_signatures) — application identification, feature-level restrictions, [SafeSearch enforcement](/use_cases/access_restriction/safesearch), login controls, and social-media restrictions.
* [Malware Defense](/use_cases/malware_scanning/malware_scanners) — [SqScan](/use_cases/malware_scanning/sqscan) (built in), [ClamAV](/use_cases/malware_scanning/clamav_malware_scanning), [external parsers](/use_cases/data_leakage_prevention/adaptable_external_parser), [ICAP services](/use_cases/integrations/icap), signature analysis, and heuristic payload inspection.
* [Data Egress Control](/use_cases/data_leakage_prevention/data_leakage_prevention) — upload restrictions, content-aware DLP, MIME controls, transfer limits, and destination-specific policy.
* Deep Content Security — [MIME identification](/use_cases/data_leakage_prevention/true_mime_fingerprints), [text analysis](/use_cases/data_leakage_prevention/text_analyser), [image analysis](/use_cases/data_leakage_prevention/image_analyser_ai), archive inspection, [payload rewriting](/use_cases/content_modifier/content_modifier), CSP injection, and content sanitization.
* Traffic Control — [redirection](/use_cases/url_redirection/url_redirection), [cookie controls](/use_cases/cookie_inspection/cookie_inspection), [header modification](/use_cases/header_rewrite/header_obfuscation), [caching policy](/use_cases/performance_acceleration/caching), QoS, [bandwidth limits](/use_cases/performance_acceleration/manage_bandwidth), and concurrency controls.
Shared transaction context allows multiple controls to evaluate the same request or response without reducing enforcement to isolated network decisions.
## Zero Trust at Layer 7
Network reachability establishes connectivity, not application authorization.
Authentication establishes identity, not unrestricted access.
TLS establishes cryptographic protection, not acceptable application behaviour.
SafeSquid evaluates available identity, destination, application, protocol, content, and security context before permitting protected web activity.
A single SaaS destination can therefore receive different treatment for different users, operations, payloads, or session conditions. An approved user can access one application function while policy blocks another. An approved destination can receive ordinary business data while DLP blocks sensitive content.
SafeSquid converts network reachability into transaction-level authorization.
## Built as a security proxy
SafeSquid integrates inspection, correlation, enforcement, and logging inside a multi-threaded proxy process.
SMP-aware execution distributes concurrent processing across available CPU cores. Shared-memory structures expose common context to active security processors. In-memory DNS caching, upstream connection reuse, and TLS session reuse reduce avoidable proxy-path overhead. So do configurable object caching, streaming controls, and multi-queue NIC support.
Standard x86\_64 Linux infrastructure supports bare-metal, virtual-machine, cloud, and clustered deployments. Deployment modes include [explicit forward proxy](/use_cases/scaling_and_high_availability/forward_proxy), [transparent interception](/use_cases/scaling_and_high_availability/transparent_proxy), [reverse proxy](/use_cases/scaling_and_high_availability/reverse_proxy), [proxy chaining](/use_cases/scaling_and_high_availability/proxy_chain), and selected [TCP-proxy configurations](/use_cases/scaling_and_high_availability/tcp_proxy).
LDAP, Active Directory, PAM, Kerberos, ICAP, and SNMP support integration with existing infrastructure. So do [WCCP](/use_cases/scaling_and_high_availability/wccp), REST-based management, external parsers, SIEM pipelines, and [open-format logs](/use_cases/audit_and_forensics/security_logs).
[Cluster deployments](/use_cases/scaling_and_high_availability/proxy_clustering) support active-active or [active-standby](/use_cases/scaling_and_high_availability/master_slave) operation with synchronization of supported policy, categorization, and certificate state.
## Standards and interoperability
SafeSquid implements HTTP/1.1 in conformance with RFC 2616 and successor HTTP specifications while preserving RFC 2616 backward compatibility.
Supported protocol and integration capabilities include HTTP/HTTPS proxying, `CONNECT`, WebSocket traffic, IPv6 clients, active and passive FTP over HTTP/HTTPS. Further capabilities include SNMP, ICAP, WCCP, LDAP, Kerberos, PAM, and configurable TLS handling.
## Enforcement remains observable
Inline control requires explainable decisions.
SafeSquid records web activity, authentication events, filtering results, bypasses, and security processing. It also records DNS activity, connection failures, integration state, resource utilization, and proxy performance.
[Detailed Logs](/use_cases/audit_and_forensics/security_logs) expose request processing, matched filters, and enforcement reasons. Process logs expose daemon activity, module operation, security updates, external integrations, [cluster synchronization](/use_cases/customisation/configuration_sync), and diagnostic failures.
Open log formats support direct inspection with standard Linux tools and ingestion by monitoring, analytics, SIEM, and forensic systems.
Configuration changes can therefore be validated against observed traffic and recorded enforcement results.
## Featured use cases
* [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) - add clustering and failover once a single node is proven.
* [Audit & Forensics](/use_cases/audit_and_forensics/audit_forensics) - preserve evidence an auditor or incident responder can actually use.
* [Integrations](/use_cases/integrations/integrations) - connect SafeSquid to ICAP scanners, SIEM, and VPN so existing tooling sees proxy-layer evidence.
* [Customisation](/use_cases/customisation/customisation) - adapt templates, startup parameters, and configuration sync to your environment.
* [Performance Acceleration](/use_cases/performance_acceleration/performance_accelerators) - cache and tune so inspection doesn't cost you latency.
## Start with one controlled request
Prove the complete control path before enabling advanced security functions.
1. Start the SafeSquid daemon and verify the required listener.
2. Restrict proxy access to one controlled client or network.
3. Configure the client to route web traffic through SafeSquid.
4. Send one HTTP request.
5. Verify processing in [Detailed Logs](/use_cases/audit_and_forensics/security_logs).
6. Add one explicit [access rule](/use_cases/access_restriction/access_restriction).
7. Repeat the request.
8. Verify the matched filter and enforcement reason.
A successful test confirms traffic insertion, HTTP processing, policy enforcement, and decision visibility.
## Next steps
* [First Configuration](/configuration/start_here/first_configuration) - set up a safe minimal configuration on the appliance.
* [Security Logs](/use_cases/audit_and_forensics/security_logs) - read the evidence behind each allow or block decision.
* [Access Restriction](/use_cases/access_restriction/access_restriction) - add your first explicit access rule.
# Reporting
Source: https://docs.safesquid.com/reporting/reporting
Plan log retention, prove the audit trail exists, and find the right report or log for SafeSquid enforcement evidence.
# Turn Enforcement Into Evidence
SafeSquid blocks and allows traffic in real time. That decision only survives an audit or an incident review once it is logged and retained long enough to matter. It must also be reachable through the right report. A control you cannot evidence is a control nobody will credit.
Plan retention before deployment and prove the audit trail works once SafeSquid is live. Then find the right report or log for a specific question.
## Quickstart path
1. **[Log-Retention Planning](/deployment/log_retention_planning)** - set the retention target and size the log volume before installation. Retention is a sizing input, not an afterthought.
2. **[Logging and Reporting](/deployment/logging_and_reporting)** - confirm access logs are written, retained, and forwarded before calling the deployment audit-ready.
3. **[Tools and Reports](/configuration/start_here/tools_and_reports)** - locate Reports and Support utilities in the Web UI once the proxy is live.
4. **[Logging and troubleshooting](/configuration/start_here/logging)** - pick the right log family for a specific symptom, instead of searching blind.
## Next steps
* [Deployment](/deployment/licensing_requirements) - size and sequence the rest of the deployment around this evidence path.
* [Audit & Forensics](/use_cases/audit_and_forensics/audit_forensics) - go deeper on forensic workflows and security-log analysis.
* [Troubleshooting](/troubleshooting/troubleshooting) - diagnose a specific symptom instead of planning or validating reporting.
# Blank Report Page
Source: https://docs.safesquid.com/troubleshooting/blank_report_page
Diagnose and resolve SafeSquid blank report page incidents with causes, recovery actions, and audit evidence.
# Fix a Blank Report Page
Blank Report Page can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## ISSUE
Custom group name is taking time to update on Dashboard.
The dashboard information is obtained from SafeSquid databases. Some records on dashboard is obtained from Master table, whereas some other records are obtained from non-Master table.
Records that are coming from Master table are displayed quickly, whereas records from non-Master table waits for 1000 transactions.
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Reports](/architecture/policy_management_console/reports) to review policy evidence in reports.
# Connection Failure to Websites
Source: https://docs.safesquid.com/troubleshooting/connection_failure_on_websites
Diagnose and resolve SafeSquid connection failure to websites incidents with causes, recovery actions, and audit evidence.
# Fix Connection Failures to Websites
Connection Failure to Websites can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Connection failed to proxy or origin
When the user accesses the website, the browser displays "**Connection to 192.168.27.30:80 failed**". A user accesses [https://abc.safesquid.com/](https://abc.safesquid.com/) via proxy and logs in with a corporate email ID. The browser can then show "**Connection to abc.safesquid.com:443 failed**".
![Error showing "Connection to abc.safesquid.com:443 failed"]()
## Root Causes
If the website which you are trying to reach is not up
If you are unable to reach the particular website because of internet slowness issues.
### Case1
Check whether the website is opening without proxy configuration inside the browser (No proxy in the middle).
If the website is not opening without a proxy, then it is not the problem with SafeSquid.
If it is opening without a proxy, run the command below. It verifies whether the website is resolving.
Command: nslookup 192.168.27.30
**To check SafeSquid server is connecting to** 192.168.27.30 on port 80
Command: telnet WEBSITE PORT\_TO\_CONNECTON
When the website cannot be reached, example output:
telnet 192.168.27.30 80
Trying 192.168.27.30...
telnet: Unable to connect to remote host: No route to host
When the website is reachable, the output is
```text theme={null}
telnet WEBSITE PORT_TO_CONNECTON
```
When the website cannot be reached:
Command :telnet 192.168.27.30 80
you will get this output if the website can connect
root\@dev:\~# telnet 192.168.27.30 80
Trying 192.168.27.30...
Connected to 192.168.27.30.
Escape character is '^]'.
### Case 2
For an on-premises server integrated with directory services, DNS resolution is done by the directory DNS server.
Check the configuration on the local internal network. Check its address record on an active directory (AD) or local DNS server.
Run the below commands on the command prompt for **abc.safesquid.com**
```text theme={null}
nslookup
abc.safesquid.com
```
If the website is resolving to the local internal network **e.g.** (10.10.11.78,10.10.128.106)
Configure conditional forwarding to the SafeSquid local caching DNS server.
Go to the path: **/etc/bind/**
and create a file.
```text theme={null}
vim
named.conf
```
root\@swg:/etc/bind# vim named.conf
// This is the primary configuration file for the BIND DNS server named.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
include "/etc/bind/named.conf.options";
include "/etc/bind/named.conf.local";
include "/etc/bind/named.conf.default-zones";
include "/etc/bind/safesquid.dns.conf";
include "/etc/bind/abc.safesquid.com";
Go to the path
```text theme={null}
cd
/etc/bind/
```
And create a file
```text theme={null}
vim
abc.safesquid.co
```
Add below lines
```text theme={null}
zone "abc.safesquid.com" {
type forward;
forwarders {10.10.124.101;};
};
```
Command to restart bind9 service:
```text theme={null}
/etc/init.d/bind9 restart
```
Verify whether the website is resolving to the local IP successfully or not.
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Website Not Accessible](/troubleshooting/website_not_accessible) to fix websites that are not accessible.
# Custom Categorization Not Working
Source: https://docs.safesquid.com/troubleshooting/custom_categorisation_not_working
Diagnose and resolve SafeSquid custom categorization not working incidents with causes, recovery actions, and audit evidence.
# Fix Custom Categorization That Does Not Apply
Custom Categorization Not Working can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Issues
* I am trying to add new websites to the whitelist or blacklist category, but it is not updating
* Uploaded a new file with some websites and added them to specific categories. But I did not find the websites in the respective category
* SafeSquid interface has hung when I try to add custom websites to any category
## Root Causes
* Verify the status of **the** Categorization Engine from **the** Statistic page of SafeSquid Interface
* **The** SafeSquid server is unable to contact **the** SafeSquid category server
* The file(websites) was not uploaded correctly
### Check for a connection to the category server from your SafeSquid server
Run the below command and see below output
telnet category.safesquid.net 443
Trying 139.59.16.202...
Connected to category.safesquid.net.
Escape character is '^]'.
If the server is not reachable, you have to run the below commands and try telnet again
```text theme={null}
rndc flush
```
```text theme={null}
/etc/init.d/bind9 restart
```
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Whitelisted Websites Blocked](/troubleshooting/whitelisted_website_blocked) to fix whitelisted websites that are still blocked.
# Free disk and RAM to restore proxy operation
Source: https://docs.safesquid.com/troubleshooting/disk_space_and_ram_are_full
Diagnose and resolve SafeSquid free disk and ram to restore proxy operation incidents with causes, recovery actions, and audit evidence.
# Restore Proxy Operation by Freeing Disk and RAM
Free disk and RAM to restore proxy operation can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
When SafeSquid partitions or RAM are full, the proxy can fail or behave unpredictably. Use the steps below to identify full partitions, clean logs and cache safely, and prevent recurrence.
## Prerequisites
Give the enough size to backup store.
Example: to back up files of size 5GB, allow for a store of 5.5 GB.
Don't delete the original log files (.log extension) and database files.
## Check disk space
Run the below command to check the available disk space on each partition.
```text theme={null}
df
-kh
```
You will see the Used and Available sizes on each partition.
Filesystem Size Used Avail Use% Mounted on
udev 735M 4.0K 735M 1% /dev
tmpfs 150M 428K 149M 1% /run
/dev/dm-2 4.9G 4.2G 424M 91% /
none 4.0K 0 4.0K 0% /sys/fs/cgroup
none 5.0M 0 5.0M 0% /run/lock
none 746M 0 746M 0% /run/shm
none 100M 0 100M 0% /run/user
/dev/sda1 232M 37M 179M 17% /boot
/dev/mapper/dev--vg-var+cache+safesquid 1.8G 2.8M 1.7G 1% /var/cache/safesquid
/dev/mapper/dev--vg-usr+local+safesquid 1.8G 44M 1.7G 3% /usr/local/safesquid
/dev/mapper/dev--vg-var+db+safesquid 15G 193M 14G 2% /var/db/safesquid
/dev/mapper/dev--vg-var+log+safesquid 15G 171M 14G 2% /var/log/safesquid
## /dev/ram1 62M 1.3M 58M 3% /tmp/safesquid
If any of the above partitions is used over 80%, back up the following files. Then delete files as required.
## Partitions
When the "/ " partition is full remove the files from the below paths:
### /opt/safesquid/bin
change the directory to /opt/safesquid/bin by using the command below:
```text theme={null}
cd
/opt/safesquid/bin
```
![listing all the contents from /opt/safesquid/bin]()
The default files and folders are:
sections
modules
safesquid -> safesquid-2017.0518.2110.3-swg-concept\*
You should not delete the tar file which is soft-linked to the SafeSquid file. In the above image, it is: safesquid-2017.0518.2110.3-swg-concept\*
### /var/log
You can also take the backup of system logs and delete the files with the .gz extension. This folder contains the logs related to a system, so don't delete or modify the original files (i.e. with the .log extension).
**Example: dmesg.1.gz**
### /var/cache/safesquid
Delete all files from this folder by using the command mentioned below. No need to take a backup of any file from this folder.
```text theme={null}
rm
-rf
*
```
### /var/db/safesquid
Delete all files except these three files from the directory: **/var/db/safesquid/report/**
safesquid2.db
safesquid2.db-wal
safesquid2.db-shm
These files will be used to store the data required for reports generation
you can take a backup or directly delete these files.
If you delete or move the above files to another destination, restart the SafeSquid server. This recreates the deleted or moved files.
### /var/log/safesquid
Change the directory to **:/var/log/safesquid/native/** by using the below command
```text theme={null}
cd
/var/log/safesquid/native/
```
Native logs are used to store the data related to requests and responses. You can delete all files in this folder, no backup is required.
**Example file name to be deleted: 20161223132118-safesquid.log.gz**
Change the directory to: **/var/log/safesquid/extended/** by using the below command
```text theme={null}
cd
/var/log/safesquid/extended/
```
Extended logs are used to store the data related to users' information for each connection. Take a backup of these files if required.
**Example file name to be deleted: 20161223132118-extended.log.gz**
Change the directory to: **/var/log/safesquid/performance/** by using the below command
```text theme={null}
cd
/var/log/safesquid/performance/
```
Performance logs are used to store the data related to safesquid performance statistics. You can take a backup if required and delete it.
**Example file name to be deleted: 20161223132118-performance.log.gz**
Change the directory to **:/var/log/safesquid/config/** by using the below command
```text theme={null}
cd
/var/log/safesquid/config/
```
config logs used to store the data related to SafeSquid interface requests and responses. No need to take a backup of these files.
**Example file name to be deleted: 20161223132118-config.log.gz**
### /tmp/safesquid
Delete all files and folders present in this directory. By using this command
```text theme={null}
rm
-rf
*
```
This memory will be used only in upgradation time.
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Monit Service Governance](/architecture/interface/supporting_services_monit) to supervise SafeSquid processes and host resources with Monit.
# DNS Failure
Source: https://docs.safesquid.com/troubleshooting/dns_failure
Diagnose and resolve SafeSquid dns failure incidents with causes, recovery actions, and audit evidence.
# Fix DNS Failures
DNS Failure can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Issue
Via proxy sometimes occur an error "DNS Lookup for safesqddns.com failed".
![Proxy error showing "DNS Lookup for safesqddns.com failed"]()
## Root Causes
1. The FQDN of the website is incorrect.
2. The local DNS server service is not running.
3. The forwarder DNS server is not able to resolve the query.
4. The network service is down.
## Solution
If the website FQDN is incorrect, accessing it via proxy gives a DNS failure. So, you have to enter the correct FQDN of that particular website.
If the website FQDN is correct, you can still hit a DNS failure. This happens when the local DNS server service is not running. So, you make sure that the local DNS server service is running.
Run the below commands to verify DNS server service
**nslookup (FQDN of the site)**
example:
**nslookup [www.safesquiddns.com](http://www.safesquiddns.com)**
Server: 127.0.0.1
Address: 127.0.0.1#53
Non-authoritative answer:
[www.safesquiddns.com](http://www.safesquiddns.com) canonical name = safesquiddns.com.
Name: safesquiddns.com
Address: 164.177.149.146
If the website is not able to resolve
root\@dev:\~# nslookup [www.safesquiddns.com](http://www.safesquiddns.com)
Server: 127.0.0.1
Address: 127.0.0.1#53
server can't find test.safesquiddns.com: NXDOMAIN
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [BIND Local DNS Resolver](/architecture/interface/bind) to run BIND as the local DNS resolver.
# LDAP Entries Not Fetched
Source: https://docs.safesquid.com/troubleshooting/failed_to_fetch_ldap_entries
Diagnose and resolve SafeSquid ldap entries not fetched incidents with causes, recovery actions, and audit evidence.
# Fix LDAP Entries That Fail to Load
LDAP Entries Not Fetched can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Issues
I configured LDAP with Active Directory, but LDAP entries are still not fetched.
## Root Cause
1. **Case 1:** LDAP is not properly configured with Active Directory.
2. **Case 2:** You are not able to contact AD (Active Directory).
Verify it from SafeSquid Logs.
```text theme={null}
POST http://safesquid.cfg/ HTTP/1.1
Host: safesquid.cfg
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:66.0) Gecko/20100101 Firefox/66.0
Accept: application/xml, text/xml, */*; q=0.01
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Referer: http://safesquid.cfg/
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Requested-With: XMLHttpRequest
Content-Length: 25
Connection: keep-alive
2019 04 08 12:23:55.725 [10281] debug: network: net_filebuf_read: speed: 192.168.0.10 uploaded to safesquid.cfg 25 bytes in 20.0000 us [ 1.2500 MBps ]
2019 04 08 12:23:55.725 [10281] debug: request: buffered 25 bytes of POSTDATA
2019 04 08 12:23:55.725 [10281] debug: interface: [IP:192.168.0.10] [1]
2019 04 08 12:23:55.725 [10281] debug: interface: invoke_handler:89 [ldap]
**2019 04 08 12:23:55.732 [0] debug: ldap: cache_update:1937 manual/configuration update**
2019 04 08 12:23:55.732 [0] debug: network: writing 0 bytes to /usr/local/safesquid/security/dns/safesquid.dns.conf file
2019 04 08 12:23:55.732 [0] debug: ldap: init_routine_unlocked:239 connection not exists in pool for domain safesquid.local
2019 04 08 12:23:55.732 [0] debug: ldap: get_ld:1174 192.168.221.1:389 max query limit:[0], 0 means no limit
2019 04 08 12:23:58.731 [0] error: ldap: s_bind:2253 authentication failed for user :administrator @safesquid.local [-1 :Can 't contact LDAP server]
2019 04 08 12:23:58.733 [10281] debug: header: to 192.168.0.10:
HTTP/1.1 200 OK
X-Powered-By: safesquid-2019.0401.1624.3-swg-standard
Date: Mon, 08 Apr 2019 12:23:55 GMT
Content-Type: text/xml
Content-Length: 40
Cache-Control: no-cache
Proxy-Connection: keep-alive
X-SafeSquid-Client-ID: 10281.1
X-SafeSquid-User-Groups: ADMINS
```
### Case 1: Check for configuration of LDAP with AD (Active Directory).
Run command on the console:
```text theme={null}
ldapsearch
-x
-h
192.168
.221.1
-b
"dc=safesquid,dc=test"
-D
adusername@domain
-w
password
```
root\@sabproxy:\~# ldapsearch -x -h 192.168.221.1 -b "dc=safesquid,dc=test" -D [administrator@safesquid.test](mailto:administrator@safesquid.test) -w sarva\@1234
The above command gives you all the fetch entries of users from AD. This works only if the LDAP integration configuration is correct.
Follow the [How to integrate AD or OpenLDAP with SafeSquid](https://help.safesquid.com/portal/en/kb/articles/integrate-ad-or-openldap-with-safesquid) for How to integrate AD or Open LDAP with SafeSquid.
### Case2: Check the connection to Active Directory
```text theme={null}
root@sabproxy:~# ping 192.168.221.1
PING 192.168.221.1 (192.168.221.1) 56(84) bytes of data.
64 bytes from 192.168.221.1: icmp_seq=1 ttl=128 time=0.396 ms
64 bytes from 192.168.221.1: icmp_seq=2 ttl=128 time=0.446 ms
64 bytes from 192.168.221.1: icmp_seq=3 ttl=128 time=0.361 ms
--- 192.168.221.1 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2000ms
rtt min/avg/max/mdev = 0.361/0.401/0.446/0.034 ms
root@sabproxy:~# ping ad.safesquid.test
PING ad.safesquid.test (192.168.221.1) 56(84) bytes of data.
64 bytes from 192.168.221.1: icmp_seq=1 ttl=128 time=0.262 ms
64 bytes from 192.168.221.1: icmp_seq=2 ttl=128 time=0.358 ms
64 bytes from 192.168.221.1: icmp_seq=3 ttl=128 time=0.442 ms
^C
--- ad.safesquid.test ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2000ms
rtt min/avg/max/mdev = 0.262/0.354/0.442/0.073 ms
ad.safesquid.test (192.168.221.1) >> Active Directory FQDN and IP Address
**If you are unable to contact Active Directory you should face an error as shown below " Destination Host Unreachable"**
root@sabproxy:~# ping 192.168.221.1
PING 192.168.221.1 (192.168.221.1) 56(84) bytes of data.
From 192.168.221.222 icmp_seq=31 Destination Host Unreachable
From 192.168.221.222 icmp_seq=32 Destination Host Unreachable
--- 192.168.221.1 ping statistics ---
37 packets transmitted, 0 received, +6 errors, 100% packet loss, time 36269ms
```
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [SSO Authentication Fail](/troubleshooting/sso_authentication_fail) to fix SSO authentication failures.
# Using find_client_id.sh for Connection Logs
Source: https://docs.safesquid.com/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log
Use the find_client_id.sh script to extract complete connection details from SafeSquid logs for troubleshooting and forensic analysis.
## Problem
Service interruptions and policy failures increase operational risk when root cause is unclear.
## Benefits
You can diagnose faster with repeatable checks, reduce downtime, and restore expected protection.
## Advantages
You get symptom-first guidance that supports incident response and produces evidence for audit and postmortem review.
## Call to action
Follow the checks in order, capture the observed output, and apply the fix that matches your failure pattern.
# Get complete connection log with find\_client\_id.sh
Native logs are written in real time by response; entries for one connection can be scattered. To analyze a single connection from start to finish (profiles, categories, headers, errors), use the client id. It pulls all log lines for that connection. find\_client\_id.sh extracts complete connection details for a given client id. Below: how to obtain the client id and run the script.
To use find\_client\_id.sh you are first required to get your connection's client id.
Client id can be extracted from the response headers section in browsers network tab.
(Note: this assumes you know how to open developer tools in a browser.)
![find_client_id script output or connection log example]()
Also, client id can be extracted from SafeSquid's native logs
## Next steps
* [Troubleshooting](/troubleshooting/troubleshooting) - find the runbook that matches your symptom.
* [Security Logs](/use_cases/audit_and_forensics/security_logs) - read the logged decision for the client you identified.
* [Support](/architecture/policy_management_console/support) - collect evidence before you escalate.
# Troubleshooting Installation Issues
Source: https://docs.safesquid.com/troubleshooting/installation_issues
Diagnose and resolve SafeSquid troubleshooting installation issues incidents with causes, recovery actions, and audit evidence.
# Fix Installation Issues
Troubleshooting Installation Issues can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
If you see **Bad archive mirror**, **Failed to retrieve pre-configuration**, or other installation failures, use the sections below. They help you diagnose and fix the failure. Symptoms are grouped by stage: before install, during install, and network-related.
## Before Installation
Common issues in this stage include system compatibility and creating a bootable USB or attaching the appropriate .iso file. Another is correctly setting up the BIOS/UEFI settings.
Solutions involve checking system requirements, verifying the integrity of the installation media, and ensuring correct boot order.
## During Installation
Issues during installation can range from partitioning errors, and network configuration problems, to software selection difficulties.
Resolutions can include checking disk space, reviewing network settings, and ensuring proper selection of software packages.
For the network-related issues below, use the installer console to identify the root cause and act on it.
## Network Checks for Issue Identification
Network issues can significantly impact the installation and functionality of SafeSquid. If you see **"Bad archive mirror"** or **"Failed to retrieve the pre-configuration file"** during installation, use the checks below. They fix DNS and gateway settings.
Administrators can perform various checks to identify and resolve network-related problems:
1. **Network Configuration**: Review and modify network settings using the `ip` commands. `ip addr show # Display all interface IP addresses ip route show # Display routing table`
**What to check:**
* IP address is assigned to the correct interface (e.g., `eth0: inet 192.168.1.100/24`)
* Default gateway is present in routing table (e.g., `default via 192.168.1.1 dev eth0`)
**Common issues:**
* No IP address shown -> interface not configured or DHCP failed
* No default route -> gateway not set during network configuration step
2. **DNS Resolution and Ping check**: busybox is a minimal Linux environment. Use `ping` to verify both DNS resolution and connectivity. `ping -c 3 google.com`
**Expected success output:** `PING google.com (142.250.x.x): 56 data bytes 64 bytes from 142.250.x.x: icmp_seq=0 ttl=xx time=x.x ms`
**Failure symptoms:**
* `ping: bad address 'google.com'` -> DNS resolution failed (check `/etc/resolv.conf` for nameserver entries)
* `Network is unreachable` -> No default gateway configured
* `Request timeout` or 100% packet loss -> Firewall blocking ICMP, or no internet connectivity
3. **Firewall Rules**: check your network firewall rules for possible port blocking.
By performing these network checks and using the available networking commands, administrators can pinpoint network-related problems and take corrective actions.
Once you have solved the network problem, return to the installer tty using ctrl + alt + F1. Then select continue.
Select continue again.
Select the "Download debconf preconfiguration file" step.
Follow the steps of standard installation and continue your installation process.
## Conclusion
For additional assistance, consult the SafeSquid forums and community resources.
## ISO Installation Failure
### Symptoms
**"Failed to retrieve the pre-configuration file"** appears during installation. The installer cannot download the automated configuration script from SafeSquid servers. This typically indicates DNS or gateway misconfiguration.
**"Bad archive mirror"** Appears when the installer cannot reach Debian package repositories. This indicates:
* Firewall blocking outbound HTTP/HTTPS on the assigned proxy IP
* No default gateway configured
* DNS resolution failure for `deb.debian.org` or `downloads.safesquid.net`
### Root Causes
* **DNS misconfiguration:** Wrong DNS server IP, or DNS server is unreachable
* **Gateway misconfiguration:** No default route, or gateway IP is incorrect
* **NIC configuration:** Wrong interface selected, or interface is down
* **Firewall rules:** Network firewall blocking installation traffic from the SafeSquid server's IP
If you face any error while installing SafeSquid Appliance Builder (SAB-ISO), you will get debugging logs information by pressing **ALT+F4**. To return to the previous screen press **ALT+F1**.
![Bad Archive Mirror Template]()
![Failed to retrieve the pre-configuration file error template]()
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Linux Server Install](/getting_started/install_safesquid/linux_server) to follow the Linux server installation steps.
# Interface Access Denied
Source: https://docs.safesquid.com/troubleshooting/interface_access_denied
Diagnose and resolve SafeSquid interface access denied incidents with causes, recovery actions, and audit evidence.
# Fix Interface Access Denied Errors
Interface Access Denied can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Issues
Administrators can be locked out when creating or reordering policies in the Access Restrictions section. The browser then shows Access Denied.
## Root causes
SafeSquid evaluates Access Restrictions entries top to bottom and matches each entry to the connection. After an entry matching the connection's IP or username is applied, later entries are not evaluated for that connection. When creating or editing entries, ensure at least one entry allows access to the web interface. The web interface ([http://safesquid.cfg/](http://safesquid.cfg/)) is an embedded Rest UI interface built into SafeSquid, NOT resolved by DNS. Such an entry must match the administrator's connection and has Web interface (Config) selected in the Access field.
**Example:**
Scenario: three entries in the Allow list of Access Restrictions:
1. First entry: access the web interface via SSH tunnel.
2. Second entry: allow the AUTHENTICATION BYPASS profile.
3. Third entry: the entry used for general internet access.
A fourth entry is added with Web interface removed from the Access field, then moved up to third. The third position now matches the administrator's connection and has Web interface disabled. The first is for SSH, and the second is for AUTHENTICATION BYPASS. The administrator is locked out and sees Access Denied. To avoid this, always keep at least one entry that allows access to the Web interface.
There are two options to recover access. Restart the SafeSquid service, or use an SSH tunnel to reach the interface and correct the Access Restrictions entries.
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Policy Management Console](/architecture/interface/configuration_portal) to review the management console that serves the interface.
# Unable to Generate Support Tar-ball
Source: https://docs.safesquid.com/troubleshooting/no_tar_ball_support
Diagnose and resolve SafeSquid unable to generate support tar-ball incidents with causes, recovery actions, and audit evidence.
# Fix a Failed Support Tar-ball Download
Unable to Generate Support Tar-ball can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## ISSUE
Unable to generate support tarball from SafeSquid Interface: **Support Page > Support Tarball**
If you cannot generate support tarball from the SafeSquid interface, automatically follow the steps below.
**Go to this path (location of support\_tarball.sh script)**
## root\@sabproxy:\~# cd /usr/local/safesquid/ui\_root/cgi-bin/
root\@sabproxy:/usr/local/safesquid/ui\_root/cgi-bin# ll
total 80
drwxrwxr-- 2 ssquid root 4096 Mar 14 11:57 ./
drwxrwxr-- 8 ssquid root 4096 Mar 14 11:57 ../
-rwxrwxr-- 1 ssquid root 1602 Mar 19 16:54 app\_template.sh\*
-rwxrwxr-- 1 ssquid root 683 Mar 19 16:54 cronentry.sh\*
-rwxrwxr-- 1 ssquid root 2542 Mar 19 16:54 kerberos.sh\*
-rwxrwxr-- 1 ssquid root 17255 Mar 19 16:54 modify\_plot.sh\*
-rwxrwxr-- 1 ssquid root 2608 Mar 19 16:54 moniter.sh\*
-rwxrwxr-- 1 ssquid root 16869 Mar 19 16:54 plot.sh\*
-rwxrwxr-- 1 ssquid root 0 Mar 19 16:54 restart.sh\*
-rwxrwxr-- 1 ssquid root 619 Mar 19 16:54 service.sh\*
-rwxrwxr-- 1 ssquid root 6193 Mar 19 16:54 support\_tarball.sh\*
## -rwxrwxr-- 1 ssquid root 518 Mar 19 16:54 update.sh\*
Here you can see that the **support\_tarball.sh** script is available with appropriate permissions.
Once you confirm the availability of **support\_tarball.sh**, move to your requirements.
**To generate support tarball manually as below :**
```text theme={null}
Command: ./support_tarball.sh
```
Go to the below path and run above command
root\@swg:/usr/local/safesquid/ui\_root/cgi-bin# ./support\_tarball.sh
2018-06-18::18:06:24.437971402 Creating folder: safesquid-2018-06-18-18-06-24 to contain relevant files and information for support
2018-06-18::18:06:24.445054777 Copying last 5000 lines of /var/log/safesquid/native/safesquid.log to safesquid-2018-06-18-18-06-24/safesquid\_logs/safesquid.log
2018-06-18::18:06:24.868917174 Copying last 5000 lines of /var/log/safesquid/extended/extended.log to safesquid-2018-06-18-18-06-24/safesquid\_logs/extended.log
2018-06-18::18:06:24.884119250 Copying last 5000 lines of /var/log/safesquid/performance/performance.log to safesquid-2018-06-18-18-06-24/safesquid\_logs/performance.log
2018-06-18::18:06:24.935809437 Copying last 5000 lines of /var/log/monit.log to safesquid-2018-06-18-18-06-24/system\_logs/monit.log
2018-06-18::18:06:24.969476836 Getting sysctl information into safesquid-2018-06-18-18-06-24/sysctl.txt
2018-06-18::18:06:25.142134567 Getting the Information about Network Interfaces into safesquid-2018-06-18-18-06-24/network.txt
2018-06-18::18:06:25.159857810 Getting the Information about Network Routing Table into safesquid-2018-06-18-18-06-24/network.txt
2018-06-18::18:06:25.174699658 Getting the Network Statistics into safesquid-2018-06-18-18-06-24/network.txt
2018-06-18::18:06:25.193097377 Getting iptables NAT Configuration into safesquid-2018-06-18-18-06-24/iptables.txt
2018-06-18::18:06:25.535699750 Getting iptables MANGLE Configuration into safesquid-2018-06-18-18-06-24/iptables.txt
2018-06-18::18:06:25.542781878 Getting iptables FILTER Configuration into safesquid-2018-06-18-18-06-24/iptables.txt
2018-06-18::18:06:25.549963671 Getting Disk Partitions Information into safesquid-2018-06-18-18-06-24/filesystem.txt
Disk /dev/mapper/swg--vg-root doesn't contain a valid partition table
Disk /dev/mapper/swg--vg-swap\_1 doesn't contain a valid partition table
Disk /dev/mapper/swg--vg-opt+safesquid doesn't contain a valid partition table
Disk /dev/mapper/swg--vg-var+lib+safesquid doesn't contain a valid partition table
Disk /dev/mapper/swg--vg-usr+local+safesquid doesn't contain a valid partition table
Disk /dev/mapper/swg--vg-var+lib doesn't contain a valid partition table
Disk /dev/mapper/swg--vg-var+log doesn't contain a valid partition table
Disk /dev/mapper/swg--vg-var+cache+safesquid doesn't contain a valid partition table
Disk /dev/mapper/swg--vg-var+log+safesquid doesn't contain a valid partition table
Disk /dev/mapper/swg--vg-var+db+safesquid doesn't contain a valid partition table
2018-06-18::18:06:25.597927995 Getting Disk Usage Information into safesquid-2018-06-18-18-06-24/filesystem.txt
2018-06-18::18:06:25.612231349 Getting Disk inode Usage Information into safesquid-2018-06-18-18-06-24/filesystem.txt
2018-06-18::18:06:25.616382197 Getting File System Mount Information into safesquid-2018-06-18-18-06-24/filesystem.txt
2018-06-18::18:06:25.756065687 Getting Kernel Information into safesquid-2018-06-18-18-06-24/systeminfo.txt
2018-06-18::18:06:25.760061018 Getting CPU information into safesquid-2018-06-18-18-06-24/systeminfo.txt
2018-06-18::18:06:25.774230478 Getting Memory Information into safesquid-2018-06-18-18-06-24/systeminfo.txt
2018-06-18::18:06:25.777545658 Getting ram memory into safesquid-2018-06-18-18-06-24/systeminfo.txt
2018-06-18::18:06:25.788885128 Creating the tar-ball for sending to SafeSquid Technical Support
2018-06-18::18:06:26.008801780 Extracted contents of the support tar-ball can be confirmed from safesquid-2018-06-18-18-06-24
**The support tarball will generate at below path**
root\@swg:/var/log/safesquid/support# ll
total 636
drwxrwxr-- 2 ssquid root 4096 Jun 18 18:06 ./
drwxrwxr-- 9 ssquid root 4096 Jun 11 16:29 ../
-rw-r--r-- 1 ssquid root 642727 Jun 18 18:06 **safesquid-2018-06-18-18-06-24.tar.gz**
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Support](/architecture/policy_management_console/support) to collect evidence before you escalate.
# Unable to Generate Performance Plot
Source: https://docs.safesquid.com/troubleshooting/not_generating_performance_plot
Diagnose and resolve SafeSquid unable to generate performance plot incidents with causes, recovery actions, and audit evidence.
# Fix a Missing Performance Plot
Unable to Generate Performance Plot can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## ISSUE
Unable to generate performance plot from SafeSquid Interface: **Support Page > Performance Plot**
When you install SafeSquid Appliance Builder (SAB) to setup your secure web gateway, the required packages are also installed automatically.
The necessary package required to generate performance plot from the SafeSquid interface is gnuplot(Command-line driven interactive plotting program)
If you can not generate a performance plot from the SafeSquid interface automatically follow the below steps.
1. **Verify whether the package (gnuplot) is properly installed while installation or not**
root\@sabproxy:\~# aptitude search gnuplot
i gnuplot - Command-line driven interactive plotting program
If it is not installed, properly install it manually (Internet is required for installation)
root\@sabproxy:\~# **aptitude install gnuplot**
1. **Go to this path (location of plot.sh script)**
root\@sabproxy:\~# cd /usr/local/safesquid/ui\_root/cgi-bin/
root\@sabproxy:/usr/local/safesquid/ui\_root/cgi-bin# ll
total 80
drwxrwxr-- 2 ssquid root 4096 Mar 14 11:57 ./
drwxrwxr-- 8 ssquid root 4096 Mar 14 11:57 ../
-rwxrwxr-- 1 ssquid root 1602 Mar 19 16:54 app\_template.sh\*
-rwxrwxr-- 1 ssquid root 683 Mar 19 16:54 cronentry.sh\*
-rwxrwxr-- 1 ssquid root 2542 Mar 19 16:54 kerberos.sh\*
-rwxrwxr-- 1 ssquid root 17255 Mar 19 16:54 modify\_plot.sh\*
-rwxrwxr-- 1 ssquid root 2608 Mar 19 16:54 moniter.sh\*
**-rwxrwxr-- 1 ssquid root 16869 Mar 19 16:54 plot.sh**\*
-rwxrwxr-- 1 ssquid root 0 Mar 19 16:54 restart.sh\*
-rwxrwxr-- 1 ssquid root 619 Mar 19 16:54 service.sh\*
-rwxrwxr-- 1 ssquid root 6193 Mar 19 16:54 support\_tarball.sh\*
-rwxrwxr-- 1 ssquid root 518 Mar 19 16:54 update.sh\*
Here you can see the **plot.sh** script is available with appropriate permissions.
Once you confirm the availability of the **plot.sh** script, move for your requirements.
1. **For a specific time range you can generate the plot as below:**
./plot.sh YYYYMMDDHHMMSS YYYYMMDDHHMMSS
**Example1:**
root\@sabproxy:/usr/local/safesquid/ui\_root/cgi-bin#./plot.sh 20180305000000 20180305235959
1. **For whole day i.e. march 5th 2018**
This will give the performance plot for the whole day i.e. March 5th, 2018
**Example2:**
root\@sabproxy:/usr/local/safesquid/ui\_root/cgi-bin#./plot.sh 20180305000000 20180305235959
1. **Go to below path /var/log/safesquid/performance/ >> location of generated performance plot**
root\@sabproxy:\~# cd /var/log/safesquid/performance/
root\@sabproxy:/var/log/safesquid/performance# ll
total 84968
drwxrwxr-- 2 ssquid root 4096 Mar 21 16:05 ./
drwxrwxr-- 9 ssquid root 4096 Mar 14 12:05 ../
-rw-rw-r-- 1 ssquid root 86732546 Mar 21 16:46 performance.log
**-rw-rw-r-- 1 ssquid root 259706 Mar 21 16:46 performance.png**
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Support](/architecture/policy_management_console/support) to collect evidence before you escalate.
# Product Activation Failure
Source: https://docs.safesquid.com/troubleshooting/product_failure
Diagnose and resolve SafeSquid product activation failure incidents with causes, recovery actions, and audit evidence.
# Fix Product Activation Failures
Product Activation Failure can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Issues
1. I uploaded my activation key, but still SafeSquid UI is showing Failed to set Subscription details.
2. After uploading the activation key, I am getting the template on the browser proxy server refusing connections.
3. Unable to see subscription details on the support page from SafeSquid User Interface.
## Root Causes
1. SafeSquid server is unable to contact the SafeSquid Subscription server.
2. The file (activation key) was not uploaded correctly.
3. The file name you uploaded is other than **activation\_key.**
4. After uploading the activation key, the page shows the proxy server refusing connections.
5. SafeSquid service restart was not done properly.
### Case 1: Check for the activation\_key file on the SafeSquid server
Run the below command and check for the file:
```text theme={null}
ls
-lrt
/usr/local/safesquid/security/
```
## root\@dev:\~# ls -lrt /usr/local/safesquid/security/
total 60
drwxrwxr-- 2 ssquid root 4096 Jul 10 11:55 dns
-rw-rw-r-- 1 ssquid root 724 Jul 28 11:23 krb5.conf
-rw-rw-r-- 1 ssquid root 2111 Aug 3 18:52 activation\_key
drwxrwxr-- 2 ssquid root 12288 Aug 4 16:04 policies
drwxrwxr-- 5 ssquid root 4096 Aug 4 16:09 ssl
-rw-rw-r-- 1 ssquid root 15744 Aug 5 09:51 activation\_key.updates.backup
## -rw-rw-r-- 1 ssquid root 15744 Aug 5 09:51 activation\_key.updates
If the file was not found, then upload your activation key again and click on restart
Restarting the SafeSquid service from the SafeSquid Interface works only with a correctly configured [monit service](/architecture/interface/supporting_services_monit) on the SafeSquid server.
Otherwise, you can directly restart the SafeSquid service from LINUX box by using below commands
```text theme={null}
/etc/init.d/safesquid stop
```
```text theme={null}
/etc/init.d/safesquid start
```
### Case 2: Check the connection to the Subscription server, by using following commands
## root\@dev:\~# ping swgupdates2.safesquid.net
PING swgupdates2.safesquid.net (104.236.27.61) 56(84) bytes of data.
64 bytes from 104.236.27.61: icmp\_seq=1 ttl=52 time=309 ms
64 bytes from 104.236.27.61: icmp\_seq=2 ttl=52 time=228 ms
\--- swgupdates2.safesquid.net ping statistics ---
2 packets transmitted, 2 received, 0% packet loss, time 1000ms
## rtt min/avg/max/mdev = 228.387/269.078/309.770/40.694 ms
```text theme={null}
nslookup
swgupdates2.safesquid.net
```
## Server: 127.0.0.1
Address: 127.0.0.1#53
Non-authoritative answer:
Name: swgupdates2.safesquid.net
## Address: 104.236.27.61
**After uploading the activation key, the page shows the proxy server refusing connections**
SafeSquid restart was not done, start the SafeSquid from the server console by using the command below:
```text theme={null}
/etc/init.d/safesquid start
```
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Self-Service Portal](/architecture/interface/self_service_portal) to manage activation and licensing.
# Proxy Server Refusing Connections Error
Source: https://docs.safesquid.com/troubleshooting/proxy_server_refusing_connection_error
Diagnose and resolve SafeSquid proxy server refusing connections error incidents with causes, recovery actions, and audit evidence.
# Fix Proxy Server Connection Refusals
Proxy Server Refusing Connections Error can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Issues
1. I am trying to access the web through the proxy server and suddenly getting the error "Proxy server refusing connections".
2. When I go to Restart the SafeSquid service from the SafeSquid interface, it displays the error "Proxy server refusing connections".
## Root Causes
1. SafeSquid Process is not running.
2. SafeSquid is not listening on the specific IP (or) port, where you configured in the client browsers.
3. Monit service is not running on SafeSquid Server. (When you restart SafeSquid from the Interface, the monit service will start the SafeSquid service. If the Monit is not running, then SafeSquid is not going to start, till you start the Monit service manually).
4. Check the status of the monit service whether it is up or down.
```text theme={null}
pidof monit
```
If the ouput of the command is empty then run the following command to start the service.
```text theme={null}
/etc/init.d/monit start
```
1. Check the status of SafeSquid Service whether it is up or down.
```text theme={null}
pidof safesquid
```
If the monit service is started already, then you will get the SafeSquid process I
1. Check the listening IP and port of SafeSquid by using the below command
```text theme={null}
netstat
-tlnp
|
grep
-iE
"safesquid"
```
**tcp6 0 0 :::8080 :::* LISTEN 2741/safesquid*\*
**tcp6 0 0 :::8081 :::* LISTEN 2741/safesquid*\*
**tcp6 0 0 :::8443 :::* LISTEN 2741/safesquid*\*
1. Check the IP configured and Port in your browser and compare it with the above output.
In the above command, SafeSquid listens on all Interfaces present on the server with ports 8080, 8081, and 8443.
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Connection Failure to Websites](/troubleshooting/connection_failure_on_websites) to fix connection failures to websites.
# SafeSearch Not Working
Source: https://docs.safesquid.com/troubleshooting/safesearch_not_working
Diagnose and resolve SafeSquid safesearch not working incidents with causes, recovery actions, and audit evidence.
# Fix SafeSearch That Does Not Enforce
SafeSearch Not Working can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
You have enabled all the entries required for Safe Searches, but you can still access inappropriate content through search engines. Follow the steps below to troubleshoot.
Test your configuration once. All required entries must be enabled.
Then test your HTTPS Inspection enabled or not. If it is not enabled, see [How to configure HTTPS inspection](/use_cases/ssl_inspection/ssl_inspection)
Then check the SSL certificate in the browser. See [Test certificate in Firefox](/use_cases/ssl_inspection/ssl_inspection).
Removes the cache and restart the browser and test it again.
You can see block template when "Text Analyzer" and default entry to block pornogrophy in policies and profiles are enabled.
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Enforce SafeSearch](/use_cases/access_restriction/safesearch) to configure SafeSearch enforcement.
# SSL Certification Errors
Source: https://docs.safesquid.com/troubleshooting/ssl_inspection_issues
Diagnose and resolve SafeSquid ssl certification errors incidents with causes, recovery actions, and audit evidence.
# Fix SSL Certificate Errors
SSL Certification Errors can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## SSL certificate and inspection issues
| Symptom | Likely cause | Resolution | Verification |
| - | - | - | - |
| Browser shows "Your connection is not private" after certificate import | HTTPS Inspection policies not configured correctly | Configure Enforce SSL scanning and Bypass rules in Configure -> Real-time content security -> HTTPS Inspection | Reload HTTPS site; confirm no certificate warning |
| youtube.com (or one site) fails; other HTTPS sites work | Global subsection not set to Enabled TRUE | Set HTTPS Inspection -> Global -> Enabled to TRUE | Access the previously failing site |
| "Secured connection fail" after certificate installed in browser | Passphrase mismatch or password encryption failed | Re-enter correct passphrase; ensure password encryption step completed | Retry HTTPS; confirm connection succeeds |
| Certificate file downloaded with 0 bytes | Certificate downloaded without password encryption | Download certificate with encryption enabled in Self-Service Portal | Check file size; re-import in browser |
| ERROR S\_X509\_DNS\_MISMATCH or "SSL Certificate has DNS errors" | Stale or wrong cert in SafeSquid SSL cache | Remove affected site from SSL Certs/Cache or clear /var/db/safesquid/ssl/certs for that host | Retry connection; check logs for ssl\_ctx :NULL or failed reading key |
| Some HTTPS sites work, others do not | Mixed cert or cache state after key/cert change | Clear SSL cache; remove old activation key data; ensure new cert deployed to clients | Test previously failing and working sites |
**Details (numbered items):**
1. This applies when the SSL certificate is imported into the Chrome browser. The browser still shows **Your connection is not private** (or similar) for HTTPS sites.
->Policies in the HTTPS Inspection subsection are misconfigured.
1. While the **successful configuration of HTTPS Inspection**, accessing youtube.com shows an error while all other HTTPS sites work fine.
->In the HTTPS inspection section, this problem can arise if the Global subsection is not set to Enabled as TRUE.
1. While the SafeSquid certificate is installed inside the browser however HTTPS sites show the error **Secured connection fail**.
->Either passphrases were not matched or Password encryption failed due to inappropriate input being given.
1. SSL certificate downloaded with size 0 bytes.
->When the certificate is downloaded without encryption of the password then the certificate will be downloaded with 0 bytes.
1. Displaying ERROR "SSL Connection to webmail.safesquid.net:2096 denied S\_X509\_DNS\_MISMATCH: SSL Certificate has DNS errors."
->Remove HTTPS websites from SSL Certs/Cache when **Secured connection fails** appears on HTTPS websites.
1. Or some of the **HTTPS websites are working without error** but some of the **HTTPS websites are not working**.
### Verify SSL certificate import in browser
Follow [Configure HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection) and [Import certificate into Firefox](/use_cases/ssl_inspection/ssl_inspection) or Chrome/IE.
### Case 2: Check SSL certs/cache for these symptoms
SafeSquid certificate is imported in the browser but a secured connection still fails when accessing HTTPS websites. Some HTTPS sites work while others do not. After removing the old activation key, installing a new key, and configuring the new SSL certificate, clear the SSL cache. Do this if issues persist.
Native Logs
2018 03 17 10:15:38.084 \[119] network: IP:192.168.0.10 fd:20 normal client disconnected after making 1 requests
2018 03 17 10:15:38.084 \[119] warn: advice: \[IP:192.168.0.10] process: transfer failed
2018 03 17 10:15:38.084 \[119] error: ssl: ClientEncrypt: failed encryption :anonymous @192.168.0.10 for [www.irctc.co.in:443](http://www.irctc.co.in:443)
2018 03 17 10:15:38.083 \[119] error: ssl: EncryptC:987 ssl\_ctx :NULL
**2018 03 17 10:15:38.083 \[119] error: ssl: failed : reading key from /var/db/safesquid/ssl/certs/irctc.co.in/[www.irctc.co.in](http://www.irctc.co.in)**
When facing the above issues, remove all HTTPS website data from **/var/db/safesquid/ssl**
Run the below command and check for the file
```text theme={null}
cd /var/db/safesquid/ssl
```
root\@sabproxy:/var/db/safesquid/ssl# ll
total 24
drwxrwxr-- 6 ssquid root 4096 Jul 28 17:06 ./
drwxrwxr-- 7 ssquid root 4096 Jul 28 17:06 ../
drwxrwxr-- 2 ssquid root 4096 Aug 10 13:34 badcerts/
drwxrwxr-- 29 ssquid root 4096 Sep 2 16:27 certs/
drwxrwxr-- 2 ssquid root 4096 Jul 28 17:06 goodcerts/
drwxrwxr-- 2 ssquid root 4096 Jul 28 17:06 serials/
root\@sabproxy:/var/db/safesquid/ssl# cd certs/
root\@sabproxy:/var/db/safesquid/ssl/certs#rm -rf \*
Repeat the above step for **goodcerts**/ and **badcerts**/ **and access those websites from the browser.**
### S\_X509\_DNS\_MISMATCH: SSL certificate has DNS errors
The origin website's certificate is broken when the browser shows "S\_X509\_DNS\_MISMATCH: SSL Certificate has DNS errors" via proxy. This holds despite a correct certificate in the browser. SafeSquid stores such sites under **/var/db/safesquid/ssl/badcerts/**. Locate the domain in that path.
Go to that domain name folder by command:
```text theme={null}
cd domain-name
```
The FQDN for that website is in that folder (e.g. webmail.safesquid.net). Open the FQDN file with **vi FQDN** (e.g. vi webmail.safesquid.net).
Here you should find mismatch domain name
root\@dev:\~# cd /var/db/safesquid/ssl/
root\@dev:/var/db/safesquid/ssl# ll
total 52
drwxrwxr-- 2 ssquid root 4096 Jul 4 2017 serials
drwxrwxr-- 2 ssquid root 4096 Mar 9 16:30 goodcerts
**drwxrwxr-- 71 ssquid root 4096 Mar 9 16:45 badcerts**
drwxrwxr-- 1022 ssquid root 36864 Mar 12 12:16 certs
root\@dev:/var/db/safesquid/ssl# cd badcerts/
root\@dev:/var/db/safesquid/ssl/badcerts# ll
total 276
drwxrwxr-- 2 ssquid root 4096 Mar 8 12:07 1rx.io
drwxrwxr-- 2 ssquid root 4096 Mar 8 12:32 ravenad.com
drwxrwxr-- 2 ssquid root 4096 Mar 8 15:36 microsoft.com
drwxrwxr-- 2 ssquid root 4096 Mar 8 16:04 indiatimes.com
drwxrwxr-- 2 ssquid root 4096 Mar 8 19:08 quoracdn.net
drwxrwxr-- 2 ssquid root 4096 Mar 9 15:25 iis.net
**drwxrwxr-- 2 ssquid root 4096 Mar 9 16:27 safesquid.net**
root\@dev:/var/db/safesquid/ssl/badcerts# cd safesquid.net/
root\@dev:/var/db/safesquid/ssl/badcerts/safesquid.net# ll
total 8
**-rw-rw-r-- 1 ssquid root 5904 Mar 9 15:43 webmail.safesquid.net**
root\@dev:/var/db/safesquid/ssl/badcerts/safesquid.net# vi webmail.safesquid.net
**S\_X509\_DNS\_MISMATCH: SSL Certificate has DNS errors**.
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
f8:bd:5e:60:3d:26:db:5d:1a:c0:6a:05:92:ee:c7:81
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=US, ST=TX, L=Houston, O=cPanel, Inc., CN=cPanel, Inc. Certification Authority
Validity
Not Before: Jul 23 00:00:00 2017 GMT
Not After : Jul 23 23:59:59 2018 GMT
Subject: OU=Domain Control Validated, OU=PositiveSSL, **CN=alpha.surebrowse.net**
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
To allow domain mismatch errors for specific HTTPS websites, create a policy:
![Creating a new policy in request types under custom settings section]()
![Creating a policy by adding all the required values]()
![Creating a new policy in Access profiles section]()
![adding the required values]()
![Clicking on Inspection policies in HTTPS inspection under Real time content security section]()
![Creating a new policy]()
![showing settings to configure a security policy, allowing "block domain mismatch in the website ssl certificate"]()
![moving up the created policy just above the last policy]()
![saving configuration globally]()
## Verification and Evidence
* **Interface Checks**: Confirm the SafeSquid Root CA is installed in the browser trust store ([Import Certificate into Chrome or IE](/use_cases/ssl_inspection/import_certificate_chrome_ie)). In Configuration Portal, HTTPS Inspection policies match the intended bypass/enforce rules; SSL Certs/Cache cleared if DNS mismatch was the issue.
* **Log Analysis**: Native logs show successful client encryption for previously failing domains. No `S_X509_DNS_MISMATCH` or transfer failed errors for the fixed cases.
* **Performance Validation**: Previously failing HTTPS sites load without "connection not secured" or "secured connection fail". YouTube and other sites work per policy.
## Next steps
* [Configure HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection) for setup and bypass rules.
* [Import Certificate into Chrome or IE](/use_cases/ssl_inspection/import_certificate_chrome_ie) for client certificate import.
* [Troubleshooting](/troubleshooting/main) for other diagnostic guides.
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
# SSO Authentication Fail
Source: https://docs.safesquid.com/troubleshooting/sso_authentication_fail
Diagnose and resolve SafeSquid sso authentication fail incidents with causes, recovery actions, and audit evidence.
# Fix SSO Authentication Failures
SSO Authentication Fail can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
If your configuration is exactly like **How to** and still your SSO authentication failed. Check out the following:
1. Make sure the **User Name**: is [administrator@safesquid.test](mailto:administrator@safesquid.test) (**User name should be any user from AD having administrative permissions**)
2. Monit service must be Up. Verify it using the command:
```text theme={null}
pidof monit
```
root\@sabproxy:\~# pidof monit 19940
1. As soon as you Save policy by selecting NEGOTIATE\_LDAP\_AUTH **kerberos.sh**\* script will automatically run from path **/usr/local/safesquid/ui\_root/cgi-bin**
a. Verify below files at path\*\*:/usr/local/safesquid/security\*\*
**HTTP.keytab**
**krb5.conf**
**krb.tkt**
b. SafeSquid will create the stub zone for DNS resolution of your Active Directory server.
The file with stub zone will be created with the name: **safesquid.dns.conf**
At path\*\*:/usr/local/safesquid/security/dns\*\*
Run command:
```text theme={null}
cat
safesquid.dns.conf
```
```text theme={null}
-----------------------------------------------------------------------
zone safesquid.test {
type stub;
masters {192.168.221.1;};
};
-----------------------------------------------------------------------
```
Also, it will automatically copy at given path\*\*:/etc/bind/\*\* Run command:
```text theme={null}
cat
safesquid.dns.conf
```
```text theme={null}
-----------------------------------------------------------------------
zone safesquid.test {
type stub;
masters {192.168.221.1;};
};
-----------------------------------------------------------------------
```
Note: Monit service must be up
If any one of the above entries missing you have to repeat all the steps.
First, remove all the given files from the above-given path.
Start monit service and repeat all the steps and capture logs
Command:
```text theme={null}
tail
-F
/var/log/safesquid/native/safesquid.log
```
1. Go to Access Restriction > GLOBAL >> SSO: TRUE
2. ALLOW List: Policy with PAM: TRUE
3. **Testing SSO Auth** a. Go to the Windows machine which joins in the domain of AD e.g windows7.safesquid.test b. Go to the browser and set PROXY as FQDN of the proxy server (sabproxy.safesquid.test) c. Access any website (Authentication prompt should not come) d. Open extended logs
```text theme={null}
tail
-F
/var/log/safesquid/extended/extended.log
```
find [username@SAFESQUID.TEST](mailto:username@SAFESQUID.TEST)@ 192.168.221.212 (IP address of Windows machine which is in the domain)
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [LDAP Entries Not Fetched](/troubleshooting/failed_to_fetch_ldap_entries) to fix LDAP entries that fail to load.
# Troubleshooting
Source: https://docs.safesquid.com/troubleshooting/troubleshooting
Comprehensive diagnostic procedures and resolution guides for common SafeSquid proxy issues, connection failures, and configuration problems
# Diagnose and resolve SafeSquid proxy issues
## Problem
Operators lose productivity when the SafeSquid UI is unreachable, activation fails, clients cannot browse, or policy behaves unexpectedly. Long outages increase security and compliance risk when the proxy is the default egress path.
## Benefits
Symptom-first guides shorten mean time to resolution. Each document lists diagnostics, likely causes, and verification steps aligned to SafeSquid logging and interface paths.
## Advantages
**Confirmed:** Troubleshooting guides map to major SafeSquid subsystems documented in [Getting Started](/getting_started/welcome), [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection), [Authentication](/use_cases/authentication/authentication), [DNS Security](/use_cases/dns_security/dns_security), and [Access Restriction](/use_cases/access_restriction/access_restriction).
## Call to action
Match the failure symptom to a section below and open the linked guide. Execute diagnostics in order, and record log excerpts before escalating to support.
When the UI doesn't load, activation fails, or clients can't reach the proxy, use the documents below. They help you diagnose and fix the problem. Each document covers a symptom area: installation, interface access, SSL, authentication, DNS, connectivity, policy, reporting, and advanced diagnostics. Pick the document that matches your symptom.
## Troubleshooting workflow
Start with the symptom category rather than a subsystem guess. That reduces false leads. A DNS issue can look like a policy issue, and a time-sync issue can look like an authentication failure.
### Installation and access
Use this page together with [Getting Started](/getting_started/welcome) when the product does not install cleanly. Use it also when the web interface is unreachable or activation cannot be completed.
### Identity and SSL
Use [Authentication](/use_cases/authentication/authentication), [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection), and [Supporting Services Monit](/architecture/interface/supporting_services_monit) when user login, certificate trust, or directory-backed access starts failing.
### Performance and stability
Use [Performance Plot](/use_cases/performance_acceleration/performance_plot), [Audit & Forensics](/use_cases/audit_and_forensics/audit_forensics), and [Architecture](/architecture/overview/safesquid_swg) when the proxy becomes slow, unstable, or inconsistent under load.
### Connectivity and policy
Use [Access Restriction](/use_cases/access_restriction/access_restriction), [DNS Security](/use_cases/dns_security/dns_security), [Header Obfuscation](/use_cases/header_rewrite/header_obfuscation), and [Cookie Inspection](/use_cases/cookie_inspection/cookie_inspection). Use them when websites fail to load or behave incorrectly through the proxy.
### Reporting and evidence
Use [Audit & Forensics](/use_cases/audit_and_forensics/audit_forensics), [Reporting Module](/use_cases/audit_and_forensics/reporting_module), and the SafeSquid interface pages when logs, reports, or evidence exports are incomplete.
When failures are broad and not isolated to one control, review [Architecture](/architecture/overview/safesquid_swg), [Audit & Forensics](/use_cases/audit_and_forensics/audit_forensics), and [Supporting Services Monit](/architecture/interface/supporting_services_monit) together. Do this before escalating.
## Advanced diagnostic tools
### [How to use find\_client\_id.sh for getting complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log)
Administrators need advanced diagnostic tools to analyze specific connection issues and obtain detailed logs for troubleshooting complex proxy problems. find\_client\_id.sh provides connection analysis including detailed log extraction, connection tracing, and diagnostic information for specific client connections. Use this document to obtain detailed connection logs and perform connection analysis for complex troubleshooting.
## Next steps
* [Getting Started](/getting_started/welcome) - verify the fix against the basic request flow.
* [Management Console](/architecture/interface/configuration_portal) - review where policy and system settings live.
* [FAQs](/faqs/faqs) - check common questions on installation, licensing, and configuration.
# Login Issues on Specific Websites
Source: https://docs.safesquid.com/troubleshooting/unable_to_login_specific_website
Diagnose and resolve SafeSquid login issues on specific websites incidents with causes, recovery actions, and audit evidence.
# Fix Login Failures on Specific Websites
Login Issues on Specific Websites can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Issues
1. [https://www.facebook.com/](https://www.facebook.com/) is accessible via proxy but login fails.
2. Login to specific websites using Facebook or Google credentials fails via proxy.
3. Login works on [https://www.facebook.com/](https://www.facebook.com/) but fails on [https://accounts.google.com/](https://accounts.google.com/)
4. Login fails on both [https://accounts.google.com/](https://accounts.google.com/) and [https://www.facebook.com/](https://www.facebook.com/)
## Solution
### Case 1: Facebook accessible via proxy but login fails
When [https://www.facebook.com/](https://www.facebook.com/) is accessible via proxy with HTTPS inspection enabled, HTTPS and SSL certificate configuration in the browser are correct. If HTTPS inspection is not configured, follow [Configure HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection). Inability to log in on Facebook usually means the Cookie Filter section is enabled with Global TRUE. Set the policy under Privacy Control > Cookie filter > Deny to Enabled FALSE. Search for "Strip cookies from all connections profiled as NO LOGIN" to find it.
### Case 2: Login fails on a specific website using Facebook or Google credentials via proxy
Confirm the target website is HTTP or HTTPS. For HTTPS, configure the HTTPS Inspection section; follow [Configure HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection). If login to [https://stackoverflow.com/](https://stackoverflow.com/) via Facebook or Google fails, the Elevated Privacy section is likely enabled with Global TRUE. Set the policy under Privacy Control > Elevated Privacy > Elevated policies to Enabled FALSE. Search for "Blocks the third-party cookies" to find it.
### Case 3: Facebook login works but Google account login fails
Login works on [https://www.facebook.com/](https://www.facebook.com/) and other sites but fails only on [https://accounts.google.com/](https://accounts.google.com/). In that case, the corporate policy under Header Filter > Insert is likely enabled. Set the policy under Privacy Control > Header Filter > Insert to Enabled FALSE. Search for "Enforce use of corporate Google Account, for all users who are NOT ALLOWED PERSONAL GOOGLE ACCOUNTS" to find it.
### Case 4: Login fails on both Google and Facebook
Login fails only on [https://accounts.google.com/](https://accounts.google.com/) and [https://www.facebook.com/](https://www.facebook.com/). In that case, the "Block Particular User Login to Facebook or Gmail" policy is likely enabled. Set the policy under Real Time Content Security > Content modifier > Rewrite Policies to Enabled FALSE.
If the global section is enabled but the policy under that section is disabled, that individual policy does not work.
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [SSL Certification Errors](/troubleshooting/ssl_inspection_issues) to fix SSL certificate errors.
# Website Not Accessible
Source: https://docs.safesquid.com/troubleshooting/website_not_accessible
Diagnose and resolve SafeSquid website not accessible incidents with causes, recovery actions, and audit evidence.
# Fix Websites That Are Not Accessible
Website Not Accessible can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Connection failed to proxy or origin
When the user accesses the website, the browser displays "**Connection to 192.168.27.30:80 failed**". A user accesses [https://abc.safesquid.com/](https://abc.safesquid.com/) via proxy and logs in with a corporate email ID. The browser can then show "**Connection to abc.safesquid.com:443 failed**".
![Error showing "Connection to abc.safesquid.com:443 failed"]()
## Possible causes
The destination website can be down, or the user can fail to reach the site because of internet slowness.
### Website or origin unreachable
Check whether the website is opening without proxy configuration inside the browser (No proxy in the middle).
If the website is not opening without a proxy, then it is not the problem with SafeSquid.
If it is opening without a proxy, run the command below. It verifies whether the website is resolving.
```text theme={null}
nslookup
192.168
.27
.30
```
**To check SafeSquid server is connecting to** 192.168.27.30 on port 80
```text theme={null}
telnet
WEBSITE
PORT_TO_CONNECTON
```
When the website cannot be reached, example output:
telnet 192.168.27.30 80
Trying 192.168.27.30...
telnet: Unable to connect to remote host: No route to host
When the website is reachable, the output is:
telnet WEBSITE PORT\_TO\_CONNECTON
When the website cannot be reached:
```text theme={null}
telnet
192.168
.27
.30
80
```
When the website can be reached:
root\@dev:\~# telnet 192.168.27.30 80
Trying 192.168.27.30...
Connected to 192.168.27.30.
Escape character is '^]'.
### On-premises with directory services (conditional DNS)
When the server is in an on-premises environment with directory services, the directory DNS server performs DNS resolution.
Check the configuration on the local internal network. Check its address record on an active directory (AD) or local DNS server.
Run the below commands on the command prompt for **abc.safesquid.com**
```text theme={null}
nslookup abc
.
safesquid
.
com
```
If the website is resolving to the local internal network **e.g.** (10.10.11.78,10.10.128.106)
Configure conditional forwarding to the SafeSquid local caching DNS server.
Go to the path: **/etc/bind/**
and create a file.
```text theme={null}
vim named
.
conf
```
root\@swg:/etc/bind# vim named.conf
// This is the primary configuration file for the BIND DNS server named.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
include "/etc/bind/named.conf.options";
include "/etc/bind/named.conf.local";
include "/etc/bind/named.conf.default-zones";
include "/etc/bind/safesquid.dns.conf";
include "/etc/bind/abc.safesquid.com";
Go to the path
```text theme={null}
cd
/
etc
/
bind
/
```
And create a file
```text theme={null}
vim abc
.
safesquid
.
co
```
Add below lines
```text theme={null}
zone "abc.safesquid.com" {
type forward;
forwarders {10.10.124.101;};
};
```
Command to restart bind9 service:
```text theme={null}
/
etc
/
init
.
d
/
bind9 restart
```
Verify whether the website is resolving to the local IP successfully or not.
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [DNS Failure](/troubleshooting/dns_failure) to fix DNS failures.
# Whitelisted Websites Blocked
Source: https://docs.safesquid.com/troubleshooting/whitelisted_website_blocked
Diagnose and resolve SafeSquid whitelisted websites blocked incidents with causes, recovery actions, and audit evidence.
# Fix Whitelisted Websites That Are Still Blocked
Whitelisted Websites Blocked can interrupt web access, policy enforcement, or evidence collection. Use this runbook to restore service, preserve logs, and prove the corrective action during security review.
## Whitelisted sites still blocked
Company policy blocks the social network category for all employees, but a few social networking sites must be whitelisted. Those sites are added to the whitelist category yet still show a block template. Similarly, after whitelisting the corporate website, employees can still fail to access it.
| Symptom | Likely cause | Resolution | Verification |
| - | - | - | - |
| Whitelisted site still shows block template | Site not in whitelist category; policy order wrong; policy disabled | Add site to whitelist in Categorize Web-sites ; enable default whitelist policy and place above GLOBAL BLOCK | Open site from client; page loads without block |
| Corporate site blocked after whitelist | sscore/categorization not loaded or category not applied | Enable sscore ; add site to whitelist category; ensure policy enabled and above block | Check Categorize Web-sites for site category; retest access |
Note: Whitelist category is the category to allow. Blacklist category is the category to block.
## Enable sscore and add site to whitelist category
Ensure the **sscore** section is enabled and the categorization engine is loaded. Verify from the SafeSquid Statistics page in the interface. See [the Reporting Module](/use_cases/audit_and_forensics/reporting_module). Add the corporate website to the whitelist category from Custom Settings -> Categorize Web-sites in the SafeSquid UI.
## Procedure
1. [Access the SafeSquid interface](/architecture/interface/configuration_portal)
2. Go to configure page
![click on configure in SafeSquid Interface]()
1. Go to the **Categorize Web-sites section under Custom Settings** and search website/domain from the **search for category** option.
2. Modify that website with a whitelist category. (A whitelist is a custom category that is made to allow blocked websites)
![Go to categorize web-sites under custom settings section]()
![enter the website to be whitelisted and click search]()
![Whitelisted website blocked troubleshooting step or policy edit]()
![Modify that website with whitelist category]()
![click on Modify]()
![success message of adding category to the category server]()
1. Go to Access profiles for default policy and verify whether the policy is enabled or not. (Make it enabled)
![Showing the category "whitelist"]()
![Showing the unique name given to the default policy]()
![Making sure this policy is above GLOBAL BLOCK policy and saving it]()
Use Categorize websites to Create and add websites to the "whitelist category".
## Verification and Evidence
* **Interface Checks**: In [Configuration Portal](/architecture/interface/configuration_portal), Custom Settings -> Categorize Web-sites: site shows whitelist category. Restriction Policies -> Access profiles: default whitelist policy is enabled and above GLOBAL BLOCK.
* **Log Analysis**: Access logs show allowed response for the whitelisted URL; no block template or category block for that domain.
* **Performance Validation**: From a client, open the whitelisted site; page loads without block template.
**Related**: [Web Categorization](/use_cases/access_restriction/web_categorization), [Access Restriction](/use_cases/access_restriction/access_restriction), [Reporting](/use_cases/audit_and_forensics/reporting_module), [Troubleshooting](/troubleshooting/main)
## Capture useful evidence
Collect evidence before restarting services or changing policy. Keep screenshots, command output, and relevant SafeSquid logs with the incident ticket.
```sh theme={null}
tail -100 /var/log/safesquid/native/safesquid.log
tail -100 /var/log/syslog
```
Expected result: the native log prints up to 100 recent lines. Each line starts with a date and time, then a `[thread or request id]` and a module name such as `network:`.
Record the affected user, source IP address, requested URL, timestamp, browser error, SafeSquid policy section changed, and verification result.
## Next steps
* Use [Find a complete connection log](/troubleshooting/how_to_use_find_client_id_sh_for_getting_complete_connection_log) to trace a specific client transaction.
* Use [Troubleshooting](/troubleshooting/troubleshooting) for the broader diagnostic checklist.
* Use [Custom Categorization Not Working](/troubleshooting/custom_categorisation_not_working) to fix custom categorization that does not apply.
# Access Mobile Applications Through SafeSquid
Source: https://docs.safesquid.com/use_cases/access_restriction/access_mobile_applications_through_safesquid
Control mobile app internet access through SafeSquid SWG with proxy enforcement and firewall-aware policies.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Route mobile app traffic through SafeSquid proxy
When internet access is allowed only via a proxy, mobile applications must use proxy settings. Set the relevant environment variables or device proxy configuration so traffic goes through SafeSquid.
## Prerequisites
Most of mobile applications will not work without direct Internet connection (Means you have blocked the access to the IP address of the mobile on your firewall/router) to the mobile.
**What is direct INTERNET connection:**
If you are using firewall, then there is an option to block the Internet access to the specific IP addresses.
If you block the Internet connection to the specific IP addresses (which is client IP / Mobile IP addresses), on your firewall then you are unable to access the Internet without setting proxy settings in that client machine(or) mobile device.
By default all devices are allowed to access the Internet
## Working of Mobile Applications with Proxy
If there is no direct Internet access to the mobiles. You configured proxy in the mobile, then some of the applications will work through proxy, as they designed such that to use proxy settings. And some of the applications will not work.
**why?**
Example:
IP of my mobile: 192.168.27.60
**Case 1: Direct Internet Connection Allowed for 192.168.27.60 on my firewall**
In this case it is not possible to block applications through proxy, even though you configured the mobile to use proxy settings and entries were created to block those applications.
Because the applications will not use the proxy settings, they use the direct access to send or receive messages.
**Case 2: Direct Internet Connection Blocked for 192.168.27.60 on my firewall**
In this case it is not possible to allow some of the applications to work with proxy, even though if you configure the proxy settings in the mobile. Because the applications not using proxy and looking for Internet access directly.
:::note
Note: The same scenario is applicable in transparent mode also.
:::
## Next steps
* **[Access Remote Desktop Applications Through SafeSquid](/use_cases/access_restriction/access_remote_desktop_applications_through_safesquid)** - understand how remote desktop applications like AnyDesk, TeamViewer, and AmmyAdmin interact with SafeSquid in different network scenarios and how to effectively block or allow access using HTTPS inspection and access profiles.
* **[Accessing Business Applications Through SafeSquid](/use_cases/access_restriction/accessing_business_applications_through_safesquid)** - troubleshoot and configure SafeSquid to allow business applications by identifying blocked URLs, authentication issues, and SSL inspection requirements.
# Access Remote Desktop Applications Through SafeSquid
Source: https://docs.safesquid.com/use_cases/access_restriction/access_remote_desktop_applications_through_safesquid
Understand how remote desktop applications like AnyDesk, TeamViewer, and AmmyAdmin interact with SafeSquid in different network scenarios and how to effectively block or allow access using HTTPS inspection and access profiles.
# Block or Allow Remote Desktop Apps Through the Proxy
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
## Case 1: There is no direct Internet access to the client Machine
**A)HTTPS ENABLED**
**Any desk** : Any desk is not able to connect to the remote server through proxy.
**Team viewer** : Team viewer is not able to connect to the remote server through proxy.
**AmmyAdmin**: AmmyAdmin is not able to connect to the remote server through proxy.
**B) HTTPS DISABLED :**
**Any desk**: Any desk is able to connect to the remote server through proxy.
**Team viewer**: Team viewer is able to connect to remote the server through proxy.
**AmmyAdmin** : AmmyAdmin is able to connect to the remote server through proxy.
How to block in the above(B) scenario:
1. Enable the default entry in access profiles named as: BLOCK APPLICATIONS (or)
2. Enable HTTPS inspection In the SafeSquid
## **Case 2 : There is a direct Internet access to the client Machine**
**A)HTTPS ENABLED**
**Any desk** : Any desk is able to connect to the remote server (It should not use proxy settings if there is a direct Internet connection).
**Team viewer** : Team viewer is able to connect to the remote server through proxy (It should use proxy settings, but if blocking rules are applied on the proxy, it uses a direct Internet connection, so it is not possible to block team viewer with proxy in direct internet connection ).
**AmmyAdmin** : AmmyAdmin is not able to connect to the remote server through proxy.
**B) HTTPS DISABLED :**
**Any desk** : Any desk is able to connect to the remote server (It is not using proxy settings if there is a direct Internet connection).
**Team viewer** : Team viewer is able to connect to remote the server through proxy.
**AmmyAdmin** : AmmyAdmin is able to connect to the remote server through proxy.
How to block in the above(B) scenario:
1. It is not possible to block Any desk and team viewer with direct Internet connection, because they don't use the proxy settings configured in settings.
2. You can block AmmyAdmin by enabling default entry in Access profiles (or) By enabling HTTPS Inspection.
## Next steps
* **[Allow Anydesk](/use_cases/access_restriction/allow_anydesk)** - allow AnyDesk and other remote desktop apps through SafeSquid with user profiles, SSL bypass, and request-type filters.
* **[Restrict AnyDesk](/use_cases/access_restriction/restrict_anydesk)** - restrict AnyDesk access via SafeSquid policies and proxy configuration for secure network access control.
# Access Restriction
Source: https://docs.safesquid.com/use_cases/access_restriction/access_restriction
Build SafeSquid access policies that make web decisions by identity, destination, time, application, and content so enforcement stays precise and auditable.
# Build precise web access decisions
## Problem statement
Broad allow rules create malware, abuse, and data-loss exposure. Blanket deny rules break legitimate work. Enterprise web policy must decide with more context than IP address alone: who the user is, what application is involved, where traffic is going, when it is happening, and what content is moving.
## Client scenario
Use Access Restriction when you need to:
* allow or block by user, group, destination, category, or application
* apply stricter controls during business hours or for regulated teams
* combine identity, HTTPS visibility, and profiling into one enforcement path
* prove why a request was allowed, denied, or redirected
## Key benefits
SafeSquid access restriction ties enforcement to the rest of the platform:
* [Authentication](/use_cases/authentication/authentication) provides identity and group context
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) provides visibility into encrypted traffic
* profiling engines provide request, response, category, time, and application context
* logs and reporting provide evidence for investigation and audit
That makes policy more precise and easier to defend operationally.
## Prerequisites
### Client-side preparations
* Route client traffic through SafeSquid.
* If policy must apply to HTTPS traffic, deploy the Root CA and enable HTTPS inspection.
### SafeSquid-side setup
* Confirm identity integration if you want user- or group-based policy.
* Define the profiles and categories the access policy will consume.
* Decide your rule order before deployment because top-down policy order affects outcome directly.
## Setup instructions
### Build policy inputs first
Before writing restriction rules, define the signals they will consume:
* authenticated users and groups
* request profiles
* response profiles
* categories
* time or business context
This avoids building access rules that look complete but match nothing useful.
### Create ordered restriction entries
In the Configuration Portal, create access-restriction entries from most specific to most general.
Put business exceptions and critical-deny rules above broad defaults. If a broad rule sits too high, later rules never get a chance to apply.
### Keep the action model explicit
For each restriction entry, document whether it should:
* allow
* deny
* redirect
* apply additional inspection or restriction profiles
Operators should be able to explain the intended outcome without reverse-engineering the entire rule stack.
### Test by realistic user path
Do not validate only with anonymous traffic. Test with the actual user, group, device path, and destination type the rule is meant to govern.
## Verification and validation
### Positive tests
Use at least one test for each intended decision path:
* a user or group that should be allowed
* a user or group that should be denied
* a destination or category that should be blocked
* an application or profile that should trigger special handling
Expected result:
* the rule order produces the intended action
* the applied profiles and filter path are visible in logs
* the user sees the expected allow, deny, or redirect behavior
### Negative tests
Test a nearby but legitimate workflow that should stay allowed.
Expected result:
* the broader restriction rule does not break approved business activity
* exception logic does not leak into unintended users
## Troubleshooting guide
### A rule exists but never seems to apply
Likely causes:
* a higher rule matches first
* the required identity or profile signal is missing
* HTTPS traffic is not being decrypted
Isolation steps:
* review rule order
* confirm authentication and profile assignment
* confirm whether the traffic is visible to SafeSquid
Remediation:
* move the rule higher if appropriate
* fix the missing prerequisite signal
* retest with the same user and destination
### Too much traffic is blocked
Likely causes:
* a broad deny rule sits above a needed exception
* category or profile conditions are too wide
Isolation steps:
* identify the exact rule that triggered
* compare affected users against intended scope
Remediation:
* narrow the matching conditions
* place the approved exception above the broad deny
* retest both blocked and allowed paths
### Policy works for HTTP but not HTTPS
Likely causes:
* HTTPS inspection is not enabled
* bypass logic excludes the traffic from inspection
Isolation steps:
* confirm the request path is decrypted
* inspect whether request or bypass profiles are modifying the flow
Remediation:
* enable the required HTTPS inspection path
* remove or narrow the bypass condition
## Related controls / next steps
* Use [Request Profiles](/use_cases/profiling_engine/request_profiles) and [Response Profiles](/use_cases/profiling_engine/response_profiles) to classify traffic before enforcing policy.
* Use [Web Categorization](/getting_started/core_features/web_categorization) to refine destination-based decisions.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) and [Reporting Module](/use_cases/audit_and_forensics/reporting_module) to prove which rule triggered.
# Accessing Business Applications Through SafeSquid
Source: https://docs.safesquid.com/use_cases/access_restriction/accessing_business_applications_through_safesquid
Troubleshoot and configure SafeSquid to allow business applications by identifying blocked URLs, authentication issues, and SSL inspection requirements.
# Allow Business Applications Through SafeSquid
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
Some business applications stop working once traffic goes through SafeSquid. The steps below identify what is blocking the application and fix it.
There is more than one reason because of why the application may not work through SafeSquid. They can be listed as:
1. The applications may have certain URLs that are getting blocked by SafeSquid. You need to allow those URLs by creating policies so that the application works properly. To identify whether URLs are getting blocked, you need to carefully observe the extended log of SafeSquid by verifying if the status code is '403' (which means blocked) for any of the requests sent by the application. To view the logs, you can run the following command by taking the SSH access of the SafeSquid server:
```bash theme={null}
tail -F /var/log/safesquid/extended/extended.log | grep "192.168.0.17" | grep '403'
```
Where "192.168.0.17" is the IP of the machine accessing the application. You will be displayed with something like the following log line. The status code 403 describes the blocked URLs.
```text theme={null}
"1496477492.50.1.2386.zx5NhVkA9enUdJEC" "50" "1" "03/Jun/2017:13:41:32" "78" "403" "0" "0" "0" "-" "192.168.0.17" "anonymous@192.168.0.17" "GET" https://www.bing.com:80/search?q=porn&qs=n&form=QBLH&sp=-1&pq=porn&sc=0-0&sk=&cvid=ADEF7442BA9A41FEB3857DD679E8124F https://www.bing.com/ "Mozilla"
/5.0 (Windows NT 10.0; WOW64; rv:53.0) Gecko/20100101 Firefox/53.0" "text/html" "Profiles" "-" "192.168.17.1:8080" "TCP_DENIED" "DIRECT" "safesquid" "www.bing.com" "bing.comnp" "www.bing.com" "bing.com" "0" "LUNCH" "ADMINS" "" "Firefox Browser,Browsers,Bing,Search Engine,Bing Search,Bing UnSafe Search" "pornography,searchengines" "" "-" "-" "GLOBAL BLOCK"
```
The logline legend mentioning what each field means is shown below:
"record\_id" "client\_id" "request\_id" "date\_time" "elapsed\_time" "status" "size" "upload" "download" "bypassed" "client\_ip" "username" "method" "url" "http\_referer" "useragent" "mime" "filter\_name" "filtering\_reason" "interface" "cachecode" "peercode" "peer" "request\_host" "request\_tld" "referer\_host" "referer\_tld" "range" "time\_profiles" "user\_groups" "request\_profiles" "application\_signatures" "categories" "response\_profiles" "upload\_content\_types" "download\_content\_types" "profiles"
2. One of the other reasons may be, that you have authentication and/or HTTPS inspection enabled and the application may not support the authentication (Negotiate/Basic) and/or HTTPS inspection. Authentication failure can be verified by observing the logs and checking for a status code of '407' which indicates "Invalid SSO Auth" (if you have enabled Negotiate authentication)
## Next steps
* **[Allow Outlook to Work Through SafeSquid](/use_cases/access_restriction/allow_outlook_to_work_through_safesquid)** - configure SafeSquid and firewall rules so Microsoft Outlook works with proxy authentication and SSL inspection enabled.
* **[Access Mobile Applications Through SafeSquid](/use_cases/access_restriction/access_mobile_applications_through_safesquid)** - control mobile app internet access through SafeSquid SWG with proxy enforcement and firewall-aware policies.
# Allow AnyDesk
Source: https://docs.safesquid.com/use_cases/access_restriction/allow_anydesk
Allow AnyDesk and other remote desktop apps through SafeSquid with user profiles, SSL bypass, and request-type filters.
# Allow AnyDesk Connections Through SafeSquid
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
## Allow remote applications for specific users
When all traffic is blocked for security, some users may need access to remote applications. SafeSquid allows the administrator to permit specific users or groups to access remote applications.
## How it works?
When a user tries to access a remote application, First SafeSquid checks for that user and decides whether this user is allowed to access a remote application or not, if yes then SafeSquid gives access to that user, and before giving the access it will check for user-agent. If access is allowed to both users and the application, then only the user can able to access that application. If the user **Samidha wants access** to the XYZ application but is trying to access the **ABC** application, SafeSquid will block to user Samidha.
```mermaid theme={null}
flowchart TB
User[User request]
CheckUser[Check user allowed]
CheckApp[Check application]
Allow[Allow]
Block[Block]
User --> CheckUser
CheckUser -->|no| Block
CheckUser -->|yes| CheckApp
CheckApp -->|no| Block
CheckApp -->|yes| Allow
```
:::note
Remote applications like Anydesk® and Ammyadmin™ do not support SSO authentication. If SSO authentication is enabled, bypass it for these applications.
:::
Remote applications like **Remote desktop applications, Download managers**, etc. (Anydesk and Teamviewer®) should get automatically blocked if HTTPS inspection is enabled. No need to configure any policy for blocking purposes.
## [Access the SafeSquid interface](/architecture/interface/configuration_portal)
## Go to configure page
![Go to configure page to Allow anydesk]()
## Go to Real-time content security: HTTPS Inspection
![Select HTTPS Inspection option in Real time content security section to Allow anydesk]()
![Enabled Global section as true to allow anydesk]()
![Bypass SSL inspection by editing policy in Inspection policy section]()
![Select enabled as true of Bypass SSL Inspection policy to allow anydesk]()
![Save Bypass SSL Inspection policy to allow anydesk]()
## Go to Restriction Policies
![Select Access profiles in Restriction policies section to allow anydesk]()
![Default Restrict remote desktop application policies present in policies and profiles section]()
![Edit one of clone policy in policies and profile section to allow anydesk]()
![Edit and entry comment and request type in policy to allow anydesk]()
![Select Bypass SSL Inspection in added profiles section to allow anydesk]()
![Save Allow anydesk policy]()
![Save configuration of policy to allow anydesk]()
## Configuration on Anydesk®
### Set proxy on Anydesk application
If authentication is enabled, specify the username and password in the AnyDesk application. AnyDesk does not use system proxy settings automatically. Configure the proxy in the AnyDesk application. AnyDesk and Ammyadmin do not support SSO; bypass SSO for them if enabled.
### Create policy without application signature
Remote applications may already exist in SafeSquid Application Signatures. Check whether the application is categorized first.
If an application is not categorized under default Application Signatures, find the User-agent using SafeSquid's extended logs or any other traffic-capturing tool.
### Add that User-agent or website into request types
Bind that created user group and Request Type in Access Profiles and decide whether to block or allow.
## Verification and Evidence
* **Interface Checks**: In [Configuration Portal](/architecture/interface/configuration_portal), confirm Real-time content security → HTTPS Inspection has Bypass SSL Inspection policy enabled, and Restriction Policies → Access profiles show the allow policy for the remote desktop application with the correct request type and Bypass SSL Inspection profile.
* **Log Analysis**: SafeSquid access logs should show successful CONNECT or requests for the remote app when allowed. Blocked attempts appear with deny or policy response codes.
* **Performance Validation**: From an allowed user and device, launch [AnyDesk](https://anydesk.com/) (or the configured app) with proxy set; connection should succeed. From a non-allowed user or app, access should be blocked.
**Related**: [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection), [Access Restriction](/use_cases/access_restriction/access_restriction), [Architecture](/architecture/overview/safesquid_swg), [Restrict AnyDesk](/use_cases/access_restriction/restrict_anydesk), [Troubleshooting](/troubleshooting/troubleshooting)
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
* **[Access Restriction](/use_cases/access_restriction/access_restriction)** - build SafeSquid access policies that make web decisions by identity, destination, time, application, and content so enforcement stays precise and auditable.
# Allow Outlook to Work Through SafeSquid
Source: https://docs.safesquid.com/use_cases/access_restriction/allow_outlook_to_work_through_safesquid
Configure SafeSquid and firewall rules so Microsoft Outlook works with proxy authentication and SSL inspection enabled.
# Allow Outlook Through the SafeSquid Proxy
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
## Problem: Outlook fails when proxy authentication or SSL inspection is enabled
MS Outlook often fails when SafeSquid has authentication (Negotiate or Basic) and/or SSL inspection enabled. SafeSquid is typically deployed behind a firewall that allows only ports 80 and 443; other traffic is blocked. Outlook uses not only HTTP/HTTPS but also SMTP(S), IMAP(S), POP(S), DNS (UDP), and LDAP (389, 636). Blocking those ports or failing to allow them through the firewall breaks Outlook.
Outlook supports proxy authentication (Negotiate and Basic) and SSL negotiation with a certificate deployed in Internet Explorer. The fix is to allow the necessary Outlook-related traffic (mail, DNS, LDAP, etc.) in the firewall or on the SafeSquid server and block the rest.
## Key benefits
Outlook works through SafeSquid with authentication and SSL inspection enabled. Mail flow continues without weakening proxy policy. Administrators can use iptables on the SafeSquid server or configure the organization firewall to allow the required ports.
## Prerequisites
* SafeSquid with authentication and/or SSL inspection enabled.
* Root or sufficient privilege to configure iptables on the SafeSquid server, or access to the organization firewall to allow the ports listed below.
## Call to action
The findings in allowing the Outlook traffic using the iptables rules are shown below:
This rule is to allow the established incoming connections to the server
```bash theme={null}
iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
```
This rule is to allow the loopback connections to the server
```bash theme={null}
iptables -A INPUT -i lo -m comment --comment "Allow loopback connections" -j ACCEPT
```
This rule is to allow the incoming ping requests to the server
```bash theme={null}
iptables -A INPUT -p icmp -m comment --comment "Allow Ping to work as expected" -j ACCEPT
```
This rule is to allow the incoming connections on the following ports to the server, 22(SSH), \*\*25(SMTP), 53(DNS), 110(POP), 389(LDAP), 587(SMTPS), 636(LDAPS), 953(RNDC), 993(IMAPS), 995(POP3S)
```bash theme={null}
iptables -A INPUT -p tcp -m multiport --dports 22,25,53,110,389,465,587,636,953,993,995 -j ACCEPT
```
This rule is to allow the incoming connections on the following ports to the server, 1023(Reserved), \*\*3268(MSGC), 3269(MSGCS), 5222(XMPP client connections), 5269(XMPP server-to-server), 5280(XMPP over synchronous HTTP), 8080(SafeSquid port)
```bash theme={null}
iptables -A INPUT -p tcp -m multiport --dports 1023,3268,3269,5222,5269,5280,8080 -j ACCEPT
```
:::note
Note that both the above rules are one and the same excepting the ports. iptables will not allow us to add all the above-mentioned ports at one go, which is the reason to separate them into two rules
:::
This rule is to allow the incoming UDP connections to the server on the following ports, 53(DNS), 953(RNDC)
```bash theme={null}
iptables -A INPUT -p udp -m multiport --dports 53,953 -j ACCEPT
```
This rule is to allow the established outbound connections from the server
```bash theme={null}
iptables -A FORWARD -m state --state RELATED,ESTABLISHED -j ACCEPT
```
This rule is to allow the loopback connections from the server
```bash theme={null}
iptables -A FORWARD -i lo -m comment --comment "Allow loopback connections" -j ACCEPT
```
This rule is to allow the ping outside from the server
```bash theme={null}
iptables -A FORWARD -p icmp -m comment --comment "Allow Ping to work as expected" -j ACCEPT
```
This rule is to allow the connections on the following ports from the server, 22(SSH), 25(SMTP), **53(DNS), 110(POP), 389(LDAP), 587(SMTPS), 636(LDAPS), 953(RNDC), 993(IMAPS), 995(POP3S)
iptables -A FORWARD -p tcp -m multiport --dports 22,25,53,110,389,465,587,636,953,993,995 -j ACCEPT**
This rule is to allow the connections on the following ports from the server, 1023(Reserved), 3268(MSGC), 3269(MSGCS), 5222(XMPP client connections), 5269(XMPP server-to-server), 5280(XMPP over synchronous HTTP), 8080(SafeSquid port)\*\*
iptables -A FORWARD -p tcp -m multiport --dports 1023,3268,3269,5222,5269,5280,8080 -j ACCEPT\*\*
This rule is to allow the UDP connections from the server on the following ports 53(DNS), 953(RNDC)
```bash theme={null}
iptables -A FORWARD -p udp -m multiport --dports 53,953 -j ACCEPT
```
This rule is to DROP the remaining input traffic to the server
```bash theme={null}
iptables -P INPUT DROP
```
This rule is to drop the forward output traffic from the server
```bash theme={null}
iptables -P FORWARD DROP
```
The above iptables rules are enough for Outlook to work in an environment where authentication and/or SSL inspection in SafeSquid are enabled.
## Next steps
* **[Accessing Business Applications Through SafeSquid](/use_cases/access_restriction/accessing_business_applications_through_safesquid)** - troubleshoot and configure SafeSquid to allow business applications by identifying blocked URLs, authentication issues, and SSL inspection requirements.
* **[Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection)** - prerequisites, certificate generation, enabling SSL inspection, client certificate import, bypass rules, and verification for SafeSquid HTTPS inspection.
# Allow Remote Applications to Particular Users
Source: https://docs.safesquid.com/use_cases/access_restriction/allow_remote_applications_to_particular_users
Allow specific users to access remote applications via SafeSquid policies, including without application signatures.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Allow specific users to access remote applications
When traffic is blocked by default, some users may need access to remote applications. SafeSquid can allow specific users or groups to access remote applications while keeping the default block for others.
## How it works
When a user tries to access remote application software, First SafeSquid checks for that user and decides whether this user is allowed to access the remote application or not, if yes then SafeSquid gives access to that user, and before giving the access it will check for user-agent or website which you added in Custom Settings > Request types section. If access is allowed to both users and the application, then only the user can able to access that application. If the user **Samidha wants access** to the **XYZ** application but is trying to access the **ABC** application, SafeSquid will block the user Samidha.
## How to Allow Remote Applications?
Follow the Link: [Allow anydesk](/use_cases/access_restriction/allow_anydesk)
## How to create policy without Application Signature
1. Remote applications are already categorized in the SafeSquid Application Signatures. First, you need to check whether the Application is categorized or not.
2. If the application is not categorized under default Application Signatures, find the User-agent using SafeSquid's extended logs or any other traffic-capturing tool.
3. Add that User-agent or website into Request Types.
4. Bind that created user group and Request Type in Access Profiles and decide whether to block or allow
## Next steps
* **[Allow Anydesk](/use_cases/access_restriction/allow_anydesk)** - allow AnyDesk and other remote desktop apps through SafeSquid with user profiles, SSL bypass, and request-type filters.
# Allow Social Networking Sites During Lunch Hours
Source: https://docs.safesquid.com/use_cases/access_restriction/allow_social_networking_sites_during_lunch_hours
Allow social networking access during lunch hours via SafeSquid time profiles while keeping productivity controls.
# Allow Social Media During Lunch Hours
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
## Problem: Social networking access must be bounded by time
Unrestricted social networking during work hours can reduce productivity and create policy risk. Many organizations block social networking on network computers. Some organizations allow access during lunch or defined windows to balance productivity and morale. SafeSquid time profiles allow social networking sites only during configured hours (e.g. lunch); outside that window access is blocked.
## Key benefits
Social networking is allowed only during the configured time window. Outside that window users receive a block template. Administrators set the LUNCH (or custom) time profile once; policy applies consistently. Productivity controls remain while offering limited access.
## Prerequisites
* [HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection) enabled in SafeSquid.
* SScore section enabled as TRUE (Application setup → Score).
* Access to [SafeSquid Configuration Portal](/architecture/interface/configuration_portal).
## Call to action
![Select Configure section to allow social networking sites in lunch hours]()
Open the Search icon (bottom right of SafeSquid Web GUI) to search by keyword or profile name.
![View default policies under policies and profiles]()
## Search default policy: LUNCH.
Enter **LUNCH** in the value field of the search dialog and click Search.
![Search for default policy Lunch]()
The default policy for the **LUNCH** profile appears in the Time Profile section.
## Go to Time Profiler
Open the default policy from the Time Profiler section having a **LUNCH** profile.
![Open the default policy from Time Profiler section having LUNCH profile]()
### Edit LUNCH policy
Set the lunch time (Hour Range and Minute Range) and save the policy.
![Modify lunch time (Hour Range and Minute Range) and save the policy]()
Also, ensure the Global part of the Time Profiler Section is Enabled with TRUE.
![Global part of Time Profiler Section is Enabled with TRUE to allow social networking sites in lunch hours]()
By default, Global Part of Time Profiler is FALSE.
![Save the policy after making Global part of Time Profiler as TRUE.]()
Save the policy after making Global part of Time Profiler as TRUE.
![Save the policy after making Global part of Time Profiler as TRUE.]()
## Go to Access Profiles
Open Access Profiles from the Restriction Policies side menu.
![Open Access Profiles from Restriction Policies side menu to allow social networking sites in lunch hours]()
### Create new policy
Create a new policy under the Access Profiles section for incorporation of the default **LUNCH** profile from the Time Profiler section.
![Create new policy under Access Profiles section for incorporation of default LUNCH profile from Time Profiler section.]()
Select the default Category **Socialnetworks** from the Categories Field.
![Select the default Category Socialnetworks from Categories Field.]()
Select **ALLOW** in the Action field to allow **Social Networking sites** during lunch hours.
![Select ALLOW in Action field to allow Social Networking sites in lunch hours.]()
Specify a unique profile name in the Added Profiles field (e.g. **SOCIAL NETWORKING SITE**).
Click on the top right Icon to save the policy.
![Specify unique profile name inside Added Profiles field and click on top right Icon to save the policy.]()
## Verification and Evidence
* During the configured lunch window: access a social networking site; access is allowed.
* Outside the lunch window: access a social networking site; the **BLOCK** template appears.
* **Interface:** Time Profiler shows LUNCH with the correct hour/minute range. Access Profiles shows the policy with Category Socialnetworks, Action ALLOW, and the added profile. Global for Time Profiler is TRUE.
## Troubleshooting
| Issue | Resolution |
| - | - |
| Social sites always blocked | Ensure Global (Time Profiler) is TRUE. Confirm the LUNCH hour/minute range includes the current time. Confirm Access Profile has Action ALLOW and Category Socialnetworks. |
| Social sites always allowed | Check policy order; a later ALLOW may override. Confirm the time profile is applied to the Access Profile and the range is correct. |
## Next steps
* **[Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection)** - prerequisites, certificate generation, enabling SSL inspection, client certificate import, bypass rules, and verification for SafeSquid HTTPS inspection.
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Allow Specific YouTube Channel and its Playlist
Source: https://docs.safesquid.com/use_cases/access_restriction/allow_specific_youtube_channel_and_its_playlist
Block general YouTube but allow specific channels and playlists in SafeSquid for education.
# Allow a Specific YouTube Channel and Its Playlists
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
## Client Scenario
Ganpat University provides graduate programs to various colleges. Ganpat University distributes the internet to its students. Ganpat University wants to block entire [www.youtube.com](http://www.youtube.com) for their students. But wants some of the YouTube channels allowed which are helpful for students.
Ganpat University's challenges are:
All Students should not be allowed to access [www.youtube.com](http://www.youtube.com). If any student tries to access YouTube, the student receives a blocked template.
Only a few of the specified YouTube channels and their playlists should be allowed. This YouTube channel contains educational and knowledge-sharing videos.
## Solution
You can achieve this by creating a policy in the Request Profiles Section and binding it with policies in the Access Profiles Section.
## Prerequisites
HTTPS Inspection should be enabled in SafeSquid. If not enabled, refer to the document - [How to enable HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection).
You need the YouTube **Channel-ID** and **List-ID** of the playlist you want to allow. You have to extract the Channel-ID and List-ID of the playlist from the YouTube URL before creating rules in SafeSquid.
## Channel-ID and List-ID Extraction
### Extract Channel-ID from YouTube channel
1. Open the YouTube channel to allow. This example uses the CBT Nuggets channel. The **Channel-ID** appears in the referrer URL as the portion after **'channel/'**. Save it for reference.
CBT Nuggets Channel URL: [https://www.youtube.com/channel/UClIFqsmxnwVNNlsvjH1D1Aw](https://www.youtube.com/channel/UClIFqsmxnwVNNlsvjH1D1Aw)
**Channel-ID: UClIFqsmxnwVNNlsvjH1D1Aw**
Select any playlist of the channel and click **PLAY ALL**. This example uses the **CBT Nuggets Webinars** playlist.
![Extract Channel-ID from YouTube Channel to Allow Specific YouTube Channel and its Playlist]()
2. You can extract List-ID from the selected playlist.
**List-ID** is the preceding portion of the URL after the **'\&list='** part. Save this part on a notepad for reference.
This example uses the playlist **CBT Nuggets Webinars**, whose URL is [https://www.youtube.com/watch?v=PcB0j6uBJCA\&list=PLQVJk9oC5JKo\_bMWae3xsavpPMKAzIeGb](https://www.youtube.com/watch?v=PcB0j6uBJCA\&list=PLQVJk9oC5JKo_bMWae3xsavpPMKAzIeGb)
Extracted **List-ID: PLQVJk9oC5JKo\_bMWae3xsavpPMKAzIeGb**
![Extract List-ID from YouTube Channel to Allow Specific YouTube Channel and its Playlist]()
Every video in the playlist URL contains the same List-ID.
URL for next video in CBT Nuggets Webinars playlist: [https://www.youtube.com/watch?v=q802E2jsByI\&list=PLQVJk9oC5JKo\_bMWae3xsavpPMKAzIeGb\&index=2](https://www.youtube.com/watch?v=q802E2jsByI\&list=PLQVJk9oC5JKo_bMWae3xsavpPMKAzIeGb\&index=2)
**List-ID: PLQVJk9oC5JKo\_bMWae3xsavpPMKAzIeGb**
![Verify List-ID from YouTube Channel to Allow Specific YouTube Channel and its Playlist]()
## Policy Creation
### Create policy in Request Types section
3. After extracting Channel-ID and List-ID, create policies in SafeSquid.
Go to SafeSquid Web-GUI and click on Configure to create Policies.
![Click on Configure to create policy that will allow Specific YouTube Channel and its Playlist]()
4. Click on Custom Settings to open the Request Types Section.
![Click on Custom Settings to open Request Types Section to allow Specific YouTube Channel and its Playlist]()
5. Click on the Request Types Section to create the policy.
![Click on Request Types Section to create the policy to allow Specific YouTube Channel and its Playlist]()
6. Make sure the Global of Request Types Section is Enabled to True.
![Select Global of Request Types Section is Enabled to True to Allow Specific YouTube Channel and its Playlist]()
7. Click on the Request Types tab to create a new policy.
![Click on Request Types tab to create new policy to Allow Specific YouTube Channel and its Playlist]()
8. Insert appropriate comments for future use.
![Insert appropriate comment for future use that describe policy of Allow Specific YouTube Channel and its Playlist]()
9. Select **YouTube** Channels in the Request Types field.
![Select YouTube Channels in Request Types field to Allow Specific YouTube Channel and its Playlist]()
10. Add Channel-ID and List-ID in the File field and save the policy. Use the values saved earlier. For the CBT Nuggets channel example, use **(UClIFqsmxnwVNNlsvjH1D1Aw|PLQVJk9oC5JKo\_bMWae3xsavpPMKAzIeGb)** in the File field.
![add Channel-ID and List-Id in File Field and Save the policy to Allow Specific YouTube Channel and its Playlist]()
11. Create new Request Types as **NUGGET CHANNEL** in the Added Request Types Field.
![Create new Request Types as NUGGET CHANNEL in Added Request Types Field to Allow Specific YouTube Channel and its Playlist]()
12. Save the Policy Created in the Request Types Section.
![Save the Policy Created in Request Types Section to Allow Specific YouTube Channel and its Playlist]()
### Create policy in Access Profiles section
13. Go to the Access Profiles section to bind with Profiles.
![Select Access Profiles section to bind with Profiles to Allow Specific YouTube Channel and its Playlist]()
14. Edit these two default policies with the profile name **BLOCK YOUTUBE CHANNEL** as shown below.
:::note
Create two new policies instead of modifying the default policies if preferred.
:::
![Edit these two default policies with profiles name BLOCK YOUTUBE CHANNEL to Allow Specific YouTube Channel and its Playlist]()
15. Edit the 1st, Policy. Set Enabled to TRUE and Save the Policy.
![Edit one out of two default policy as True with profiles name BLOCK YOUTUBE CHANNEL to Allow Specific YouTube Channel and its Playlist]()
16. Edit the 2nd, Policy. Set this policy Enabled to TRUE.
![Edit second one out of two default policy as True with profiles name BLOCK YOUTUBE CHANNEL to Allow Specific YouTube Channel and its Playlist]()
17. Insert appropriate comments for future use.
![Insert appropriate comment for future use in policy which made to allow Specific YouTube Channel and its Playlist]()
18. Select **NUGGET CHANNEL** in the Request Types field (created in Step 10). Save the policy.
![Select NUGGET CHANNEL in Request Types field in policy that allow Specific YouTube Channel and its Playlist]()
19. After saving, verify the modified policies to confirm they were created correctly.
![saving to confirm whether its created properly or not policy that allow Specific YouTube Channel and its Playlist]()
## Test the Scenario
Now try to open videos other than the CBT Nuggets Webinars playlist of the YouTube Channel CBT Nuggets.
All the other videos will be blocked and the below template will be shown.
![Test policy that Allow Specific YouTube Channel and its Playlist]()
You can check the videos from the CBT Nuggets Webinars playlist of the CBT Nuggets channel. Only these videos will be allowed.
:::note
This configuration will work only for videos sourced from the channel page and not from the feeds links or YouTube Videos embedded in website.
To allow all the videos of any specific YouTube Channel you have to insert List-ID's (of every playlist in that channel) and file part (of each individual unlisted video) of the URL in the File field of the Request Types Section.
:::
## Next steps
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
# Block Particular User Login to Facebook or Gmail
Source: https://docs.safesquid.com/use_cases/access_restriction/block_particular_user_login_to_facebook_or_gmail
Block specific users from logging into Facebook or Gmail via SafeSquid for controlled organizational access.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Block specific users from logging into Facebook or Gmail
Restrict which users can log into Facebook or Gmail; only selected users can log in; all others are blocked.
## Prerequisites
HTTPS Inspection should be enabled in SafeSquid. If not enabled, see the document - [How to enable HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection).
## [Access the SafeSquid User Interface](/architecture/interface/configuration_portal)
![click on configure in SafeSquid interface]()
## Go to Search
![click on search in access profiles section]()
## Search policy: "BLOCK PARTICULAR USER LOGIN"
![search for " BLOCK PARTICULAR USER LOGIN " default policy]()
## Go to Content Modifier: Rewrite Policies
![showing search results for "BLOCK PARTICULAR USER LOGIN " in Content modifier section]()
![click on content modifier from the sidebar under Real Time content Security]()
## Ensure Global Section with Enabled TRUE
![ensuring the global section set as true]()
![selecting true in global if it is set to false]()
![click on submit to save the policy]()
## Go to Rewrite Policies and make it Enable
![going in "Rewriting policies " to enable "BLOCK PARTICULAR USER LOGIN" policy]()
![editing the policy]()
![setting true value in enabled]()
## Enter Username inside Pattern
![entering the desired username pattern]()
![click on save to save the policy]()
## Search policy: "BLOCK PARTICULAR USER LOGIN"
![searching for policy "BLOCK PARTICULAR USER LOGIN "]()
## Go to Access Profiles to Enable
![going to access profile to enable the policy]()
![clicking on edit policy to edit the policy]()
![selecting true to enable it]()
![save the policy]()
## To test
Go to Facebook and Login
Try login to your Facebook account it will show you the below page:
![testing the policy]()
### Go to Gmail and login
Try login to your Gmail account it will show you the below page:
![testing the policy by login]()
## Next steps
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Block Specific YouTube Channel
Source: https://docs.safesquid.com/use_cases/access_restriction/block_specific_youtube_channel
Block a specific YouTube channel using SafeSquid by creating policies based on Channel-ID and List-ID for targeted video restriction.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Block one YouTube channel while allowing other content
Block access to specific YouTube channels (e.g., T-Series) while allowing other YouTube content.
:::note
Blocking specific YouTube channels while allowing other videos is a common policy need. The steps below demonstrate blocking a specific channel and its playlist videos.
:::
## Prerequisites
* HTTPS Inspection must be enabled in SafeSquid. See [How to enable HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection).
* Extract the YouTube **Channel-ID** and **List-ID** from the target channel URL
## Extract Channel-ID and List-ID
1. Open the YouTube channel to block (e.g., T-Series).
2. Extract the **Channel-ID** from the URL (the portion after `channel/`):
* URL: `https://www.youtube.com/channel/UCq-Fj5jknLsUf-MWSy4_brA`
* **Channel-ID:** `UCq-Fj5jknLsUf-MWSy4_brA`
![Extract Channel-ID from YouTube Channel]()
3. Click **PLAY ALL** on the channel page to access a playlist.
4. Extract the **List-ID** from the playlist URL (the portion after `&list=`):
* URL: `https://www.youtube.com/watch?v=IgKdXLfxgQQ&list=PL9bw4S5ePsEE2KMw53rY40A00t4I-otqy`
* **List-ID:** `PL9bw4S5ePsEE2KMw53rY40A00t4I-otqy`
![Extract List-ID from YouTube Channel]()
![List-ID in subsequent videos]()
## Create Request Types Policy
5. Open SafeSquid WebGUI and click **Configure**.
![SafeSquid Configure section]()
6. Click **Custom Settings** to open the Request Types section.
![Custom Settings menu]()
7. Ensure the **Global** setting in Request Types is set to **True**.
![Enable Global Request Types]()
8. Click the **Request Types** tab to create a new policy.
![Request Types tab]()
9. Create a new Request Profile named **T-SERIES CHANNEL** in the Added Request Types field.
![Create T-SERIES CHANNEL profile]()
10. Add the Channel-ID and List-ID to the **File** field using the format:
```text theme={null}
(UCq-Fj5jknLsUf-MWSy4_brA|PL9bw4S5ePsEE2KMw53rY40A00t4I-otqy)
```
Save the policy.
![Add Channel-ID and List-ID]()
## Create Access Profiles Policy
11. Navigate to the **Access Profiles** section.
![Access Profiles section]()
12. Edit the default policy **BLOCK YOUTUBE CHANNELS**:
* Select **T-SERIES CHANNEL** in the Request Types field
* Set Action to **DO\_NOT\_BYPASS**
![Configure Access Profile]()
13. Save the policy.
![Save policy]()
## Verification and Evidence
14. Access the T-Series channel URL: `https://www.youtube.com/channel/UCq-Fj5jknLsUf-MWSy4_brA`
The channel displays the Access Blocked template.
![Channel blocked]()
15. Access any T-Series playlist video to confirm blocking.
![Playlist video blocked]()
:::note
This configuration blocks videos accessed from the channel page only. Videos from feed links or embedded YouTube videos are not blocked.
To block all videos from a channel, add all playlist List-IDs and individual video file portions to the Request Types File field.
:::
## Next steps
* [Allow Specific YouTube Channel and Its Playlist](/use_cases/access_restriction/allow_specific_youtube_channel_and_its_playlist) to allow only approved channels.
* [Access Restriction](/use_cases/access_restriction/access_restriction) for policy and profile configuration.
# Compliance Templates
Source: https://docs.safesquid.com/use_cases/access_restriction/compliance_templates
Pre-configured DLP patterns for PCI-DSS, HIPAA, GDPR, and other regulatory compliance requirements using SafeSquid Text Analyser.
# Apply Compliance Templates for Regulated Data
Uncontrolled exfiltration of cardholder data, PHI, or PII creates regulatory exposure, investigation burden, and reputational harm. SafeSquid Text Analyser supports pattern-based detection for PCI, HIPAA, GDPR, and custom data. Use these templates as a starting point for detection and enforcement, not as a substitute for a full compliance program.
## Problem: Sensitive data in transit requires detection for compliance
Organizations must detect and control sensitive data in web traffic to meet PCI-DSS, HIPAA, GDPR, and similar requirements. Failure to detect cardholder data, PHI, or PII in transit creates regulatory and legal risk. SafeSquid Text Analyser supports pattern-based detection so administrators can block or log matches and demonstrate control operation to auditors.
## Key benefits
Pre-built patterns reduce implementation time for PCI-DSS, HIPAA, GDPR, and similar programs. Organizations can show auditors configured detection rules and logs of matches or blocks. Combine templates with [Access Restriction](/use_cases/access_restriction/access_restriction) to block, log, or alert on matches after tuning.
## Prerequisites
* HTTPS inspection enabled so SafeSquid can inspect request/response body content. See [Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection).
* Access to Configure → Real time content security → Text analyzer in the Configuration Portal.
* Decision on which regulations apply and which data types to protect (assess before configuring).
## Pre-built patterns for regulatory requirements
SafeSquid's Text Analyser supports pattern-based detection of sensitive data. Use the sections below as starting points for PCI-DSS, HIPAA, GDPR, and other regulatory requirements.
:::note
These templates provide detection patterns only. They do not by themselves make an environment compliant. Combine them with [Access Restriction](/use_cases/access_restriction/access_restriction), HTTPS inspection, logging, governance, retention, and review processes.
:::
## PCI-DSS (Payment Card Industry)
Detect credit card numbers, CVV codes, and cardholder data in transit.
### Credit Card Number Patterns
| Card Type | Pattern (Regex) | Example |
| - | - | - |
| Visa | `4[0-9]{12}(?:[0-9]{3})?` | 4111111111111111 |
| Mastercard | `5[1-5][0-9]{14}` | 5500000000000004 |
| American Express | `3[47][0-9]{13}` | 340000000000009 |
| Discover | `6(?:011\|5[0-9]{2})[0-9]{12}` | 6011000000000004 |
| All Major Cards | `(?:4[0-9]{12}(?:[0-9]{3})?\|5[1-5][0-9]{14}\|3[47][0-9]{13}\|6(?:011\|5[0-9]{2})[0-9]{12})` | — |
### Configuration Example
1. Navigate to **Configure → Real time content security → Text analyzer**
2. Add a new policy with:
* **Comment:** PCI-DSS Credit Card Detection
* **Mime type:** `text/.*|application/json|application/xml`
* **Keyword(s):** `(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13})`
* **Score:** 100
3. Set **Threshold** to 100 to block on first match
### Additional PCI Patterns
| Data Type | Pattern |
| - | - |
| CVV/CVC | `\b[0-9]{3,4}\b` (use with context) |
| Expiry Date | `(0[1-9]\|1[0-2])\/([0-9]{2}\|[0-9]{4})` |
| Track Data | `%B[0-9]{13,19}\^[A-Z\s]{2,26}\^[0-9]{4}` |
***
## HIPAA (Healthcare)
Detect Protected Health Information (PHI) including medical record numbers, SSNs, and health-related terms.
### Social Security Number
| Format | Pattern |
| - | - |
| With dashes | `[0-9]{3}-[0-9]{2}-[0-9]{4}` |
| Without dashes | `(?
## Go to Real time content security
![Select HTTPS Inspection option in Real time content security section to Restrict anydesk]()
![Enabled Global section as true to restrict anydesk and to edit Inspection policy]()
![Enabled Global section as true to restrict anydesk and to edit Inspection policy]()
![Select Access profiles in Restriction policies to access default policies to restrict any desk]()
![Default Restrict remote desktop application policies present in policies and profiles section]()
![Edit one of clone policy in policies and profile section to restrict anydesk]()
![Edit and entry comment and request type in policy to restrict anydesk]()
![Save Restrict anydesk policy]()
![Save configuration of policy to restrict anydesk]()
## Configuration on anydesk
Set proxy on anydesk application
If authentication is enabled you have to specify Username and Password on any desk application.
Anydesk should not take auto proxy settings: If you set proxy in IE browser or chrome browser and you select "Try to detect the proxy server" option on anydesk, it should not take proxy automatically. You must have to configure proxy on anydesk application.
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Enforce SafeSearch
Source: https://docs.safesquid.com/use_cases/access_restriction/safesearch
Enforce SafeSearch on Google, Yahoo, and Bing through SafeSquid so users cannot disable search-result filtering locally.
# Keep search filtering enforced at the proxy
## Problem statement
Search engines can expose explicit or otherwise inappropriate results even when the destination itself is not blocked. Relying on users to keep SafeSearch enabled is not operationally safe because the setting can be changed locally in a few clicks.
## Client scenario
Use this control when you need to:
* enforce safer search results for schools, shared terminals, or supervised user groups
* prevent users from disabling SafeSearch locally
* keep search-result filtering active on major search engines without depending on endpoint settings
## Key benefits
SafeSquid can enforce SafeSearch centrally for supported search engines so the proxy, not the user, controls the setting. That reduces policy drift and makes acceptable-use enforcement easier to maintain across many devices.
## Prerequisites
### Client-side preparations
* Ensure client search traffic passes through SafeSquid.
* If search traffic uses HTTPS, deploy the SafeSquid Root CA to relevant clients.
### SafeSquid-side setup
* Enable [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) because major search engines use HTTPS.
* Confirm the default SafeSearch-related rules are present in the existing SafeSquid policy set.
## Setup instructions
### Enable HTTPS visibility first
SafeSearch enforcement on encrypted search traffic depends on HTTPS inspection. If SafeSquid cannot inspect the search request, it cannot override the user preference safely.
### Enable the SafeSearch policies
SafeSquid includes default rules to enforce SafeSearch for:
* Google
* Yahoo
* Bing
Enable the relevant SafeSearch policies in the policy and profile sections if they are currently disabled.
### Use proxy enforcement instead of browser trust
Do not rely on browser-side settings alone. Users can disable SafeSearch in the search engine or browser interface. But proxy-enforced rules keep the safer setting active regardless of local preference.
### Understand the Google behavior
Google SafeSearch enforcement works by ensuring the safe-search parameter remains active in the request path. The existing SafeSquid rules handle that centrally, which is why HTTPS inspection and correct policy application both matter.
## Verification and validation
### Positive tests
For each supported search engine:
1. perform a test query that would normally surface explicit results
2. confirm the search engine returns filtered results
3. try disabling SafeSearch in the user interface and repeat the test
Expected result:
* filtered mode remains enforced
* user-side changes do not override the proxy decision
### Negative tests
Use a normal business or educational search query.
Expected result:
* ordinary search remains usable
* enforcement does not break general search functionality
## Troubleshooting guide
### Users can still disable SafeSearch
Likely causes:
* HTTPS inspection is not enabled
* the SafeSearch policy exists but is disabled
* the traffic is bypassing the expected inspection path
Isolation steps:
* confirm the search session is decrypted
* confirm the SafeSearch policy is enabled
* verify the request passes through the intended SafeSquid policy path
Remediation:
* enable or restore HTTPS inspection
* enable the SafeSearch rules
* retest with the same search engine
### Search works, but filtered results do not appear consistently
Likely causes:
* only part of the search traffic is being inspected
* a bypass rule or exception path affects the search engine traffic
Isolation steps:
* test from the same client repeatedly
* compare working and non-working requests in logs
* review request profiles or bypass conditions that may affect search domains
Remediation:
* remove or narrow the conflicting bypass
* ensure the search engine traffic follows one consistent policy path
## Related controls / next steps
* Use [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) for the HTTPS visibility required by this control.
* Use [Web Categorization](/getting_started/core_features/web_categorization) and [Access Restriction](/use_cases/access_restriction/access_restriction) when search-result filtering must sit alongside broader destination controls.
# Web Categorization
Source: https://docs.safesquid.com/use_cases/access_restriction/web_categorization
Review and refine SafeSquid website categorization so destination-based enforcement stays accurate, explainable, and safe for production use.
# Correct destination logic before policy fails
## Problem statement
Category-based enforcement is only as good as the category assignment behind it. When a business-critical site is miscategorized, productivity breaks. When a risky site remains uncategorized or wrongly classified, policy looks stronger than it is.
## Client scenario
Use Web Categorization when you need to:
* inspect the existing category assigned to a website
* correct misclassified sites
* create local categories for business-specific policy
* support access, safe-search, or acceptable-use rules with cleaner destination logic
## Key benefits
Accurate categorization improves the quality of every category-driven control above it. It reduces noisy exceptions, makes access rules easier to explain, and helps operators troubleshoot category-based blocks without guessing.
## Prerequisites
### Client-side preparations
* Identify the exact domain or site path that users are accessing.
* Reproduce the traffic through SafeSquid so you can validate the final category outcome.
### SafeSquid-side setup
* Decide whether the site should fit an existing category or a new local category.
* Check whether a broader policy already consumes the category you plan to modify.
## Setup instructions
### Search the existing categorization first
In the category editor, search for the website or domain before making changes.
This matters because operators should understand the current category state before overriding it.
### Change only what the policy actually needs
If one destination is wrong, correct that destination instead of widening multiple access exceptions around it.
That keeps policy cleaner and reduces future troubleshooting debt.
### Create local categories carefully
Use a new category only when the business need cannot be represented safely by an existing one.
A category name should make sense to operations, security review, and future administrators reading the policy months later.
### Retest the policy path after recategorization
Category edits should always be validated through the access rule that consumes them. A correct-looking edit in the editor is not enough if the consuming policy still behaves unexpectedly.
## Verification and validation
### Positive test
Search for a known site, apply the category change, then access the site through SafeSquid.
Expected result:
* the site reflects the intended category assignment
* the consuming access policy allows or blocks as designed
* logs and reports show the expected category outcome
### Negative test
Test another site in the same broader destination family that should not inherit the change.
Expected result:
* the categorization update remains narrow
* unrelated domains do not shift into the wrong control path
## Troubleshooting guide
### A category change does not affect policy outcome
Likely causes:
* another rule matches before the category-based rule
* the site is being matched by hostname, request profile, or explicit exception first
Isolation steps:
* inspect the final rule path in logs
* verify which access rule actually decided the request
Remediation:
* adjust the consuming rule order
* remove or narrow the conflicting exception
* retest the same destination
### Too many sites are affected by a category decision
Likely causes:
* the category is too broad for the business need
* a local exception should have been used instead
Isolation steps:
* list the destinations now affected by the category
* compare intended scope with observed scope
Remediation:
* move the special case into a narrower local category or exception rule
* retest approved and blocked destinations separately
## Related controls / next steps
* Use [Access Restriction](/use_cases/access_restriction/access_restriction) to consume category outcomes safely.
* Use [Request Profiles](/use_cases/profiling_engine/request_profiles) when hostname or application context needs to complement category logic.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) and [Reporting Module](/use_cases/audit_and_forensics/reporting_module) to verify category-driven decisions.
# Working of Default Entries in Access Restrictions
Source: https://docs.safesquid.com/use_cases/access_restriction/working_of_default_entries_in_access_restrictions
Understand how default SafeSquid access-restriction entries behave so you can modify baseline policy safely without creating hidden enforcement gaps.
# Understand baseline rules before changing them
## Problem statement
Default restriction entries are easy to overlook because they seem familiar. In practice, they shape the baseline enforcement path for every later policy decision. Editing them casually can create hidden allow paths, unexpected denials, or troubleshooting confusion that only appears in production.
## Client scenario
Use this page when you need to:
* understand what the shipped default entries are doing
* decide whether to modify or leave a default rule in place
* troubleshoot policy behavior that seems to happen before custom rules
* prepare a safer rollout plan for access-policy changes
## Key benefits
A clear understanding of the default entries reduces accidental policy drift. It also helps new administrators understand whether a behavior comes from their custom logic or from the product baseline.
## Prerequisites
### Client-side preparations
* Reproduce the user workflow that is affected.
* Gather the username, destination, and time window for testing.
### SafeSquid-side setup
* Review the current ordered access restriction list before modifying defaults.
* Identify any custom exceptions that depend on the current baseline behavior.
## Setup instructions
### Inspect default entries before editing
Read the existing default entries in their current order.
Do not assume they are harmless placeholders. In many environments they participate in the first effective allow or deny path.
### Compare default logic with your custom policy
Before editing a default entry, ask:
* does this default rule still support the intended baseline?
* does a custom rule depend on this rule being present or absent?
* would it be safer to add a new specific rule instead of mutating the baseline?
### Prefer narrow overrides over casual baseline edits
If the requirement is specific, add a targeted exception or new rule first. Avoid changing defaults just to solve a narrow one-off workflow.
That keeps the baseline understandable and reduces surprise for future operators.
## Verification and validation
### Positive test
Identify a transaction that should follow the default path and verify it still behaves as intended after your review or edit.
Expected result:
* the baseline rule path is understood
* the final action matches the intended default behavior
### Negative test
Test a custom workflow that should bypass or override the default behavior.
Expected result:
* the custom rule still wins where intended
* the default rule does not unexpectedly reassert control
## Troubleshooting guide
### Custom policy changes seem ineffective
Likely causes:
* a default entry matches first
* administrators assumed the defaults were inactive
Isolation steps:
* inspect rule order
* identify which entry actually triggered in logs
Remediation:
* move the specific custom rule above the default if appropriate
* narrow the default entry if it is too broad
### Unexpected access is still allowed
Likely causes:
* a baseline allow remains in place
* a deny rule was added below a broader default allow
Isolation steps:
* compare the triggered rule against the full ordered list
* retest with the same user and destination
Remediation:
* move or narrow the relevant entries
* validate again with positive and negative tests
## Related controls / next steps
* Use [Access Restriction](/use_cases/access_restriction/access_restriction) for the full policy model.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) to identify which entry actually decided the request.
# YouTube API Integration
Source: https://docs.safesquid.com/use_cases/access_restriction/youtube_api_integration_with_safesquid_to_allow_specific_youtube_videos
Integrate YouTube API with SafeSquid to allow or block YouTube videos by category for productivity and bandwidth control.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Allow or block YouTube by category via YouTube API
YouTube offers entertainment and educational content; unrestricted viewing can reduce productivity and bandwidth. SafeSquid integrates with the YouTube API to identify video categories. Policies can allow or block specific categories so organizations permit learning and marketing content while blocking unrelated videos.
## Client scenario (case study)
Ganpat University provides graduate programs to various colleges. All the staff's PC/Laptop traffic is going via SafeSquid SWG.
Ganpat University wants to block entire youtube.com for faculty and students. But wants some of the YouTube channels allowed which are helpful for faculty/students.
Ganpat University challenges are:
All staff/Students should not be allowed to access [www.youtube.com](http://www.youtube.com). If any faculty/student try to access YouTube then he/she should get blocked template.
Only few of the specified YouTube channel and its playlist should be allowed. These YouTube channel contains educational and knowledge sharing videos.
SafeSquid SWG give them solution for the above requirement.
You can achieve this by creating policy in Request Profiles Section and bind it with policies in Access Profiles Section.
You need YouTube Channel-ID and List-ID of playlist, you want to allow.
You have to extract Channel-ID and List-ID of the playlist from YouTube URL before creating policies in SafeSquid.All the
Mr. Haresh is the system administrator of Ganpat University. From last few months he received the request from faculty for allowing many other videos/Playlist/channels etc.
Of course, all the videos/Playlist/channel etc. are educational and knowledge sharing.
But he faces some difficulty for extracting Channel-ID and List-ID of the requested playlist/channel regularly.
SafeSquid SWG has given them the fantastic solution for Mr. Haresh difficulty.
The latest Version of SafeSquid (Versions August onward) includes **YouTube API Integration with SafeSquid-SWG**. That means you can now create Policies on the basis of YouTube Categories.
You can now allow/block specific category of videos on YouTube.
![Find category to allow or block Youtube video]()
## Prerequisites
HTTPS Inspection should be enabled in SafeSquid. If it is not enabled, see How to enable HTTPS Inspection
## Create a YouTube V3 API using your Google Account.
To Request the Category of Specific Video
To extract Video Category from Video ID
Go To [https://console.developers.google.com/apis/library](https://console.developers.google.com/apis/library) [Google Cloud API Library](https://console.cloud.google.com/apis/library)
![Create a Youtube V3 API using google account for Youtube API integration with safesquid]()
:::note
What happens over here is If you don't Create a Project over here, Google will Automatically Create a new Project for you Named as "My First Project" when you ENABLE the YouTube Data API v3.
:::
People doing it for the first time and have requirement to use YouTube Data API v3 to integrate it with SafeSquid-SWG.
I recommend creating a New Project with a Proper name so that you can later identify it.
Since they have specified Per Day Quota i.e. No of Request to find Information about a Particular video and its details.
Make sure that this Google Account is not using YouTube API for any other purposes as this will reduce the No of Request
## CREATE A NEW PROJECT
![Click on select a project to integrate Youtube API with safesquid]()
![Click on project to integrate Youtube API with safesquid]()
### Name as: YouTubeAPI-For-SafeSquid
![Name and create a project to integrate Youtube API with safesquid]()
![Redirect to API Library in API & Services section]()
### Select a project
![Select a project to integrate Youtube API with safesquid]()
![Get a access of API Library]()
![Select YOUTUBE DATA API V3 to integrate Youtube API with safesquid]()
### Enable YouTube Data API V3
![ENABLE YOUTUBE DATA API V3 to]()
### Create credentials
![Select a Create credentials to integrate Youtube API with safesquid]()
![Click on Create credentials to integrate Youtube API with safesquid]()
### Select API key
![select API key to create API keys]()
![Google generate Youtube API keys]()
## Integrate the YouTube API Key in SafeSquid.
**To identify the category of the YouTube video**
Now we are going to Integrating this Key in SafeSquid-SWG.
To do that, Go to SafeSquid console.
Go to the path using below command:
```bash theme={null}
cd /var/lib/safesquid/
```
Create the directory using below command:
```bash theme={null}
mkdir youtube
```
Give the permission using below command:
chmod 774 youtube
chown ssquid:root youtube
root\@safesquid-swg:/var/lib/safesquid# ll
total 56
drwxrwxr-- 12 ssquid root 4096 Aug 29 15:35 ./
drwxr-xr-x 48 root root 4096 Jul 4 19:06 ../
drwxrwxr-- 3 ssquid root 4096 Jan 21 2019 application\_signatures/
drwxrwxr-- 2 ssquid root 4096 Sep 5 14:03 category/
drwxrwxr-- 3 ssquid root 4096 Apr 2 18:44 content\_signatures/
drwxrwxr-- 2 ssquid root 4096 Jan 21 2019 imgfilter/
drwxrwxr-- 3 ssquid root 12288 Sep 5 13:47 sqscan/
drwxrwxr-- 3 ssquid root 4096 May 30 14:17 sscore/
drwxrwxr-- 4 ssquid root 4096 Sep 5 14:03 sscore2/
drwxrwxr-- 2 ssquid root 4096 Jun 13 19:12 ssqore/
drwxrwxr-- 4 ssquid root 4096 Sep 5 14:03 svscan/
drwxrwxr-- 2 ssquid root 4096 Aug 23 14:53 youtube/
Go to youtube directory using command:
root\@safesquid-swg:/var/lib/safesquid#cd youtube
Copy YouTube API Key using WinSCP or any other tool at given path **/var/lib/safesquid/youtube/**
root\@safesquid-swg:/var/lib/safesquid/youtube# ll
total 16
drwxrwxr-- 2 ssquid root 4096 Aug 23 14:53 ./
drwxrwxr-- 12 ssquid root 4096 Aug 29 15:35 ../
-rw-rw-r-- 1 ssquid root 40 Jul 3 14:11 keys
-rw-rw-r-- 1 ssquid root 947 Jul 3 14:12 legends
After adding key, the file will look like this
root\@safesquid-swg:cat /var/lib/safesquid/youtube/keys
AIz\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*o
After adding the API key, **restart the SafeSquid service** from the SafeSquid Interface or via command line:
```bash theme={null}
/etc/init.d/safesquid restart
```
:::note
Please Restart SafeSquid Twice in order to Integrate YouTube API properly.
:::
You have successfully integrated YouTube API with SafeSquid-SWG.
Now, Go ahead with Policy creation on the basis of YouTube Categories.
To do so, I will help you out in creating a simple Policy which will only allow Specific YouTube Category VIA SafeSquid all other YouTube Videos will be blocked.
![Click on configure to integrate Youtube API with safesquid]()
![Policy to integrate Youtube API with safesquid]()
![Youtube Video policy to allow specific video]()
![Youtube Video policy to allow specific video]()
## Next steps
* **[Allow Specific YouTube Channel and its Playlist](/use_cases/access_restriction/allow_specific_youtube_channel_and_its_playlist)** - block general YouTube but allow specific channels and playlists in SafeSquid for education.
* **[Block Specific YouTube Channel](/use_cases/access_restriction/block_specific_youtube_channel)** - block a specific YouTube channel using SafeSquid by creating policies based on Channel-ID and List-ID for targeted video restriction.
# Audit & Forensics
Source: https://docs.safesquid.com/use_cases/audit_and_forensics/audit_forensics
Comprehensive network monitoring, security analysis, and forensic capabilities for enterprise web security management
# Logging, reporting, and forensics for compliance and incidents
Lack of visibility into web traffic and security events undermines incident response, compliance evidence, and audit. SafeSquid audit and forensics must answer practical questions: what happened, which user or administrator was involved, which policy fired, whether traffic was bypassed, and what evidence remains after the event.
SafeSquid provides that visibility through reporting, detailed request logs, configuration logs, bypass and privacy logs, performance monitoring, and operational records such as UI and privileged-access logs.
## Problem statement
Security controls fail operationally when the team cannot reconstruct events. Anonymous traffic, undocumented policy changes, missing bypass records, and poor retention all create false assurance.
## Client scenario
Use this hub when you need to design or investigate:
* compliance evidence for web-security controls
* incident timelines for user activity or threat events
* privileged changes and policy modifications
* cluster-wide visibility and retention strategy
## Reporting and analytics
### [Reporting module](/use_cases/audit_and_forensics/reporting_module)
Organizations require detailed visibility into web traffic patterns, user activities, and security events to support compliance reporting, security analysis, and operational decision-making. Reporting Module enables SafeSquid to generate reports covering user activities, website access patterns, security incidents, bandwidth utilization, and policy violations through customizable dashboards and detailed analytics. This reporting capability provides actionable intelligence for security teams while supporting regulatory compliance and operational optimization. Access the Reporting Module through SafeSquid's dashboard interface to generate comprehensive traffic and security analytics.
## Security event logging
### [Security logs](/use_cases/audit_and_forensics/security_logs)
Security teams need detailed logs of security events, policy violations, and threat activities to support incident investigation, compliance auditing, and forensic analysis. Security Logs enable SafeSquid to capture comprehensive security event data including blocked requests, policy violations, authentication failures, and threat detection activities through structured logging and real-time monitoring. This logging capability ensures complete audit trails for security events while supporting forensic investigation and compliance requirements. Configure security logging in SafeSquid's logging settings to enable security event capture and analysis.
The broader SafeSquid evidence model also includes:
* UI Access Logs
* Privileged Access Logs
* Bypass Logs
* Deep Content Security Logs
* Content Security Policy Violation Logs
## Performance monitoring
### [Performance plot](/use_cases/performance_acceleration/performance_plot)
Organizations need visibility into system performance metrics, bandwidth utilization, and resource consumption to optimize web security infrastructure and identify performance bottlenecks. Performance Plot enables SafeSquid to generate detailed performance analytics including bandwidth usage, response times, connection counts, and system resource utilization through graphical representations and trend analysis. This monitoring capability provides insights into system performance while supporting capacity planning and optimization efforts. Access performance plots through SafeSquid's monitoring interface to analyze system performance and identify optimization opportunities.
## System health monitoring
### [Monit](/use_cases/audit_and_forensics/audit_forensics_monit)
Enterprise environments require continuous monitoring of system health, service availability, and resource utilization to ensure reliable web security operations and rapid issue detection. Monit enables SafeSquid to monitor system processes, resource usage, service availability, and performance metrics through automated health checks and alerting mechanisms. This monitoring capability ensures system reliability while supporting proactive maintenance and rapid issue resolution. Configure Monit monitoring in SafeSquid's system settings to enable comprehensive health monitoring and automated alerting.
## Forensic analysis and directory structure
### [Architecture and file layout](/architecture/overview/safesquid_swg)
Security teams require organized access to log files, configuration data, and forensic artifacts to support incident investigation, compliance auditing, and system analysis. Directory Structure provides documentation of SafeSquid's file organization including log locations, configuration directories, data storage paths, and forensic artifact locations through structured documentation and access guidelines. This organizational framework ensures efficient access to forensic data while supporting systematic investigation and analysis procedures. Reference the Directory Structure documentation to locate and access forensic data for security investigations and compliance audits.
## Next steps
Correlate with [Security Logs](/use_cases/audit_and_forensics/security_logs) and [Troubleshooting](/troubleshooting/troubleshooting) for incident response; for policy configuration see [Access Restriction](/use_cases/access_restriction/access_restriction) and [Configuration Portal](/architecture/interface/configuration_portal).
# Monit
Source: https://docs.safesquid.com/use_cases/audit_and_forensics/audit_forensics_monit
Install and verify Monit so SafeSquid restarts automatically after local service failure and operators can detect monitoring gaps early.
# Keep SafeSquid under service watch
## Problem statement
If the SafeSquid service stops and no local watchdog restarts it, web access can fail until an operator notices the outage. In branch sites and lean operations teams, that gap can turn a recoverable process failure into a visible business incident.
## Client scenario
Use Monit when you need the host to:
* detect a stopped SafeSquid service quickly
* restart SafeSquid automatically after local process failure
* confirm the watchdog itself is running after reboot
Monit helps with local process recovery. It does not replace clustering, upstream load balancing, or disaster recovery planning.
## Key benefits
Monit shortens recovery time for simple service failures and gives administrators a clear local health mechanism. It is most useful for single-node deployments, pilot environments, and branch appliances that need basic self-healing.
## Prerequisites
### Client-side preparations
* Ensure you have shell access with administrative privileges on the SafeSquid host.
* Confirm you can restart SafeSquid safely during a maintenance window if this is a production system.
### SafeSquid-side setup
* If you used the SafeSquid Appliance Builder, Monit may already be installed.
* Confirm the SafeSquid init/service commands used on the host are valid before building rules around them.
## Setup instructions
### Confirm whether Monit already exists
Run:
```bash theme={null}
/etc/init.d/monit status
```
If the service is present and running, review the current configuration before changing anything.
### Install Monit when it is missing
Run:
```bash theme={null}
apt-get install monit
```
This installs the local monitoring daemon that will watch SafeSquid and restart it when the process stops.
### Update the Monit configuration
Open the Monit configuration directory and edit `monitrc`.
Set a polling interval, enable the local web status page if your operational model allows it, and include the directory used for service-specific policies.
Example baseline:
```conf theme={null}
set daemon 3
set httpd port 2812 and
use address localhost
allow localhost
allow admin:monit
allow @monit
include /etc/monit/conf.d/
```
The three-second polling interval determines how quickly Monit notices a stopped process. The include directive matters because service checks are typically stored under `/etc/monit/conf.d/`.
### Restart Monit after changes
Run:
```bash theme={null}
/etc/init.d/monit restart
```
This reloads the configuration and applies the updated monitoring rules.
### Confirm SafeSquid is under Monit control
Run:
```bash theme={null}
monit status
```
Verify that SafeSquid appears in the monitored service list. If it does not, Monit is running but not yet supervising the proxy service.
### Start Monit automatically at boot
Run:
```bash theme={null}
update-rc.d monit enable
```
This reduces the risk of rebooting into an unmonitored state.
## Verification and validation
### Positive test
Stop SafeSquid intentionally:
```bash theme={null}
/etc/init.d/safesquid stop
```
Then check whether the process returns:
```bash theme={null}
pidof safesquid
```
Expected result:
* the SafeSquid process disappears briefly
* Monit detects the stop condition
* SafeSquid starts again without manual intervention
### Negative test
Stop Monit and then stop SafeSquid in a controlled test window. SafeSquid should remain down until you restart it manually. This proves the automatic recovery path depends on Monit actually running.
### Evidence to retain
* output of `monit status`
* service status before and after the stop test
* time taken between stop event and service recovery
## Troubleshooting guide
### SafeSquid does not restart after a stop test
Likely causes:
* Monit is not running
* SafeSquid is not defined as a monitored service
* the Monit rule points to the wrong service name or PID file
Isolation steps:
* run `/etc/init.d/monit status`
* run `monit status`
* confirm SafeSquid appears as a monitored object
Remediation:
* start or restart Monit
* correct the SafeSquid service check definition
* rerun the stop test
### Monit runs but reports no SafeSquid service
Likely causes:
* the include path is missing or wrong
* the service policy file was never created
Isolation steps:
* inspect `monitrc`
* verify `include /etc/monit/conf.d/` exists
* verify a SafeSquid-specific rule exists in the included directory
Remediation:
* restore the include line
* add or correct the SafeSquid monitoring rule
* restart Monit and confirm with `monit status`
### Monitoring breaks after reboot
Likely causes:
* Monit is not enabled at startup
* boot sequencing starts SafeSquid before its monitoring rule is available
Isolation steps:
* check whether Monit starts automatically after reboot
* confirm both Monit and SafeSquid show expected service state
Remediation:
* run `update-rc.d monit enable`
* reboot in a maintenance window and validate again
## Related controls / next steps
* Use [Disaster Recovery](/use_cases/scaling_and_high_availability/disaster_recovery) for recovery planning beyond single-host service restarts.
* Use [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) when you need resilient scale-out instead of local process recovery alone.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) to confirm outage timing and recovery evidence during investigations.
# Reporting Module
Source: https://docs.safesquid.com/use_cases/audit_and_forensics/reporting_module
Use SafeSquid reporting to investigate activity, drill into users and destinations, and export time-bounded evidence for operations and audit review.
# Turn dashboard data into evidence
## Problem statement
Dashboards often look useful while failing real investigations. If operators cannot move from a chart to a specific user, destination, policy event, and time window, reporting becomes presentation material instead of operational evidence.
## Client scenario
Use the Reporting Module when you need to:
* investigate a user, group, destination, or policy outcome quickly
* prove activity during a specific time window
* export evidence for audit, management review, or incident response
* tune policy from observed traffic instead of assumptions
## Key benefits
The Reporting Module provides a fast investigation surface for recent activity and a practical way to narrow from summary view to specific transactions. It complements raw logs by helping operators identify where to look and what to export.
## Prerequisites
### Client-side preparations
* Know the user, group, destination, or incident window you want to investigate.
* Confirm the traffic of interest actually passed through SafeSquid.
### SafeSquid-side setup
* Ensure dashboard reporting is available and receiving current data.
* Use raw logs as the fallback source when the dashboard view is too narrow or a time window must be validated precisely.
## Setup instructions
### Start from the dashboard view
Open **Reports → Dashboard** and review the current report scope.
Dashboard data defaults to recent transactions, so begin by deciding whether you need transaction-count scope or date-range scope.
### Drill into the first reliable signal
Click a useful entry such as:
* user name
* user group
* IP address
* domain
* blocked websites
* security breaches
* categories
* application signatures
Choose the first filter that is least ambiguous for the incident you are investigating.
![Detailed real-time reporting SafeSquid Dashboard]()
![Filtering section in SafeSquid Dashboard]()
### Adjust the transaction range when needed
SafeSquid reports on a recent transaction set by default. Increase or narrow the range based on the event you are investigating.
![Report based on last 1000 transactions by default]()
![Edit report based on number of transactions]()
![Apply filter to view SafeSquid report]()
![Choose filtering options to view SafeSquid report]()
![Close filter menu in SafeSquid report]()
### Switch to date-range evidence for incident review
When the event belongs to a known time window, use the date-range filter instead of relying only on the recent transaction view.
![SafeSquid report based on date range]()
![SafeSquid filtered report]()
![Flush button to reset report filters]()
### Export what you prove
When the report reflects the correct user, activity, and time range, export the result for review or audit use.
## Verification and validation
### Positive test
Trigger a controlled request, then locate it through the dashboard using a user, IP, or destination filter.
Expected result:
* the event appears in the reporting window
* drill-down narrows the result to the intended transaction set
* the exported report reflects the same filtered evidence
### Negative test
Search for a user or destination that should not appear in the chosen time window.
Expected result:
* the report remains empty or excludes that activity
* operators do not mistake stale or unrelated data for current evidence
### Evidence to retain
* the exact filter path used
* the time range or transaction range selected
* the exported report file
* any corresponding log query used to corroborate the finding
## Troubleshooting guide
### Expected activity is missing from the dashboard
Likely causes:
* the report scope is too narrow
* the filters are too restrictive
* the activity did not pass through the expected SafeSquid path
Isolation steps:
* reset filters
* widen the transaction range or date range
* compare against raw logs
Remediation:
* correct the scope
* validate the traffic path
* rerun the report with a narrower filter only after the event is visible
### The dashboard shows activity, but it is not precise enough for evidence
Likely causes:
* operators are stopping at summary widgets
* the transaction window is too broad
* raw log corroboration was skipped
Isolation steps:
* drill down by a more specific field
* reduce the time range
* compare the same event against logs
Remediation:
* preserve both the report export and the supporting log reference
* use the dashboard to find the event, then use logs to prove it precisely
## Related controls / next steps
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) for raw evidence and deep investigation.
* Use [Performance Plot](/use_cases/performance_acceleration/performance_plot) for time-based load and capacity context.
# Security Logs
Source: https://docs.safesquid.com/use_cases/audit_and_forensics/security_logs
SafeSquid security logs — native, extended, configuration, performance, bypass, and privacy records used for troubleshooting, investigations, and audit evidence.
# Investigate Issues With SafeSquid Logs
## Problem statement
If teams cannot tell which request was blocked, which request was bypassed, which configuration changed, or which user was involved, investigations become guesswork. Security logging is the evidence layer behind SafeSquid operations.
## Client scenario
Use this page when you need to understand which SafeSquid logs matter for:
* request-level troubleshooting
* policy verification
* privileged-change review
* bypass and privacy-event review
* forensic evidence collection
## Logs support troubleshooting and analysis
Logs provide a timeline of events for the OS and applications and are a primary troubleshooting tool. When an issue occurs, the system administrator analyzes log files first. Most logs are plain text under /var/log. With SafeSquid installed, two log types matter: SafeSquid application logs and SafeSquid activity logs (in system logs). To view a log file, use one of:
```bash theme={null}
less /var/log/logfilename
```
```bash theme={null}
more -f /var/log/logfilename
```
```bash theme={null}
/var/log/logfilename
```
```bash theme={null}
tail -f /var/log/logfilename
```
```bash theme={null}
grep -i error /var/log/logfilename
```
## SafeSquid Application Logs
SafeSquid application produces these logs. Logs contain all kinds of error messages, warnings or other events written by the SafeSquid. These messages provide logical, high-level information for specific use cases. Each log message helps administrators understand SafeSquid behavior.
SafeSquid application generates six different log formats.
These logs are named safesquid.log (Native logs), extended.log (NCSA/Extended logs), config.log (Config logs), and performance.log (Performance logs).
Two more log formats were added subsequently as bypass.log and privacy.log.
The path to these log files are as follows:
| Log File | Path |
| - | - |
| **safesquid.log** | **/var/log/safesquid/native/** |
| **extended.log** | **/var/log/safesquid/extended/** |
| **config.log** | **/var/log/safesquid/config/** |
| **performance.log** | **/var/log/safesquid/performance/** |
| **bypass.log** | **/var/log/safesquid/bypass/** |
| **privacy.log** | **/var/log/safesquid/privacy/** |
View Native Log and Config Log details from the **SafeSquid Interface**.
These log families map closely to the wider SafeSquid evidence model:
* native logs for functional and debugging detail
* extended logs for request-level evidence
* config logs for administrative changes
* performance logs for capacity and stability analysis
* bypass logs for override behavior
* privacy logs for privacy-related handling
### Native logs
It records various functional aspects like REQUESTS, SECURITY, REDIRECT etc. that are affected by the various features and their configuration.
Control the verbosity of the Native log by specifying LOGLEVEL, as shown in the table below.
The LOGLEVEL parameter affects only the SafeSquid's Native log.
| Value | Process logged | Value | Process logged |
| - | - | - | - |
| 1 | Requests | 16384 | Forwarding |
| 2 | Network | 32768 | Sync |
| 4 | LDAP | 65536 | Antivirus |
| 8 | Header filtering | 131072 | External parser |
| 16 | Interface Request | 262144 | ICAP |
| 32 | Cookie filtering | 524288 | SSL |
| 64 | Redirect | 1048576 | Category |
| 128 | Template | 2097152 | URL command |
| 256 | Text Analyzer | 4194304 | Modules |
| 512 | Rewriting | 8388608 | Security |
| 1024 | Limits | 16777216 | Warning |
| 2048 | Caching | 33554432 | Error |
| 4096 | Prefetching | 67108864 | Profiles |
| 8192 | ICP | 134217728 | Debug |
To record only requests set LOGLEVEL to 1; to record only caching set LOGLEVEL to 2048. To record rewriting, limits, and forwarding set LOGLEVEL to 512 + 1024 + 16384 (17920). To log everything (risk: very large log file quickly) set LOGLEVEL to the sum of all values in the table, 134217727—also the default if LOGLEVEL is commented out. For debug logs only set LOGLEVEL to 134217728. For all activities plus debug set LOGLEVEL to 268435455.
:::note
Adjusting this value requires a restart of SafeSquid service.
:::
This file stored all data related **to every request and response** processed by the SafeSquid. These logs will be useful for debugging purpose.
[Access the SafeSquid User Interface](/architecture/interface/configuration_portal)
On top right of SafeSquid Interface view **Reports >> Dashboard**
Click on "**Native logs**" to see the run time native logs.
**Each request and response** processed through SafeSquid is visible. Use the search bar to find a particular string. The **Resume** button stops real-time streaming of logs.
![Access Reports to view Dashboard on safesquid user interface]()
### Extended logs
The extended.log (NCSA / Extended log format) records maximum details of each request handled by the proxy application. Extended logs will be helpful for generation of reports to analyze the user activities.
**FORMAT / LEGEND:**
"record\_id" "client\_id" "request\_id" "date\_time" "elapsed\_time" "status" "size" "upload" "download" "bypassed" "client\_ip" "username" "method" "url" "http\_referer" "useragent" "mime" "filter\_name" "filtering\_reason" "interface" "cachecode" "peercode" "peer" "request\_host" "request\_tld" "referer\_host" "referer\_tld" "range" "time\_profiles" "user\_groups" "request\_profiles" "application\_signatures" "categories" "response\_profiles" "upload\_content\_types" "download\_content\_types" "profiles"
**Example Log Line1:**
```text theme={null}
"1531492103912WfkgX" "91" "2" "13/Jul/2018:19:58:26" "3663" "200" "626" "0" "626" "FALSE" "192.168.0.24" "anonymous@192.168.0.24" "GET" "" "https://accounts.google.com/" "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:61.0) Gecko/20100101 Firefox/61.0" "image/png" "-" "-" "192.168.24.74:8080" "TCP_MISS" "DIRECT" "ssl.gstatic.com" "ssl.gstatic.com" "gstatic.com" "accounts.google.com" "google.com" "100-1K" "" "ADMINS" "" "Unidentified Web2.0,Firefox,Internet Browser" "Search Engines & Portals" "POTENTIAL MALWARE THREATS,SMALL DOWNLOADS" "-" "image/png" "READ ONLY,ANTIVIRUS"
```
**Example Log Line2:**
```text theme={null}
"153157359815951WfkgX" "1595" "1" "14/Jul/2018:18:36:38" "106" "403" "1517132" "1517132" "0" "FALSE" "192.168.0.24" "anonymous@192.168.0.24" "POST" [http://www.csm-testcenter.org:80/test](http://www.csm-testcenter.org/test) "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:61.0) Gecko/20100101 Firefox/61.0" "text/html" "DLP" "application/vnd.ms-excel" "192.168.24.74:8080" "TCP_DENIED" "DIRECT" "safesquid" "www.csm-testcenter.org" "csm-testcenter.org" www.csm-testcenter.org "csm-testcenter.org" "1M-10M" "" "ADMINS" "MEDIUM UPLOADS" "Unidentified Web2.0,All Posts,All Uploads,Uploads,Firefox,Internet Browser" "Unknown" "" "application/vnd.ms-excel,text/plain" "-" "READ ONLY,ANTIVIRUS,BLOCK UPLOADS"
```
The details of the fields in extended.log are as follows:
| Field | Explanation |
| - | - |
| record\_id | A unique record identifier, to prevent duplication of records when imported into SQL databases. Example1> 1531492103912WfkgX |
| client\_id | The internal SafeSquid ID associated with the present/ongoing connection. Example1> 91 |
| request\_id | A unique ID for every request created in the present/ongoing connection to the web-server. Example1> 2 |
| date\_time | The date and time when the HTTP request was sent. The fields in the date/time field are \[DD/MMM/YYYY:hh:mm:ss], where the fields are defined as follows: DD is the day of the month, MMM is the month, YYYY is the year, hh is the hour, mm is the minute, ss is the seconds. Example1> 13/Jul/2018:19:58:26 |
| elapsed\_time | Length of time in milliseconds that current HTTP request used to complete the transaction. Example1> 3663 |
| status | Numeric code indicating the success or failure of the HTTP request. This code is a server response to a browser's request. Example1> 200 |
| size | Numeric field indicating the data transferred in number of bytes as part of the HTTP request, not including the HTTP header. Example1> 626 |
| upload | Numeric field indicating the data transferred from webserver to client. Example2> 1517132 |
| download | Numeric field indicating the data transferred from client to webserver. Example1> 626 |
| bypassed | Boolean (TRUE/FALSE) value which indicates whether the current request was bypassed or not after blocked by SafeSquid filter. Example1> FALSE |
| client\_ip | The IP address of the requesting client. Example1> 192.168.0.24 |
| username | The username\@client\_ip, (or user ID) used by the client for authentication. If no value is present, "anonymous" is substituted. Example1> anonymous\@192.168.0.24 |
| method | A method is part of HTTP request sent by client to the server. Example1> GET |
| url | An HTTP url is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. Example1> |
| http\_referer | An HTTP header field that identifies the address of the age that linked to the resource being requested. "-" is substituted when there is no referrer in HTTP header field. Example1> [https://accounts.google.com/](https://accounts.google.com/) |
| useragent | User agent is the client which initiates a request. Useraagent are often browsers, editors, spiders (web-traversing robots), or other end user tools. Example1> Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:61.0) Gecko/20100101 Firefox/61.0 |
| mime | Mime-type (media type) are used to identify the format of a file and format contents transmitted on the Internet. Example1> image/png |
| filter\_name | Filter name due to which the request was blocked. "-" is substituted when request is allowed. Example2> DLP |
| filtering\_reason | If the request gets blocked, then predefined reason for blocked request will be set. "-" is substituted for unknown reasons and allowed requests. Example2> application/vnd.ms-excel |
| interface | Interface IP:PORT that received the request. This field is important when SafeSquid is listening on multiple IPs or Ports. Example1> 192.168.24.74:8080 |
| cachecode | Cachecodes are access error code set by SafeSquid during connection with TCP/UDP request. Example2> TCP\_DENIED |
| peercode | Peercode entry represents a code that explains how the request was handled, for example, by forwarding it to a peer, or returning the request to the source. Example1> DIRECT |
| peer | Peer represents the name of the host from which the object was requested. This host may be the origin site, a parent, or any other peer. Example1> ssl.gstatic.com |
| request\_host | Fully qualified domain name(FQDN) of the requested web-server. Example1> ssl.gstatic.com |
| request\_tld | Top-level domain name of the requested web-server. Example1> gstatic.com |
| referer\_host | The referrer is the URL of the HTTP resource that referred the user to the resource requested. "-" is substituted when there are no referrers. Example1> accounts.google.com |
| referer\_tld | Top-level domain name of the referrer URL that referred the user to the resource requested. "-" is substituted when there are no referrers. Example1> google.com |
| range | Data transferred in number of bytes as part of the HTTP request which comes under SafeSquid predefined range. Example2> 1M-10M |
| time\_profiles | Comma separated list of Time profiles that categorize, websites based on the time ranges. "" is substituted when no profiles are applied. |
| user\_groups | Comma separated list of User Group(s) to which this entry is applicable. Example1> ADMINS |
| request\_profiles | Comma separated list of Request profiles that were applied to the request. "" is substituted when no request profiles are applied. Example2> MEDIUM UPLOADS |
| application\_signatures | Comma separated list of application signatures that were applied to the request. Example2> Unidentified Web2.0,All Posts,All Uploads,Uploads,Firefox,Internet Browser |
| categories | Comma separated list of categories that were applied to the request. "" is substituted when no profiles are applied. Example2> Search Engines & Portals |
| response\_profiles | Comma separated list of Response profiles that were applied to the request. "" is substituted when no response profiles are applied. Example2> POTENTIAL MALWARE THREATS,SMALL DOWNLOADS |
| upload\_content\_types | Comma separated list of Upload Content Type. "-" is substituted when no profiles are applied or content types are unknown. Example2> application/vnd.ms-excel,text/plain |
| download\_content\_types | Comma separated list of Download Content Type. "-" is substituted when no profiles are applied or content types are unknown. Example1> image/png |
| profiles | Comma separated list of profiles that were applied to the request. "" is substituted when no profiles are applied. Example2> READ ONLY,ANTIVIRUS,BLOCK UPLOADS |
On top right of SafeSquid Interface view **Reports >> Dashboard**
Click on "**Detailed logs**" to see the run time extended logs.
Run time detailed logs displayed are Time, Username, Client ID, Method, URL, Status, Size, Referer, Useragent, Mime, Filter Name, Filter Reason, Profiles, Request profiles, Response profiles, Categories, Applications, Upload content type, Download content type from Extended Logs.
You can use **search option** to find information related to specific user or specific response code...etc. It's a common search option for filtering.
**Show/Hide Column** button is for **hiding** any option from above list.
You can also **search individually** from above list.
![Detailed logs of safesquid]()
### Config logs
Config logs contain the details related to the **SafeSquid user interface activities** like **configuration change**. You can find the users information who made the configuration changes and when.
**FORMAT / LEGEND**:
"ACCESS\_TIME" "SAFESQUID\_INTERFACE" "USERNAME\@IP" "PAGE" "SECTION" "ACTION" "HTTP\_METHOD" "URL" "REFERER" "ARGUMENTS" "CONFIG\_FILE" "REASON"
**Example Log Line1:**
```text theme={null}
"01/Aug/2018:01:30:19" "192.168.24.74:8080" "anonymous@192.168.0.27" "" "dlp" "edit" "POST" "[http://safesquid.cfg:80/](http://safesquid.cfg/)" "http://safesquid.cfg/" "F0=TRUE&F1=Block the uploading of PDF and Microsoft Word Documents. &F2=BLOCK-ALL-UPLOADS&F3=application/octet-stream,application/x-msdownload|application/x-dosexec&F4=.bat$|.exe$,.exe$&F5=MIME_OR_FILE&F6=DO_NOT_BYPASS&handler=configuration§ion=dlp&subsection=DLP&id=3&action=edit" "" ""
```
**Example Log Line2:**
```text theme={null}
"01/Aug/2018:18:29:38" "192.168.24.74:8080" "anonymous@192.168.0.27" "" "" "" "POST" "[http://safesquid.cfg:80/](http://safesquid.cfg/)" "http://safesquid.cfg/" "handler=save&filename=config.xml" "/usr/local/safesquid/security/policies/config_anonymous@192.168.0.27_2018-08-27-18-29-38.xml" ""
```
The details of the fields in config.log are as follows:
| Field | Explanation |
| - | - |
| ACCESS\_TIME | The date and time when the request for modification in SafeSquid configuration was sent. The fields in the date/time field are \[DD/MMM/YYYY:hh:mm:ss], where the fields are defined as follows: DD is the day of the month, MMM is the month, YYYY is the year, hh is the hour, mm is the minute, ss is the seconds. Example1> 01/Aug/2018:01:30:19 |
| SAFESQUID\_INTERFACE | Interface IP:PORT that received the request for modification in SafeSquid configuration. This field is important when SafeSquid is listening on multiple IPs or Ports. Example1> 192.168.24.74:8080 |
| USERNAME\@IP | The USERNAME\@IP, (or user ID) of the client who modified the SafeSquid configuration. If username is unknown then, "anonymous" is substituted. Example1> anonymous\@192.168.0.24 |
| PAGE | |
| SECTION | SafeSquid section where rule is either created or modified or deleted. Example1> DLP |
| ACTION | Action taken on any SafeSquid section to add a new policy or edit/ clone/ delete an existing policy. Example1> edit |
| HTTP\_METHOD | HTTP method to request sent by client to the server. Example1> POST |
| URL | SafeSquid interface URL is a reference to open WebGUI to View/change configuration. Example> [http://safesquid.cfg:80/](http://safesquid.cfg/) |
| REFERER | Referer address of the SafeSquid interface URL. Example1> [http://safesquid.cfg/](http://safesquid.cfg/) |
| ARGUMENTS | This field displays the SafeSquid policy details which was modified. Where F## shows the field values of the all fields. section=## displays section name. id=## determines the policy number from top. action=## shows the action performed on that policy. Example1> F0=TRUE\&F1=Block the uploading of PDF and Microsoft Word Documents. \&F2=BLOCK UPLOADS\&F3=application/octet-stream, application/x-msdownload\|application/x-dosexec&F4=.bat\$\|.exe\$,.exe\$&F5=MIME\_OR\_FILE&F6=DO\_NOT\_BYPASS&handler=configuration§ion=dlp&subsection=DLP&id=3&action=edit |
| CONFIG\_FILE | A backup config.xml file along with the path which can be restored at any time by the administrator. Example2>/usr/local/safesquid/security/policies/config\_anonymous@192.168.0.27\_2018-08-27-18-29-38.xml |
| REASON | |
On top right of SafeSquid Interface view **Reports >> Dashboard**
Click on **"Config logs"**
You can use **search option** to find information related to specific Time, Interface, Username, Section, Action, Arguments, Config File.
![Configuration logs of safesquid]()
### Performance logs
Performance logs will be helpful to analyze the performance of SafeSquid.
SafeSquid Performance logs provide performance metrics to identify any outage due to resource shortfall, or failure in Internet Connectivity, or surge in web-traffic, etc.
SafeSquid performance log has been extended to make it easier for analysis with third-party software such as GNU Plot that analyzes records on a progressive per line basis.
**FORMAT / LEGEND**:
Time Stamp (YYYYMMDDhhmmss),Elapsed Time,Client Connections Handled,Client Connections Closed,Client Transactions Handled,Client Connections in Pool,Spare Client Threads,Client Threads in Use,Client Threads in Waiting,Threads Starting up,Threads Reserved for Prefetching,Threading Errors,Outbound Connections created,Outbound Connections Failed,Outbound Connection Pool Reused,Outbound Connections in Pool,Bytes in (KBytes),Bytes Out (KBytes),Caching Objects Created in Memory,Caching Objects Removed from Memory,DNS Queries Reused,New DNS Queries,DNS Query failures,Total System Memory (KBytes),Free System Memory (KBytes),SafeSquid Virtual Memory (KBytes),SafeSquid Resident Memory (KBytes),SafeSquid Shared Memory (KBytes),SafeSquid Code Memory (KBytes),SafeSquid Data Memory (KBytes),SafeSquid Library Memory (KBytes),Connections Handled Delta,Connections Closed Delta,Transactions Handled Delta,Client Pool Delta,Spare Threads Delta,Active Threads Delta,Threads Waiting Delta,Threads Starting up Delta,Threads Prefetching Delta,Threading Errors Delta,Outbound Connections created Delta,Outbound Connections Failed Delta,Outbound Connection Pool Reused Delta,Outbound Connections in Pool Delta,Bytes in (KBytes) Delta,Bytes Out (KBytes) Delta,Caching Objects Created in Memory Delta,Caching Objects Removed from Memory Delta,DNS Queries Reused Delta,New DNS Queries Delta,DNS Query failures Delta,load avg.(1 min),load avg.(5 min),load avg.(15 min),Running Processes,Waiting Processes,User Time,System Time,Total (user + system) Time,User Time Delta,System Time Delta,Total Time Delta
**Example Log Line1:**
```text theme={null}
20180905172137,1603,21151,20941,44316,119,8016,91,68,17,0,0,13640,975,20650,139,1853191,2012552,0,0,11317,3185,41,5976008,2389076,596224,98868,4204,2472,0,472172,13,32,52,11,0,-30,30,0,0,0,5,3,27,0,1698,884,0,0,5,2,0,0.25,0.21,0.49,1,562,60.000000,56.000000,116.000000,0.000000,0.000000,0.000000
```
**Example Log Line2:**
```text theme={null}
20180905172139,1605,21170,20972,44346,132,8016,66,93,17,0,0,13654,976,20660,139,1854126,2014492,0,0,11328,3186,41,5976008,2387184,596224,98888,4204,2472,0,472172,19,31,30,13,0,-25,25,0,0,0,14,1,10,0,935,1940,0,0,11,1,0,0.23,0.21,0.49,1,562,60.000000,56.000000,116.000000,0.000000,0.000000,0.000000
```
The details of the fields in performance.log are as follows:
| Field | Explanation |
| - | - |
| Time Stamp (YYYYMMDDhhmmss) | Time when SafeSquid generated this record and stored in performance log. SafeSquid begins printing of each record on a new line with the first column as the TimeStamp in YYYYMMDDhhmmss format. Example> Log line1 was loged at 2018 September, 5th at 17:21:37 hence it displays 20180905172137 in YYYYMMDDhhmmss format. |
| Elapsed Time | Time in seconds since the SafeSquid process started. This is the time in seconds since the process started. Example> Log line1 reports that SafeSquid process running from last 1603 seconds. |
| Client Connections Handled | Total Client Connections handled by SafeSquid since the start of process. Example> Log line1 reports that since SafeSquid process running (from 1603 seconds), process handled 21151 incoming connections. |
| Client Connections Closed | Total Client Connections closed by SafeSquid since the start of process. Example> Log line1 reports that since the start of the process, SafeSquid had closed 20941 incoming connections. Thus we can interpret that at 2018-05-09 17:21:37 there were 21151 - 20941 = 210 concurrent incoming client connections. So while the 3rd counter and 4th counter are not very significant by themselves, their differential value is very important as it gives a an idea about concurrent connections being handled at any point. |
| Client Transactions Handled | Total Number of transactions handled between clients and SafeSquid since the start of the process. Within each connection a client may send multiple requests, to service these requests SafeSquid may have to transact multiple HTTP transactions. Example> Log line1 reports that since start of the process, SafeSquid had handled 44316 transactions. |
| Client Connections in Pool | Connections in local pool of SafeSquid. After request handling each connection is been kept in client connection pool for persistence. SafeSquid may not forcibly close a client connection after performing a transaction within, and even wait for sometime allowing the client to reuse a connection after a few seconds. Such connections are maintained in a "Client Pool". Example> Log line1 reports that there were 119 client connections that were idling in the client pool. Thus out of the 210 concurrent connections (derived above), 119 were in the client pool and the remaining 91 were either actively transacting, or maybe in the various stages of closure. |
| Spare Client Threads | Additional number of Threads that SafeSquid may produce to service client requests when SafeSquid printed this record. Example> Log line1 reports that SafeSquid can still produce 8016 client requests. |
| Client Threads in Use | Concurrent Requests being serviced by SafeSquid when SafeSquid printed this record. Example> Log line1 reports that SafeSquid had used 91 threads to fulfill client requests. |
| Client Threads in Waiting | Threads just released by client requests and available for instantly servicing a client request when SafeSquid printed this record. Example> Log line1 reports that at present 68 client threads are in waiting state. |
| Threads Starting up | Some Threads already assigned for some sections when SafeSquid starts, these are special threads of SafeSquid. Example> Log line1 reports that at present 17 threads are used by SafeSquid for internal processes. |
| Threads Reserved for Prefetching | Threads reserved by SafeSquid, to service pre-fetching demands. Example> Log line1 reports that at present 0 thread is used for pre-fetching. |
| Threading Errors | Total number of events when SafeSquid could not produce a thread due to system failure or MAXTHREADS limitation. Example> Log line1 reports that since start of the process 0 threading errors occurred. |
| Outbound Connections created | Total New connections created by SafeSquid to various remote webservers to service a client request. Example> Log line1 shows total 13640 new connections created by SafeSquid. |
| Outbound Connections Failed | Total Number of Events since the start of the process, when SafeSquid failed to create a connection to various remote webservers to service a client request. Example> Log line1 shows total 975 failed outbound connections. |
| Outbound Connection Pool Reused | After handling request from client, connections are kept/stored in connection pool in waiting state. These connections are been reused so that additional burden on server of creating too many connections on server be lower down. Total reused connection till current time. Example> Log line1 shows 20650 outbound connections are been reused from connection pool from last 1603 seconds. |
| Outbound Connections in Pool | Total number of Outbound connections idling in Connection Pool. Example> Log line1 shows 139 outbound connections idling in pool. |
| Bytes in (KBytes) | Total number of KiloBytes received by SafeSquid since the start of the process. Example> Log line1 shows 1853191 Kilobytes has been received from server since the start of the process. |
| Bytes Out (KBytes) | Total number of KiloBytes sent by SafeSquid since the start of the process. Example> Log line1 shows 2012552 Kilobytes has been sent by SafeSquid since start of the process. |
| Caching Objects Created in Memory | Total number of Cached Objects created by SafeSquid in memory since the start of the process. Example> Log line1 shows 0 caching objects created in memory. |
| Caching Objects Removed from Memory | Total number of Cached Objects removed by SafeSquid from memory since the start of the process. Example> Log line1 shows 0 caching objects removed from memory. |
| DNS Queries Reused | Total number of DNS queries to fulfill client request that are previously used and saved in DNS cache. Example> Log line1 shows 11317 DNS queries are reused from DNS cache since start of the process. |
| New DNS Queries | Total number of successful DNS queries to fulfill client requests. Example> Log line1 shows 3185 DNS queries are reused from DNS cache since start of the process. |
| DNS Query failures | Total number of events when SafeSquid successfully failed to do a DNS lookup since the start of the process. Example> Log line1 shows 41 DNS query fails since start of the process. |
| Total System Memory (KBytes) | Total system memory of server where SafeSquid is installed. Example> Log line1 indicates server has 5976008 KB(i.e. 6 GB) of RAM. |
| Free System Memory (KBytes) | Current Free system memory of server where SafeSquid is installed. Example> Log line1 indicates free system memory when log captured was 2389076 KB(i.e. 2.38 GB). |
| SafeSquid Virtual Memory (KBytes) | Current Virtual memory of server where SafeSquid is installed. Example> Log line1 shows server has 596224 KB virtual memory. |
| SafeSquid Resident Memory (KBytes) | Current Resident memory of server where SafeSquid is installed. Or The size of the SafeSquid process resident in physical memory. Example> Log line1 shows server has 98868 KB resident memory. |
| SafeSquid Shared Memory (KBytes) | Current shared memory of server where SafeSquid is installed. The memory shared with other processes other than SafeSquid i.e. memory mapped both by SafeSquid process and other process (such as shared libraries or other helping executables and libraries). Example> Log line1 indicates 4204 KB shared memory. |
| SafeSquid Code Memory (KBytes) | Total SafeSquid Code Memory in the text format. Example> Log line1 indicates 2472 KB of code is written in SafeSquid. |
| SafeSquid Data Memory (KBytes) | Memory that is been used by SafeSquid in the server. The size of the SafeSquid process i.e. the size of loaded executable code of SafeSquid. Example> Log line1 shows 0 bytes of data memory used. |
| SafeSquid Library Memory (KBytes) | Total memory used by SafeSquid helping Libraries. Example> Log line1 shows 472172 Kbytes of memory used by SafeSquid libraries. |
| Connections Handled Delta | Difference between two consecutive connection handled entries i.e. \[present number of connection handled - previous entry connection handled]. Example> Log line2 shows Connections Handled Delta = 21170 - 21151 => 19 |
| Connections Closed Delta | Difference between two consecutive connection closed entries i.e. \[Number of connection closed - previous entry connection closed]. Example> Log line2 shows Connections Closed Delta = 20972 - 20941 => 31 |
| Transactions Handled Delta | Difference between two consecutive total transactions handled this can be determined by client ID i.e. \[current entry transaction handled - previous entry transaction handled]. Example> Log line2 shows Transactions Handled Delta = 44346 - 44316 => 30 |
| Client Pool Delta | Difference between two consecutive client pool entries i.e. \[present connections in pool waiting state - previous entry pool having connection waiting]. Example> Log line2 shows Client Pool Delta = 132 - 119 => 13 |
| Spare Threads Delta | Difference between two consecutive unused threads entry i.e. \[current unused threads - previous entry unused threads]. Example> Log line2 shows Spare Threads Delta = 8016 - 8016 => 0 |
| Active Threads Delta | Difference between two consecutive entries active threads i.e. \[current active threads - previous entry active threads]. Example> Log line2 shows Active Threads Delta = 66 - 91 => -25 |
| Threads Waiting Delta | Difference between two consecutive entries waiting threads i.e. \[current waiting threads - previous entry waiting threads]. Example> Log line2 shows Threads Waiting Delta = 93 - 68 => 25 |
| Threads Starting up Delta | Difference between two consecutive entries startup/special threads i.e. \[current special threads running - previous entry special threads running]. Example> Log line2 shows Threads Starting up Delta = 17 - 17 => 0 |
| Threads Prefetching Delta | Difference between two consecutive entries prefetching threads running i.e. \[present number of threads used for prefetching - previous entry prefetch threads used]. Example> Log line2 shows Threads Prefetching Delta => 0 |
| Threading Errors Delta | Difference between two consecutive entries count of threads having error i.e. \[total threads having error reported - previous entry error reported thread]. Example> Log line2 shows Threading Errors Delta => 0 |
| Outbound Connections created Delta | Difference between two consecutive entries where new connections are been created i.e. \[count of new connections created - previous entry having count of new connections created]. Example> Log line2 shows Outbound Connections created Delta = 13654 - 13650 => 14 |
| Outbound Connections Failed Delta | Difference between two consecutive entries where connections failed to complete the request i.e. \[Failed connections count - failed connections count]. Example> Log line2 shows Outbound Connections Failed Delta = 976 - 975 => 1 |
| Outbound Connection Pool Reused Delta | Difference between two consecutive entries where pooled connections are been reused i.e. \[connections reused from pool now - connections reused from pool 2 seconds before]. Example> Log line2 shows Outbound Connection Pool Reused Delta = 20660 - 20650 => 10 |
| Outbound Connections in Pool Delta | Difference between two consecutive entries total number of pooled connections i.e. \[connections in pool waiting at present - connections in pool before 2 seconds waiting]. Example> Log line2 shows Outbound Connections in Pool Delta = 139 - 139 => 0 |
| Bytes in (KBytes) Delta | Difference between two consecutive entries total data received in Kilobytes from server i.e. \[Data\[KB] received from server - Data\[KB] received from server 2 seconds before]. Example> Log line2 shows Bytes in Delta = 1854126 - 1853191 => 935 KBytes |
| Bytes Out (KBytes) Delta | Difference between two consecutive entries total data send in Kilobytes from client i.e. \[Data\[KB] send to server - Data\[KB] send to server 2 seconds before]. Example> Log line2 shows Bytes Out Delta = 2014492 - 2012552 => 1940 |
| Caching Objects Created in Memory Delta | Difference between two consecutive entries total caching objects created in memory i.e. \[total caching objects created - total caching objects created 2 seconds before]. Example> Log line2 shows Caching Objects Created in Memory Delta => 0 |
| Caching Objects Removed from Memory Delta | Difference between two consecutive entries total caching objects removed from memory i.e. \[total caching objects removed at present - total caching objects removed 2 seconds before]. Example> Log line2 shows Caching Objects Removed from Memory Delta => 0 |
| DNS Queries Reused Delta | Difference between two consecutive entries total DNS queries used from DNS cache i.e. \[total DNS queries used from cache at present - total DNS queries used from cache 2 seconds before]. Example> Log line2 shows DNS Queries Reused Delta = 11328 - 11317 => 11 |
| New DNS Queries Delta | Difference between two consecutive entries new DNS queries fired by SafeSquid i.e. \[new DNS queries fired at present - new DNS queries 2 seconds before]. Example> Log line2 shows New DNS Queries Delta = 3186 - 3185 => 1 |
| DNS Query failures Delta | Difference between two consecutive entries of the DNS failure count i.e. \[DNS queries failure count at present - DNS queries failure count 2 seconds before]. Example> Log line2 shows DNS Query failures Delta => 0 |
| load avg.(1 min) | 1 Minute System load average when SafeSquid printed this record. Example> Log line2 shows 0.23 of 1 minute load average |
| load avg.(5 min) | 5 Minute System load average when SafeSquid printed this record. Example> Log line2 shows 0.21 of 5 minute load average |
| load avg.(15 min) | 15 Minute System load average when SafeSquid printed this record. Example> Log line2 shows 0.49 of 15 minute load average |
| Running Processes | Total of all SafeSquid Running Processes using CPU time when SafeSquid printed this record. Example> Log line2 shows only 1 running process |
| Waiting Processes | Total of all SafeSquid Waiting Processes waiting for CPU time when SafeSquid printed this record. Example> Log line2 shows 562 Waiting Processes |
| User Time | User time is the amount of CPU time spent in user-mode code (outside the kernel) within the process. i.e. actual CPU time consumed by SafeSquid processes. Example> Log line2 shows Cumulated CPU time consumed by SafeSquid processes is 60.000000 |
| System Time | System time is the amount of CPU time spent in the kernel within the process. This means executing CPU time spent in system calls within the kernel, as opposed to library code, which is still running in user-space. Like 'user', this is only CPU time used by the process. Example> Log line2 shows system time consumed by SafeSquid processes is 56.000000 |
| Total (user + system) Time | User + System will tell you how much actual CPU time your process used. Note that this is across all CPUs, so if the process has multiple threads it could potentially exceed the wall clock time reported by Real. Note that in the output these figures include the User and System time of all child processes as well, although the underlying system calls return the statistics for the process and its children separately. Example> Log line2 shows Cumulated Total of CPU Time consumed due to SafeSquid processes is 116.000000 |
| User Time Delta | Difference between two consecutive entries of total user time i.e. \[CPU time used by SafeSquid at present - CPU time used by SafeSquid before 2 seconds]. Example> Log line2 shows User Time Delta = 0.000000 |
| System Time Delta | Difference between two consecutive entries of total system time i.e. \[CPU time used by SafeSquid at present - CPU time used by SafeSquid before 2 seconds]. Example> Log line2 shows System Time Delta = 0.000000 |
| Total Time Delta | Difference between two consecutive entries of total (system + user) time i.e. \[Present (user+system) time used by SafeSquid - (user+system) time used by SafeSquid before 2 seconds]. Example> Log line2 shows Total Time Delta = 0.000000 |
**Performance Plot**
From the interface go to the Support page. Open the **Performance Plot** tab, select two time intervals to generate the performance plot for that range.
See More about [How to generate the Performance Plot](/use_cases/performance_acceleration/performance_plot)
### Bypass logs
Bypass logs contain the details related to the execution of bypass privilege granted to any user. When users with bypass privilege, execute their privilege to access a web-site that is not explicitly allowed, it is recorded in the bypass logs. It also records the users' opinions about the site. The URLs that were additionally bypassed, to present a seamless experience.
**FORMAT / LEGEND**:
"TimeStamp" "Action" "User "Referrer.Domain" "Requested.Domain" "From/Referral/URL" "Method" "Requested/URL" "Categories,Applied" "Suggested,Categories"
**Example Log Line1:**
```text theme={null}
"2018.09.12:21:07:11" "NOT BYPASSED" "anonymous@192.168.0.24" "microsoft.com" "optimizely.com" "https://powerbi.microsoft.com/" "POST" "[https://logx.optimizely.com:443/v1/events](https://logx.optimizely.com/v1/events)" "business,computersandsoftware" "-"
```
**Example Log Line2:**
```text theme={null}
"2018.09.12:21:07:51" "HOST ADDED" "anonymous@192.168.0.24" "microsoft.com" "optimizely.com" "https://powerbi.microsoft.com/" "POST" "[https://logx.optimizely.com:443/v1/events](https://logx.optimizely.com/v1/events)" "business,computersandsoftware" "test"
```
The details of the fields in bypass.log are as follows:
| Field | Explanation |
| - | - |
| TimeStamp | The date and time when the user with bypass privilege accessed a web-site that is not explicitly allowed. The fields in the date/time field are \[YYYY.MM.DD:hh:mm:ss], where the fields are defined as follows: DD is the day of the month, MMM is the month, YYYY is the year, hh is the hour, mm is the minute, ss is the seconds. Example> 2018.09.12:21:07:11 |
| Action | Action taken by User to either block or bypass the cookie for current URL (either host or referer). User can also re-categorize the current URL into predefined categories. Example> NOT BYPASSED |
| User | The User is annotating as username\@clientip used by the client for authentication. If no value is present, "anonymous" is substituted. Example> anonymous\@192.168.0.24 |
| Referrer.Domain | Domain name of the referrer URL that referred the user to the resource requested. "-" is substituted when there are no referrers. Example> microsoft.com |
| Requested.Domain | Domain name of the requested web-server. Example> optimizely.com |
| From/Referral/URL | From/Referrer/URL is the URL of the HTTP resource that referred the user to the resource requested. "-" is substituted when there are no referrer URL. Example> [https://powerbi.microsoft.com/](https://powerbi.microsoft.com/) |
| Method | A method is part of HTTP request sent by client to the server. Example> POST |
| Requested/URL | Requested/URL is reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. Example> [https://logx.optimizely.com:443/v1/events](https://logx.optimizely.com/v1/events) |
| Categories,Applied | Comma separated list of categories that were applied to the request. "\_" is substituted when no categories are applied. Example> business,computersandsoftware |
| Suggested,Categories | Comma-separated list of categories suggested for the request to access. "\_" is substituted when no categories are suggested. Log line2 is printed after the requested URL is given access with suggestion of re-categorization. Example> test |
### Privacy logs
Privacy Logs are used to record incidences of cookies, and queries going to third-party web sites.
Privacy log captures incidences of third-party web-sites when a user accesses a web-site, and action taken by elevated privacy.
**FORMAT / LEGEND**:
YYYY/mm/DD:HH:MM:SS ClientID username\@IP HTTP-REFERRER METHOD URL \[USER\_AGENT] action
The details of the fields in privacy.log are as follows:
| Field | Explanation |
| - | - |
| YYYY/mm/DD: HH:MM: SS | Time when SafeSquid generated this record and stored in privacy log. SafeSquid begins printing of each record on a new line with the first column as the TimeStamp in YYYY/mm/DD: HH:MM: SS format. |
| ClientID | The internal SafeSquid ID associated with the present/ongoing connection. |
| username\@IP | The username\@IP(or user ID) used by the client for authentication. If no value is present, "anonymous" is substituted. |
| HTTP-REFERRER | An HTTP header field that identifies the address of the age that linked to the resource being requested. "-" is substituted when there is no referrer in HTTP header field. |
| METHOD | A method is part of HTTP request sent by client to the server. |
| URL | An HTTP url is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. |
| \[USER\_AGENT] | User agent is the client which initiates a request. Useraagent are often browsers, editors, spiders(web-traversing robots), or other end user tools. |
| action | Action is the privacy level applied to the request. |
## SafeSquid activity log written in system logs
The path to these log files is as follows:
| Log File | Path |
| - | - |
| **Monit Log** | **/var/log/monit.log** |
| **Syslog** | **/var/log/syslog** |
### Monit log
SafeSquid Uses Monit service for managing and monitoring its process. Monit service is particularly useful for monitoring daemon processes, such as those started at system boot time. While Monit service is running and if SafeSquid process is terminated either manually or automatically then SafeSquid will be restarted. Also, Monit service plays a crucial role when user want to modify any startup parameter or upgrade the SafeSquid version.
**FORMAT**:
\[date] priority : message
**Example Log Lines**:
**\[IST Jan 20 13:08:37] info : 'safesquid' trying to restart
\[IST Jan 20 13:08:37] info : 'safesquid' start: /etc/init.d/safesquid
\[IST Jan 20 13:08:40] error : 'safesquid.dns.conf' timestamp was changed for /usr/local/safesquid/security/dns/safesquid.dns.conf
\[IST Jan 20 13:08:40] info : 'safesquid.dns.conf' exec: /bin/bash
\[IST Jan 20 13:08:40] error : 'upgrade' timestamp was changed for /tmp/safesquid/upgrade
\[IST Jan 20 13:08:40] info : 'upgrade' exec: /bin/bash
\[IST Jan 20 13:08:40] error : 'safesquid.ldb' file doesn't exist
\[IST Jan 20 13:08:40] info : 'safesquid.ldb' trying to restart
\[IST Jan 20 13:08:43] error : 'Logs' space usage 86.9% matches resource limit \[space usage>5.0%]
\[IST Jan 20 13:08:43] info : 'safesquid' process is running with pid 1815
\[IST Jan 20 13:08:43] error : 'named' process PID changed from 1170 to 1891
\[IST Jan 20 13:08:43] info : 'safesquid.dns.conf' timestamp was not changed for /usr/local/safesquid/security/dns/safesquid.dns.conf
\[IST Jan 20 13:08:43] info : 'upgrade' timestamp was not changed for /tmp/safesquid/upgrade**
### Syslog
Linux's syslog service provides a highly configurable logging system. Some messages triggered by SafeSquid application are been stored in syslog. Syslog is a standard log for sending and receiving notification messages--in a particular format--from various network devices. The messages include time stamps, event messages, severity, host IP addresses, diagnostics and more.
Syslog was designed to monitor network devices and systems to send out notification messages if there are any issues with functioning--it also sends out alerts for pre-notified events and monitors suspicious activity via the change log/event log of participating network devices.
You will find log lines of SafeSquid application in the syslog file.
**Example Log Lines**:
**2020 01 20 14:25:08 \[-1] init: Startup Log: /var/log/syslog
2020 01 20 14:25:08 \[-1] init: safesquid: start called
2020 01 20 14:25:08 \[-1] init: USER: ssquid exists
2020 01 20 14:25:08 \[-1] init: ssquid: checking for group membership: root
2020 01 20 14:25:08 \[-1] init: ssquid: has group memberships: root
2020 01 20 14:25:08 \[-1] init: ssquid: is member of group: root
2020 01 20 14:25:08 \[-1] init: export MALLOC\_CHECK\_=2
2020 01 20 14:25:08 \[-1] init: debug: invoking tcp\_tune
2020 01 20 14:25:08 \[-1] init: RAMDEVICE /dev/ram1 does not exist, and therefore cannot be used
2020 01 20 14:25:08 \[-1] init: LIBS\_DIR: /opt/safesquid/libs no preload libraries found
2020 01 20 14:25:08 \[-1] init: validating: OPT\_DIR:/opt/safesquid with permissions ug=rwX,o=r
2020 01 20 14:25:08 \[-1] init: already exists: OPT\_DIR:/opt/safesquid
2020 01 20 14:25:08 \[-1] init: SET\_PERMISSION: OPT\_DIR:/opt/safesquid ug=rwX,o=r
2020 01 20 14:25:08 \[-1] init: validating: USR\_LOCAL\_DIR:/usr/local/safesquid with permissions ug=rwX,o=r
2020 01 20 14:25:08 \[-1] init: already exists: USR\_LOCAL\_DIR:/usr/local/safesquid
2020 01 20 14:25:08 \[-1] init: SET\_PERMISSION: USR\_LOCAL\_DIR:/usr/local/safesquid ug=rwX,o=r
2020 01 20 14:25:08 \[-1] init: validating: TMP\_DIR:/tmp/safesquid with permissions ug=rwX,o=r
2020 01 20 14:25:08 \[-1] init: already exists: TMP\_DIR:/tmp/safesquid
2020 01 20 14:25:08 \[-1] init: SET\_PERMISSION: TMP\_DIR:/tmp/safesquid ug=rwX,o=r**
[https://help.safesquid.com/portal/en/kb/articles/identify-the-filter-by-using-safesquid-extended-logs-or-detailed-logs](https://help.safesquid.com/portal/en/kb/articles/identify-the-filter-by-using-safesquid-extended-logs-or-detailed-logs)
[https://help.safesquid.com/portal/en/kb/articles/identify-the-filter-name-using-safesquid-detailed-logs-from-the-interface](https://help.safesquid.com/portal/en/kb/articles/identify-the-filter-name-using-safesquid-detailed-logs-from-the-interface)
[https://help.safesquid.com/portal/en/kb/articles/forwarding-logs-to-the-siem-server-by-configuring-the-udp-port](https://help.safesquid.com/portal/en/kb/articles/forwarding-logs-to-the-siem-server-by-configuring-the-udp-port)
## Use logs intentionally
When operators know which question they are answering, they can move to the right log family faster:
* use `extended.log` when you need user, URL, status, filter, profile, category, and application evidence for a specific transaction
* use `safesquid.log` when you need feature-level behavior and debugging detail
* use `config.log` when you need to know what changed and when
* use `performance.log` when the problem is latency, load, or resource pressure
* use `bypass.log` when a blocked request appears to have been overridden
* use `privacy.log` when privacy controls, cookie handling, or third-party requests are under review
* use `/var/log/monit.log` and `/var/log/syslog` when the issue may be service health, startup, or host-level behavior
## Verification and validation
### Positive test
Trigger a controlled policy event, such as a known block, bypass, or login-authenticated request, then verify that:
* the event appears in the expected log family
* the username, client IP, URL, and status line up with the test
* the applied filter or profile matches the intended policy path
### Negative test
Run a normal allowed request that should not trigger a block, bypass, or privacy event.
Expected result:
* the request appears in the normal request evidence path
* no misleading bypass or filter event is recorded
### Audit evidence
For investigation and audit readiness, retain:
* the exact time window used for the search
* the username or client IP
* the URL or domain involved
* the filter, profile, category, or application fields that justify the decision
* related `config.log` entries when a policy change may have caused the observed behavior
## Troubleshooting guide
### Operators cannot find a request that users insist happened
Likely causes:
* the wrong time window is being searched
* the traffic bypassed the expected SafeSquid path
* the wrong log family is being checked
Isolation steps:
* confirm the client IP, username, and approximate timestamp
* search `extended.log` first for request evidence
* verify the client was actually using SafeSquid during the incident
Remediation:
* narrow the time range and search by URL, user, and status
* investigate bypass paths or alternate egress
* preserve the exact search criteria once the event is found
### A request was blocked, but the team cannot tell why
Likely causes:
* only status codes are being reviewed
* the filter and profile fields were not checked
* a recent configuration change altered behavior
Isolation steps:
* inspect `extended.log` for `filter_name`, `filtering_reason`, and applied profiles
* inspect `config.log` for recent rule changes
* compare the event against a known-good earlier transaction
Remediation:
* document the exact filter path that triggered
* rollback or adjust the offending configuration if needed
* retest the same URL or payload
### Logging exists, but evidence is too thin for incident review
Likely causes:
* teams rely only on summary views
* log retention or forwarding is incomplete
* verbose logging was disabled during the incident window
Isolation steps:
* confirm which raw log files were available during the event
* confirm whether SIEM forwarding captured the same period
* review whether the selected log level supported the needed detail
Remediation:
* preserve raw logs for the affected window
* improve forwarding and retention coverage
* adjust logging strategy for future investigations, then validate with a fresh test
## Related controls / next steps
* Use [Reporting Module](/use_cases/audit_and_forensics/reporting_module) for operational dashboards and exported evidence.
* Use [Monit](/use_cases/audit_and_forensics/audit_forensics_monit) when service-restart events and local watchdog health are part of the investigation.
# Active Directory
Source: https://docs.safesquid.com/use_cases/authentication/active_directory
Integrate SafeSquid with Active Directory for seamless user authentication, SSO, and group-based access control.
# Active Directory Integration
Integrate SafeSquid with Active Directory (AD) to enable centralized user management, group-based access policies, and seamless Single Sign-On (SSO) for domain-joined users.
## Problem statement
Large Windows environments need proxy policy and reporting tied to Active Directory identities and groups. Without that linkage, audit evidence degrades into IP addresses and generic browsing records.
## Active Directory Integration Workflow
| Step | Task | Goal |
| - | - | - |
| 1 | [Setup AD Integration](/use_cases/authentication/setup_active_directory_integration) | Link SafeSquid with AD and fetch user/group entities. |
| 2 | **Choose Auth Method** | Decide between Simple (prompt) or SSO (transparent) authentication. |
| 3 | [Simple Authentication](/use_cases/authentication/ad_simple_authentication) | Browser prompts users for AD credentials. |
| 4 | [SSO Authentication](/use_cases/authentication/ad_sso_authentication) | Transparent authentication for domain-joined users via Kerberos. |
## Which AD authentication method to use?
| Feature | Simple Authentication | SSO Authentication |
| - | - | - |
| **User Experience** | Browser login prompt | Transparent (no prompt) |
| **Domain Requirement** | None (works for any device) | Client must be domain-joined |
| **Complexity** | Low (LDAP bind) | Moderate (Kerberos, DNS, Time Sync) |
| **Primary Use Case** | Guest devices, non-domain PCs | Standard corporate workstations |
:::tip
**Recommendation**
Most enterprises use **SSO Authentication** for corporate domain-joined workstations to provide the best user experience, and **Simple Authentication** as a fallback for guest or non-domain devices.
:::
## Critical dependencies
Active Directory integration depends on:
* directory reachability
* correct DNS
* correct time synchronization for Kerberos
* correct client assumptions for domain-joined and non-domain devices
If DNS or NTP is wrong, AD authentication can fail even when the proxy itself is healthy.
## Verification
After completing the integration:
1. **Fetch Entries:** Verify that AD users and groups appear in the SafeSquid **LDAP Entities** section.
2. **Test Rule:** Create an access rule that requires AD authentication.
3. **Log Check:** Confirm `identity.log` shows the correct AD username in `DOMAIN\user` or UPN format.
## Troubleshooting
**Symptom:** Domain users still see browser prompts.\
**Likely cause:** Kerberos SSO prerequisites are not satisfied, or the device is not eligible for transparent auth.\
**Isolation:** Check DNS, NTP, and domain-join assumptions.\
**Remediation:** Fix the dependency or use the simple-auth path for that device class.\
**Retest:** Retry the same flow and confirm transparent or expected authentication behavior.
**Symptom:** Users authenticate but group-based policy does not apply.\
**Likely cause:** Group retrieval or rule mapping is incomplete.\
**Isolation:** Confirm group visibility in SafeSquid and compare rule matching.\
**Remediation:** Refresh directory entities and correct the rule scope.\
**Retest:** Compare users from different AD groups against the same policy target.
## Source register
| Topic | Status | Source |
| - | - | - |
| Setup → Simple → SSO flow | **Confirmed** | Linked task pages in this hub |
| Kerberos / time sync prerequisites | **Confirmed** | [SSO Authentication](/use_cases/authentication/ad_sso_authentication), [NTP](/architecture/interface/ntp) |
| RODC path | **Confirmed** | [Kerberos with RODC](/use_cases/authentication/configure_kerberos_authentication_with_rodc) |
## Next steps
* Start with [Setup Active Directory Integration](/use_cases/authentication/setup_active_directory_integration) to establish the initial connection.
* Configure [Access Restriction](/use_cases/access_restriction/access_restriction) to apply policies based on AD groups.
# Simple Authentication
Source: https://docs.safesquid.com/use_cases/authentication/ad_simple_authentication
Configure Active Directory simple (LDAP) authentication in SafeSquid for browser-prompted user identification.
# AD Simple Authentication
Simple authentication validates domain users via LDAP bind. When users browse the web, they are prompted by their browser to enter their Active Directory credentials.
## Problem statement
Not every device can participate in Kerberos SSO. Guest devices, non-domain systems, and troubleshooting cases still need directory-backed identity without falling back to anonymous IP-only control.
## When to use Simple Authentication
| Use Simple Auth When | Use SSO (Kerberos) Instead |
| - | - |
| Client devices are not joined to the domain | Corporate workstations are domain-joined |
| Fast setup is required (no Kerberos config) | Best user experience (no prompt) is required |
| Troubleshooting authentication issues | Production environment for domain users |
:::note
**Prerequisites**
* [Setup Active Directory Integration](/use_cases/authentication/setup_active_directory_integration) must be completed.
* SafeSquid must be able to fetch LDAP entities (verify in **LDAP Entities** tab).
* DNS and NTP must be healthy, even for prompt-based AD-backed authentication, because directory reachability and environment consistency still matter.
:::
## Configure Simple Authentication
1. **Access SafeSquid Interface:** Go to **Application Setup** → **Integrate LDAP**.
2. **Enable Section:** Ensure the **Integrate LDAP** global section is set to **TRUE**.
3. **Configure LDAP Server:**
* Go to **LDAP Servers** tab.
* Edit your AD server entry.
* Ensure **LDAP Bind Method** is set to **SIMPLE** (for browser-prompt authentication).
4. **Save Configuration:** Click the checkmark to save.
![Ensure LDAP Enabled]()
## Enable Authentication in Access Rules
1. **Go to Access Restrictions:** **Application Setup** → **Access Restrictions** → **Allow List**.
2. **Edit Rule:** Find the rule matching your client IPs or create a new one.
3. **Configure Auth:**
* **PAM Authentication:** Set to **TRUE**.
* **LDAP Profiles:** (Optional) Select specific AD groups if this rule only applies to them. Leave blank for all AD users.
4. **Save Policy:** Click the checkmark to save.
## Operational notes
* Use simple authentication when transparent SSO is not viable for the target device class.
* Keep the prompt-based user experience explicit in rollout planning so support teams know this is expected behavior, not a failure.
* Narrow bypasses carefully, because overbroad bypass weakens user attribution in logs and reports.
## Verification
| Action | Method | Expected Result |
| - | - | - |
| **Browser Test** | Access any website from a client. | A browser login prompt should appear. |
| **Login Test** | Enter valid AD credentials. | Access is granted; the website loads. |
| **Identity Log** | `tail -f /var/log/safesquid/identity.log` | The log shows the authenticated AD username. |
| **Detailed Log** | **Reports** → **Detailed Logs** | Requests are tagged with the directory username and group. |
## Troubleshooting
## Troubleshooting
| Symptom | Likely Cause | Fix |
| - | - | - |
| No login prompt | Rule order or IP mismatch | Ensure the authentication rule is above general allow rules; verify client IP matches rule scope. |
| Prompt keeps reappearing | Incorrect AD credentials or Bind DN | Verify user password in AD; ensure the bind account in LDAP integration has read access. |
| Authentication fails | Directory reachability, DNS, or time issue | Verify AD reachability, sync time with AD, and ensure AD FQDN resolution works. |
| Valid users blocked | Group membership issue | Check whether the user is a member of the group specified in **LDAP Profiles**. |
## Source register
| Topic | Status | Source |
| - | - | - |
| Browser prompt + AD bind | **Confirmed** | This page |
| Time skew / DNS with AD | **Confirmed** | Troubleshooting, [NTP](/architecture/interface/ntp) |
## Next steps
* [Configure SSO Authentication](/use_cases/authentication/ad_sso_authentication) for a transparent user experience.
* [Access Restriction](/use_cases/access_restriction/access_restriction) to define policies by AD group.
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) to attribute HTTPS traffic to AD users.
# SSO Authentication
Source: https://docs.safesquid.com/use_cases/authentication/ad_sso_authentication
Configure Kerberos-based Single Sign-On (SSO) with Active Directory for transparent user authentication in SafeSquid.
# AD SSO Authentication (Kerberos)
Kerberos-based SSO provides a seamless user experience for domain-joined workstations. Users are authenticated transparently via their domain ticket, eliminating browser credential prompts.
## Problem statement
Corporate Windows fleets need transparent authentication so the proxy can enforce identity-aware policy without constant credential prompts. Kerberos SSO is the documented path for that experience in Active Directory environments.
## How Kerberos SSO Works
```mermaid theme={null}
sequenceDiagram
participant Client as Domain Client
participant SafeSquid
participant AD as Active Directory
Client->>SafeSquid: HTTP(S) request (Negotiate)
SafeSquid->>AD: Validate Kerberos ticket
AD-->>SafeSquid: User Identity & Group Membership
SafeSquid->>SafeSquid: Apply Group Policy
SafeSquid-->>Client: Allow / Deny
```
:::note
**Prerequisites**
* [Setup Active Directory Integration](/use_cases/authentication/setup_active_directory_integration) completed.
* **Time Sync:** SafeSquid and AD server time must match (max skew 5 mins).
* **DNS:** SafeSquid must resolve the AD domain; AD must have a DNS entry for SafeSquid.
* **Monit:** The Monit service must be running (`pidof monit`).
* Clients must actually be domain-joined and eligible for Kerberos-based transparent authentication.
:::
## Configure SSO Authentication
1. **Access SafeSquid Interface:** Go to **Application Setup** → **Integrate LDAP**.
2. **Configure LDAP Server:**
* Go to **LDAP Servers** tab and edit your entry.
* **LDAP Bind Method:** Select **NEGOTIATE** (this enables Kerberos SSO).
* **Bind DN:** Ensure this is a domain admin or account with high privileges to create the keytab.
3. **Automatic Keytab Generation:**
When you save with **NEGOTIATE**, SafeSquid automatically generates:
* `HTTP.keytab`
* `krb5.conf`
* `krb.tkt`
Verify these in `/usr/local/safesquid/security/`.
![selecting negotiate from the drop down menu]()
4. **DNS Stub Zone:** SafeSquid creates a stub zone for AD resolution in `/etc/bind/safesquid.dns.conf`. Ensure this is active.
## Operational notes
* This page is the documented transparent-authentication path for AD. Do not generalize the same SSO claim to non-AD directory flows without proof.
* Browser and zone configuration matter. A technically correct Kerberos setup can still appear broken if the client refuses to send the ticket.
* Treat keytab and Kerberos material as operationally sensitive assets.
## Enable SSO in Access Rules
1. **Navigate to Access Restrictions:** **Application Setup** → **Access Restrictions** → **Allow List**.
2. **Configure Rule:**
* **PAM Authentication:** Set to **TRUE**.
* **SSO:** Ensure the global SSO field is **TRUE** (default).
3. **Save and Apply:** Click the checkmark to save.
## Verification
| Action | Method | Expected Result |
| - | - | - |
| **Transparent Login** | Access a website from a domain-joined client. | Website loads immediately without a credential prompt. |
| **Check Keytab** | `ls -l /usr/local/safesquid/security/HTTP.keytab` | File exists and has recent timestamp. |
| **Identity Log** | `tail -f /var/log/safesquid/identity.log` | Shows authenticated usernames in `user@DOMAIN` format. |
| **DNS Test** | `nslookup ` from SafeSquid. | Successfully resolves to AD server IP. |
## Troubleshooting
| Symptom | Likely Cause | Fix |
| - | - | - |
| Repeated prompts (SSO fail) | Time skew | Run `date` on AD and SafeSquid; sync via NTP if they differ by more than 5 minutes. |
| Prompt on some browsers | Browser config or client eligibility | Ensure the client is domain-joined and the SafeSquid host is treated as an intranet or delegated target where required. |
| Keytab not generated | Permission or Bind issue | Ensure the bind account has sufficient AD permissions; check `/var/log/safesquid/native/safesquid.log` for Kerberos errors. |
| DNS resolution fail | Missing or wrong stub zone | Verify `/etc/bind/safesquid.dns.conf` contains the correct AD server IP and is included in your BIND config. |
:::tip
**Browser Configuration**
For Chrome and Edge to send Kerberos tickets, the SafeSquid proxy URL must be recognized as an intranet site. You can enforce this via GPO:
**Administrative Templates** → **Google Chrome** → **Kerberos delegation server allowlist**
:::
## Source register
| Topic | Status | Source |
| - | - | - |
| Kerberos SSO, keytab, time skew | **Confirmed** | This page, [NTP](/architecture/interface/ntp) |
| BIND stub for AD DNS | **Confirmed** | This page, [BIND](/architecture/interface/bind) |
| Chrome/Edge intranet zone for Kerberos | **Confirmed** | Tip above (browser behavior) |
## Next steps
* [Access Restriction](/use_cases/access_restriction/access_restriction) (Apply policies by AD group)
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) (Attribute HTTPS traffic to AD users)
* [Bypass Authentication](/use_cases/authentication/bypass_authentication) (For non-browser apps that don't support Kerberos)
# Authentication
Source: https://docs.safesquid.com/use_cases/authentication/authentication
Configure user authentication in SafeSquid using BASIC, Network Signature, Directory Services (including Kerberos SSO), PAM, and bypass rules.
## Problems addressed
Without attributable user or device context, HTTPS and HTTP policy, reporting, and forensics collapse to anonymous IP addresses. Regulators and incident responders expect **who accessed what** when proxies sit in the path.
## Outcomes operators expect
* Directory-backed accounts, SSO, or local credentials for interactive users.
* IP-to-group mapping where login prompts are impossible.
* Controlled bypass for break-glass and non-interactive workloads.
* Identity lines in logs for audit—see verification steps on this page.
## Supported identity backends
Confirmed product knowledge supports these identity integrations:
* Active Directory
* LDAP
* Kerberos
Roadmap items that should **not** be documented as current product capabilities:
* RADIUS
* SAML
## Advantages vs “proxy without identity”
SafeSquid ties **Authentication** rules to the same policy engine as URL, content, and time rules ([Access Restriction](/use_cases/access_restriction/access_restriction)). **MFA:** SafeSquid does not render MFA UI itself; MFA arrives via directory or PAM backends (see note below).
**Comparative authentication feature matrix vs other SWG products:** **Not SSOT-backed in this doc set**—see [What is SafeSquid SWG?](/architecture/what_is_safesquid_swg).
## Acquire, deploy, use
Pick one primary method from the table below, configure it in the SafeSquid administration UI, then validate `identity.log` and browser behavior per **Verification**.
SafeSquid identifies users through multiple authentication methods to enable identity-based access control and audit trails. Methods can be used individually or in combination to suit enterprise requirements.
:::note
**Multi-factor authentication**
SafeSquid itself does not provide MFA prompts. To enforce MFA, integrate with directory services (Active Directory with MFA-enabled accounts) or use PAM with MFA modules (e.g., Google Authenticator PAM). SafeSquid enforces the authentication decision but delegates credential validation to the backend system.
:::
## Choose your authentication method
| Method | Use When | User Experience | Infrastructure Required |
| - | - | - | - |
| [BASIC Authentication](/use_cases/authentication/basic) | No directory service available | Browser login prompt | None |
| [Architecture](/architecture/overview/safesquid_swg) | IP-based policy needed (devices, legacy apps) | Transparent (no login) | Static IP addressing or DHCP reservations |
| [Directory Services](/use_cases/authentication/directory_services) | Centralized identity required | Browser prompt or SSO | Active Directory or OpenLDAP |
| [PAM Authentication](/use_cases/authentication/pam) | OS credentials should apply to proxy | Browser login prompt | PAM-capable OS |
| [Bypass Authentication](/use_cases/authentication/bypass_authentication) | Some apps cannot authenticate | Transparent for bypassed apps | None |
## Authentication methods
### [BASIC Authentication](/use_cases/authentication/basic)
BASIC authentication (RFC 7617) with credentials stored locally in SafeSquid. Browser-prompt authentication with no directory infrastructure required; credentials managed locally. Use when you need identity-based policies without Active Directory or LDAP.
### [IP-based recognition in architecture](/architecture/overview/safesquid_swg)
Maps source IPs or subnets to user-groups for group-based access restriction and reporting. No user login required; policy applies by IP. Use when user identity is unavailable (device-only, legacy apps) but you need group-based rules.
### [Directory Services](/use_cases/authentication/directory_services)
Integrates with Active Directory or OpenLDAP to leverage existing user accounts and group memberships. Supports simple authentication and Kerberos-based SSO where configured. Use when you need centralized identity management and don't want to duplicate user accounts in SafeSquid.
### [PAM Authentication](/use_cases/authentication/pam)
Validates proxy users via the system PAM stack so OS and proxy share credentials. Use when you want a single credential set for both OS login and proxy access in PAM-based environments (Linux, Unix).
### [Bypass Authentication](/use_cases/authentication/bypass_authentication)
Allows specific destinations or request types to skip authentication while other traffic remains authenticated. Use for automatic updates or apps that cannot send proxy credentials.
## Combining authentication methods
SafeSquid evaluates authentication rules in the order they appear in the policy. The first matching rule applies (no fall-through). Common combinations:
* **Directory + Bypass:** AD/LDAP for users, bypass for OS updates and app sync
* **Network Signature + Directory:** IP-based groups for IoT/devices, AD for user workstations
* **PAM + Bypass:** OS credentials for interactive users, bypass for service accounts
:::tip
Apply authentication rules from most specific to most general. Place narrow bypass rules before broader authentication requirements.
:::
## Production considerations
* Authentication is not only for access control. It is also required for meaningful reporting, audit evidence, and incident investigation.
* Kerberos and other directory-based methods depend on reliable time synchronization. If NTP is unhealthy, authentication can fail even when the proxy path is otherwise correct.
* Bypass rules should be kept narrow. Overbroad bypass weakens attribution and creates false confidence in reporting.
## Verification
After configuring authentication:
1. **Test login flow:** Browse through the proxy from a client; confirm authentication prompt appears (or SSO succeeds)
2. **Check identity logs:** Verify `/var/log/safesquid/identity.log` shows authenticated usernames for proxied requests
3. **Test bypass (if configured):** Confirm bypassed destinations work without prompts
4. **Check reporting impact:** Confirm the authenticated user identity appears in the reporting path and detailed logs
## Troubleshooting
**Symptom:** Users browse, but logs show anonymous IPs.\
**Likely cause:** Authentication is not actually applied to the tested path, or bypass rules are matching first.\
**Isolation:** Compare the request against the authentication rule order and identity logs.\
**Remediation:** Reorder or narrow the rules.\
**Retest:** Repeat the same request and confirm the user identity appears.
**Symptom:** Kerberos or SSO fails unexpectedly.\
**Likely cause:** Directory integration, time synchronization, or client trust assumptions are wrong.\
**Isolation:** Check directory reachability, NTP health, and the exact client path.\
**Remediation:** Restore time sync and correct the AD or Kerberos integration settings.\
**Retest:** Repeat the SSO flow and confirm silent or expected authentication behavior.
**Symptom:** Some applications fail only after authentication is enabled.\
**Likely cause:** The application cannot handle proxy authentication.\
**Isolation:** Test the same application with and without a narrow bypass rule.\
**Remediation:** Add a tightly scoped bypass for that application path if justified.\
**Retest:** Confirm the application works without weakening broad user attribution.
## Source register
| Topic | Status | Source |
| - | - | - |
| BASIC, Network Signature, Directory, PAM, Bypass flows | **Confirmed** | Linked method pages in this section |
| MFA via directory / PAM (not SafeSquid UI) | **Confirmed** | Note on this page |
| First-match rule order | **Confirmed** | **Combining authentication methods** above |
| SAML as a first-class auth mode in UI | **Not current** | Internal knowledge marks SAML as roadmap, not shipping capability |
## Next steps
1. Choose an authentication method above and configure it
2. Combine with [Access Restriction](/use_cases/access_restriction/access_restriction) for identity-based policies
3. Enable [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) to decrypt HTTPS traffic — without it, SafeSquid can only authenticate based on CONNECT requests, not actual HTTPS content
# Local Credential Store
Source: https://docs.safesquid.com/use_cases/authentication/basic
Configure SafeSquid for browser-based user authentication without Active Directory using local credential storage.
# BASIC Authentication
Browser-prompt authentication with usernames and passwords stored locally in SafeSquid. No directory infrastructure required; credentials are managed locally in SafeSquid or via OS users. Use when you need identity-based access control without Active Directory or LDAP.
## Problems addressed
Some sites lack Active Directory or LDAP. Operators still need **named** identities in logs and access rules instead of anonymous client IPs.
## Outcomes operators expect
* Browser prompts and successful binds recorded in `identity.log` when configured correctly.
* Identity-aware Allow List rules without directory infrastructure.
## Advantages vs directory-backed authentication
BASIC avoids directory rollout cost and suits small or isolated footprints. Trade-off: local credential hygiene, no central SSO, and transport caveats in **Security consideration** below.
## Acquire, deploy, use
Follow **Enable browser authentication** through **Verification**; then combine with [Access Restriction](/use_cases/access_restriction/access_restriction) and optional [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection).
## When to use BASIC authentication
| Use BASIC When | Use Directory Services Instead |
| - | - |
| No Active Directory or LDAP | Enterprise with existing AD/LDAP |
| Small organization (\<50 users) | Need centralized identity management |
| Isolated environment | SSO requirement |
| Quick proof of concept | Audit requires directory-backed auth |
:::caution
**Security consideration**
BASIC authentication sends credentials in base64 encoding (not encrypted). Use only on:
* Internal networks, or
* HTTPS proxy connections, or
* With SSL inspection enabled
For production deployments with external access, use [Directory Services](/use_cases/authentication/directory_services) with TLS.
:::
:::note
**Prerequisites**
* SafeSquid deployed and operational
* Admin access to SafeSquid configuration interface (`http://safesquid.cfg/` — embedded Rest UI, NOT DNS-resolved)
* Browser configured to use SafeSquid as proxy (see [Connect Your Client](/getting_started/client_configuration/connect_your_client))
:::
## Enable browser authentication
1. **Access SafeSquid Configuration**\
Open `http://safesquid.cfg/` through a browser using the SafeSquid proxy.
2. **Navigate to Access Restrictions**\
**Application Setup** → **Access Restrictions** → **Allow List**\
Click the orange **+** icon to add a new entry.
![Going in the access restrictions section in application setup]()
3. **Configure Authentication**\
In the new rule window:
* Set **PAM Authentication** to **FALSE** (we're using local credentials, not OS PAM)
* Leave **Username** and **Password** empty to apply authentication to all users (or enter specific username/password to restrict this rule to a single user)
![Making the PAM authentication false and adding username and password in the username password field]()
4. **Save the Configuration**\
Click the checkmark to save the rule.
:::tip
This creates the authentication requirement. Users will be prompted for credentials when browsing. Next step: add users.
:::
:::tip
**Apply changes**
After adding users or modifying access rules, click **Apply** in the Access Restrictions section to activate the changes immediately without restarting SafeSquid.
:::
## Add users
**Best for:** Adding individual users with SafeSquid-only access
1. **Navigate to Access Profiles**\
Click **Configure** → **Search** → **Access Profiles**
![Click Configure in the SafeSquid interface]()
![Click Search in Access Profiles]()
2. **Create User Entry**\
Click **Add New** → Select **BASIC** authentication type
![Access profiles search or policy list]()
![Edit or add BASIC auth user entry]()
3. **Enter Credentials**\
Add username and password for the user
![BASIC authentication user form or credentials]()
4. **Save and Apply**\
Save the user entry and apply to the access restriction rule
![Save BASIC auth user or policy]()
![BASIC auth profile applied to access restriction]()
![Configuration saved for BASIC authentication]()
**Best for:** Users who also need OS login access
1. **Create a New User**
```bash theme={null}
useradd name_of_the_user
```
2. **Set the Password**
```bash theme={null}
passwd name_of_the_user
```
Enter and confirm the new password when prompted.
![Changing the password]()
3. **Enable PAM in Access Rule**\
In SafeSquid **Access Restrictions** → **Allow List**, edit your access rule and set **PAM Authentication** to **TRUE**. This allows SafeSquid to validate against OS users.
:::tip
Use this method when you want proxy credentials to match OS login credentials (single credential set).
:::
## Verification
1. **Test Authentication Flow**
* Open a browser configured to use SafeSquid as proxy
* Browse to any external site (e.g., `http://example.com`)
* Authentication prompt should appear
* Enter configured credentials
* Access is granted when authentication succeeds
2. **Verify in Interface**\
**Access Restrictions** → **Allow List** shows the rule with authentication enabled
3. **Check Logs**
```bash theme={null}
tail -f /var/log/safesquid/identity.log
```
You should see entries with authenticated usernames for proxied requests.
## Troubleshooting
| Symptom | Likely Cause | Fix |
| - | - | - |
| No login prompt appears | Authentication not enabled in access rule | Set PAM Authentication to TRUE (for OS users) or FALSE (for SafeSquid credential store); ensure rule matches client IP |
| Login fails repeatedly | Incorrect credentials or misconfigured rule | Verify username/password; check if using PAM (OS users) vs SafeSquid credential store |
| Some users can't login | User not added or wrong method | Confirm user exists (OS or SafeSquid interface) and matches the authentication method configured (PAM vs BASIC) |
| Rule not applied | IP mismatch or rule order | Ensure client IP matches the rule; check rule order in Allow List |
## Credential management best practices
SafeSquid's local credential store does not enforce password policies automatically. Implement these manually:
* **Password strength:** Require min 12 chars with complexity when creating accounts
* **Rotation:** Manually update credentials every 90 days for compliance
* **Audit:** Review `/var/log/safesquid/identity.log` monthly for unauthorized attempts
* **Segregation:** Create separate user accounts for different roles/groups
For automated password policy enforcement, migrate to [Directory Services](/use_cases/authentication/directory_services).
## Source register
| Topic | Status | Source |
| - | - | - |
| RFC 7617 BASIC flow | **Confirmed** | This page, UI paths |
| Local credential store vs PAM toggle | **Confirmed** | This page |
| `identity.log` evidence | **Confirmed** | Verification section above |
## Next steps
* **Add group-based policies:** Combine authentication with [Access Restriction](/use_cases/access_restriction/access_restriction) to enforce different rules per user or group
* **Attribute HTTPS traffic:** Enable [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) so encrypted traffic shows authenticated usernames in logs
* **Upgrade to directory:** Migrate to [Directory Services](/use_cases/authentication/directory_services) when user count grows or centralized identity is required
* **IP-based fallback:** Use the [Architecture hub](/architecture/overview/safesquid_swg) for devices that cannot authenticate
* **Bypass apps:** Configure [Bypass Authentication](/use_cases/authentication/bypass_authentication) for OS updates and automatic processes
# Bypass Authentication
Source: https://docs.safesquid.com/use_cases/authentication/bypass_authentication
Configure tightly scoped authentication bypass in SafeSquid for non-interactive destinations and applications that cannot complete proxy authentication.
# Bypass authentication only where attribution is impossible
## Problem statement
Some applications and destinations cannot respond to proxy authentication challenges. If you force interactive authentication on those flows, updates fail, background sync breaks, and service traffic stops. If you bypass too broadly, you lose identity attribution and create blind spots in enforcement and audit review.
## Client scenario
Use Authentication Bypass when you need to:
* allow operating system or application update traffic that cannot prompt for credentials
* keep non-interactive sync clients working
* exempt narrowly defined destinations or request types from authentication
Avoid using bypass for ordinary browsing or any workflow where user attribution matters.
## Key benefits
A narrow bypass policy lets SafeSquid preserve authentication for general web use while allowing specific machine-driven or application-driven traffic to function. The goal is operational continuity with the smallest possible loss of attribution.
## Prerequisites
### Client-side preparations
* Identify the exact application, destination, or traffic pattern that fails under authentication.
* Capture the hostnames or request characteristics before building the bypass.
### SafeSquid-side setup
* Confirm your main authentication path is already working for normal traffic.
* Decide whether the bypass should be built from an existing default policy or from a new request-type and access-profile combination.
## When to use bypass
| Use bypass when | Keep authentication instead |
| - | - |
| application cannot prompt for credentials | interactive web browsing |
| OS or security updates must run unattended | corporate apps needing user attribution |
| background sync clients fail on auth prompts | sensitive-data access workflows |
| trusted machine-driven traffic is well scoped | any broad internet access path |
:::caution
Bypassed traffic is not attributed to a specific authenticated user. Keep the bypass as narrow as possible and prefer specific destinations or request characteristics over broad domain patterns.
:::
## Setup instructions
### Open the configuration workflow
Open the [Configuration Portal](/architecture/interface/configuration_portal) and move into the relevant policy areas.
![Enable bypass authentication step 1]()
### Enable the global bypass section
Search for the bypass-authentication policy area and set the global **Enabled** state to `TRUE`.
![Enable bypass authentication step 2]()
This activates the section that allows SafeSquid to exempt matching traffic from authentication.
### Review the default bypass entries first
SafeSquid includes default policies for bypassing authentication for selected applications and categories. Review those before creating new logic so you do not duplicate or conflict with the existing baseline.
![Default bypass policies for applications and categories]()
### Create a request-type for the exact traffic
Go to the request-type area and create a rule that identifies the target application or destination precisely.
The existing Dropbox-style example remains useful:
* use **Host Name** to match the destination
* enable **Smart TLD** if the application uses multiple country or service domains
* add a dedicated request type such as `DROPBOX REQUESTS`
![Bypass authentication request-type workflow step 1]()
![Bypass authentication request-type workflow step 2]()
### Bind the request-type to an access profile
Create or edit an access-profile policy that consumes the request type and adds a profile such as `AUTHENTICATION BYPASS`.
This is the step that turns request classification into actual bypass behavior.
![Bind request type to authentication bypass profile]()
![Save authentication bypass access profile]()
### Keep the pattern narrow
Do not use a broad wildcard when a specific FQDN or application pattern is enough. A bypass is safest when it matches only the non-interactive flow you intended to exempt.
## Verification and validation
### Positive tests
Test the exact bypassed workflow, such as the target application or update destination.
Expected result:
* the request succeeds without an authentication prompt
* the application works normally
* logs show the traffic followed the bypass path
### Negative tests
Test ordinary browsing to a site that should still require authentication.
Expected result:
* SafeSquid still prompts or enforces authentication normally
* the bypass profile does not leak into unrelated traffic
## Troubleshooting guide
### Users or apps still receive an authentication prompt
Likely causes:
* the bypass profile is not linked into the active policy path
* the request-type does not actually match the application traffic
* the application uses additional domains that were not included
Isolation steps:
* inspect the active request-type and access-profile logic
* verify the live destination list in logs
* compare the app request against the configured host pattern
Remediation:
* fix the link between request type and bypass profile
* add the missing related domains
* narrow or correct the host pattern, then retest
### Too much traffic bypasses authentication
Likely causes:
* the hostname or Smart TLD pattern is too broad
* a shared domain is being matched for unrelated traffic
Isolation steps:
* review all destinations that now inherit the bypass
* compare them against the intended application flow
Remediation:
* narrow the pattern
* use more specific request characteristics
* retest both the app flow and normal browsing
## Related controls / next steps
* Use [Access Restriction](/use_cases/access_restriction/access_restriction) and [Request Profiles](/use_cases/profiling_engine/request_profiles) to keep bypass logic narrow and auditable.
* Use [Directory Services](/use_cases/authentication/directory_services) and [Authentication](/use_cases/authentication/authentication) for the normal attributed access path.
# SSO Authentication with RODC
Source: https://docs.safesquid.com/use_cases/authentication/configure_kerberos_authentication_with_rodc
Integrate Active Directory for SSO using Read-Only Domain Controllers (RODC). Includes RWDC preparation, lookup logic, and LDAP configuration.
# Set Up Active Directory SSO With RODC
## Problem: Kerberos SSO in RODC Environments
In distributed networks where Read-Only Domain Controllers (RODCs) are used, direct configuration of Kerberos identities is impossible due to the read-only nature of the database. Attempts to create computer objects or modify SPNs on an RODC will fail. Users at RODC-controlled sites often face 407 authentication prompts because the RODC is "blind" to the SafeSquid computer object until it is explicitly created on a Writable DC and replicated.
## Key benefits
* **Global Single Sign-On**: Authenticated users at RODC sites access the proxy without credential prompts.
* **Security Alignment**: Enforces AES-256 encryption across all sites.
* **Centralized Management**: Configure once on the Writable DC (RWDC) and replicate automatically to all RODC locations.
* **Zero Admin Overhead**: Automation script handles complex AD attribute mapping (UAC Flags, SPNs, Encryption Types).
## The Concept: Kerberos Lookup & the "Push"
To understand why the Main DC is vital, consider the Kerberos-RODC flow:
```mermaid theme={null}
sequenceDiagram
participant Client
participant RODC as Read-Only DC
participant RWDC as Writable DC
participant SafeSquid
Note over RWDC: Step 1: Create Object (Script)
RWDC->>RODC: Step 2: Push/Replicate Data
Client->>RODC: Request Ticket for SafeSquid
RODC->>RODC: Step 3: Local Lookup
RODC-->>Client: Issue Kerberos Ticket
Client->>SafeSquid: Authenticate
```
**Why it matters:** The RODC cannot issue a ticket unless it "knows" SafeSquid exists. Since it can't create the account itself, you must **Push** the "Source of Truth" from the **Main Writable DC**.
***
## Prerequisites
* Perform all operations on a **Writable Domain Controller** (RWDC).
* **Target the PDC Emulator**: To avoid "Referral" or "Unwilling to process" errors, we explicitly find and target the Primary DC.
```powershell theme={null}
# Run this first to identify your Writable DC
$TargetDC = (Get-ADDomainController -Discover -Service PrimaryDC).HostName | Select-Object -First 1
Write-Host "Operations will be performed on: $TargetDC" -ForegroundColor Cyan
```
***
## Configuration Breakdown
### Service Principal Names (SPNs)
Seven SPNs are required. The hostname used by `msktutil` must match the AD object's registration exactly.
| Attribute | Required Value / Placeholder |
| - | - |
| **Name** | `safesquid` |
| **SamAccountName** | `safesquid$` |
| **UPN** | `safesquid.@` |
| **UAC Bitmask** | `33624064` (Workstation + No Expiry + No Pre-Auth) |
| **Encryption Type** | `28` (AES 128/256 Support) |
***
## Placeholder Reference Table
Use this table to identify which values in the commands and scripts need to be replaced with your environment's specific details.
| Placeholder | Description | Example Value |
| :- | :- | :- |
| `` | The hostname of your SafeSquid ISO/Virtual Machine. | `safesquid-proxy-01` |
| `` | Your Active Directory domain name (FQDN). | `company.local` |
| `` | Your AD domain name in ALL CAPS. | `COMPANY.LOCAL` |
| `$ComputerName` | The name of the AD computer object. **Do not change this.** | `safesquid` |
| `` | The hostname of your Read-Only Domain Controller. | `rodc-01` |
| `` | The IP address of your Read-Only Domain Controller. | `192.168.1.10` |
***
## Service Principal Name (SPN) Reference Table
These seven SPNs must be registered on the SafeSquid computer object. Replace placeholders with your actual values.
| SPN Type | Service Principal Name Format | Description |
| :- | :- | :- |
| **ISO Host (FQDN)** | `HOST/.` | Kerberos identity for the ISO hostname. |
| **ISO HTTP (FQDN)** | `HTTP/.` | Used for web-based Kerberos authentication. |
| **ISO LDAP (FQDN)** | `LDAP/.` | Used for LDAP/AD communication. |
| **Common Host (FQDN)** | `HOST/safesquid.` | Kerberos identity for the common `safesquid` name. |
| **Common HTTP (FQDN)** | `HTTP/safesquid.` | Primary SPN for proxy authentication. |
| **Common LDAP (FQDN)** | `LDAP/safesquid.` | Used for searching AD via `safesquid` identity. |
| **Common Host (Short)** | `host/safesquid` | Short name (NetBIOS) SPN for legacy compatibility. |
***
## Setup Procedure
Choose the method that fits your administration style.
### Step 1: Initialize Identity
Replace `` with your environment values.
```powershell theme={null}
$TargetDC = (Get-ADDomainController -Discover -Service PrimaryDC).HostName | Select-Object -First 1
$ISO_Hostname = "" # e.g., 'safesquid-proxy-01'
$DomainName = "" # e.g., 'company.local'
$Realm = $DomainName.ToUpper() # e.g., 'COMPANY.LOCAL'
$ComputerName = "safesquid"
```
### Step 2: Create or Update Object
```powershell theme={null}
# Attempt to create the object on the writable DC
New-ADComputer -Name $ComputerName -Server $TargetDC `
-SamAccountName "$ComputerName$" `
-Path "CN=Computers,DC=$($DomainName.Replace('.', ',DC='))" `
-DNSHostName "$ComputerName.$DomainName" `
-UserPrincipalName "$ComputerName.$Realm@$Realm" `
-Enabled $true
# Update core attributes if object already exists
Set-ADComputer -Identity $ComputerName -Server $TargetDC `
-DNSHostName "$ComputerName.$DomainName" `
-UserPrincipalName "$ComputerName.$Realm@$Realm"
```
### Step 3: Register SPNs (Differential Update)
Only adds SPNs that are missing to avoid "Duplicate" errors.
```powershell theme={null}
$obj = Get-ADComputer -Identity $ComputerName -Server $TargetDC -Properties servicePrincipalName
# Define the mandatory SPN list
$Desired = @(
"HOST/$ISO_Hostname.$Realm", "HTTP/$ISO_Hostname.$Realm", "LDAP/$ISO_Hostname.$Realm",
"HOST/$ComputerName.$Realm", "HTTP/$ComputerName.$Realm", "LDAP/$ComputerName.$Realm",
"host/$ComputerName"
)
# Identify which ones aren't already there
$toAdd = $Desired | Where-Object { $_ -notin $obj.servicePrincipalName }
if ($toAdd) {
Set-ADComputer -Identity $obj.DistinguishedName -Server $TargetDC -Add @{ servicePrincipalName = $toAdd }
Write-Host "Added missing SPNs."
}
```
### Step 4: Security Flags (UAC & AES)
```powershell theme={null}
Set-ADObject -Identity $obj.DistinguishedName -Server $TargetDC `
-Replace @{
userAccountControl = 33624064
'msDS-SupportedEncryptionTypes' = 28
}
```
### Fully Generalized AD Script
Copy-paste this into a PowerShell (Admin) terminal on a Writable DC.
#### How to Run This Script
1. **Save the Script**: Copy the code below and save it as a file named `Replicate-ADComputer.ps1`.
2. **Location**: Save this file directly on your **Writable Domain Controller** (RWDC/PDC Emulator).
3. **Execute**: Open PowerShell as Administrator, navigate to the folder where you saved the script, and run it using this command:
```powershell theme={null}
.\Replicate-ADComputer.ps1
```
```powershell theme={null}
# =========================================================================
# SAFESQUID MASTER AD PREPARATION SCRIPT (GENERAL)
# =========================================================================
Import-Module ActiveDirectory
# --- 1. SET YOUR VARIABLES HERE ---
$ISO_Hostname = ""
$DomainName = ""
$ComputerName = "safesquid"
# --- 2. AUTOMATED LOGIC ---
$SAMAccount = "$ComputerName$"
$Realm = $DomainName.ToUpper()
$BaseDCPath = ($DomainName -split '\.' | ForEach-Object { "DC=$_" }) -join ','
$UPN = "$ComputerName.$Realm@$Realm"
$DNSHostName = "$ComputerName.$DomainName"
# Target the Writable PDC Emulator
$TargetDC = (Get-ADDomainController -Discover -Service PrimaryDC).HostName | Select-Object -First 1
Write-Host "Targeting DC: $TargetDC" -ForegroundColor Cyan
# SPNs (Matching msktutil requirements)
$DesiredSPNs = @(
"HOST/$ISO_Hostname.$Realm", "HTTP/$ISO_Hostname.$Realm", "LDAP/$ISO_Hostname.$Realm",
"HOST/$ComputerName.$Realm", "HTTP/$ComputerName.$Realm", "LDAP/$ComputerName.$Realm",
"host/$ComputerName"
)
# --- 3. EXECUTION ---
$Existing = Get-ADComputer -Filter "SamAccountName -eq '$SAMAccount'" -Server $TargetDC -Properties servicePrincipalName -ErrorAction SilentlyContinue
if ($Existing) {
Write-Host "Object found, updating attributes..." -ForegroundColor Yellow
Set-ADComputer -Identity $Existing.DistinguishedName -Server $TargetDC -DNSHostName $DNSHostName -UserPrincipalName $UPN
# Differential SPN update
$SPNsToAdd = $DesiredSPNs | Where-Object { $_ -notin $Existing.servicePrincipalName }
if ($SPNsToAdd) { Set-ADComputer -Identity $Existing.DistinguishedName -Server $TargetDC -Add @{ servicePrincipalName = $SPNsToAdd } }
} else {
Write-Host "Creating new computer object..." -ForegroundColor Cyan
New-ADComputer -Name $ComputerName -Server $TargetDC -Path "CN=Computers,$BaseDCPath" -DNSHostName $DNSHostName -UserPrincipalName $UPN -ServicePrincipalNames $DesiredSPNs -Enabled $true
}
# Apply Security Flags (UAC 33624064 + AES-256 Support)
$FinalObj = Get-ADComputer -Identity $ComputerName -Server $TargetDC
Set-ADObject -Identity $FinalObj.DistinguishedName -Server $TargetDC -Replace @{
userAccountControl = 33624064
'msDS-SupportedEncryptionTypes' = 28
}
Write-Host "`nSUCCESS: Active Directory is now configured for SafeSquid." -ForegroundColor Green
```
***
## Phase 2: Configure Password Replication Policy (PRP)
Since the RODC is read-only, you must allow it to cache the SafeSquid computer password.
1. Open **AD Users and Computers** > **Domain Controllers** OU.
2. Right-click your **RODC** Object > **Properties**.
3. Go to the **Password Replication Policy** tab.
4. Click **Add** and select the **safesquid** computer account.
5. Ensure it is set to **"Allowed"**.
***
## Phase 3: SafeSquid Interface Setup
Navigate to **Application Setup** > **Integrate LDAP** > **LDAP servers**.
![LDAP CONFIG IN SAFESQUID FOR RODC]()
| Parameter | Configuration Value |
| :- | :- |
| **Enabled** | `TRUE` |
| **Ldap FQDN\IP** | `` `\` `` |
| **Ldap Bind Method** | `NEGOTIATE_LDAP_AUTH` |
| **Ldap Username** | `` `administrator@` `` |
| **Ldap Basedn** | `` `dc=,dc=` `` |
| **Ldap Domain** | `` `` `` |
:::warning
Ensure the **Ldap Bind Method** is set to **NEGOTIATE\_LDAP\_AUTH**. This is the trigger that initiates Kerberos ticket exchange.
:::
***
## Troubleshooting
### Keytab Generation Fails
* **Symptom**: Logs show `kerberos: main: Generate Keytab: failed`.
* **Cause**: The RODC password replication policy hasn't synced the computer account yet.
* **Fix**: Manually initiate a sync on the RODC or wait 15 minutes.
### 407 Proxy Authentication Required
* **Cause**: Time drift between AD and SafeSquid.
* **Fix**: Verify time sync using the `date` command on both servers. They must be within 5 minutes of each other.
## Source register
| Topic | Status | Source |
| - | - | - |
| `NEGOTIATE_LDAP_AUTH` bind method | **Confirmed** | This page (required for Kerberos path) |
| RODC replication / keytab errors | **Confirmed** | Troubleshooting above |
| Time skew tolerance | **Draft** | **5 minutes** aligns with common Kerberos practice; **CTO** confirm against supported AD policy |
## Next steps
* [SSO Authentication](/use_cases/authentication/ad_sso_authentication) for standard RWDC paths.
* [NTP](/architecture/interface/ntp) for clock sync.
* [Authentication hub](/use_cases/authentication/authentication).
# Directory Services
Source: https://docs.safesquid.com/use_cases/authentication/directory_services
Integrate SafeSquid with Active Directory or OpenLDAP for centralized user authentication and group-based access control.
# Centralized Identity and Group-Based Policy
SafeSquid integrates with directory services to provide centralized user authentication and group-based access control. This ensures that web access policies are tied to enterprise identities and group memberships.
## Problem statement
IP-based proxy control is not enough for enterprise governance. Administrators need directory-backed user and group identity so policy, reporting, and investigations reflect the real actor behind the request.
## Supported Directory Services
| Directory Service | Integration Type | Key Features |
| - | - | - |
| [Active Directory](/use_cases/authentication/active_directory) | Kerberos SSO / LDAP | Seamless SSO for domain users, group sync |
| [OpenLDAP](/use_cases/authentication/openldap) | Simple LDAP | Centralized identity for Linux/Unix environments |
Confirmed directory-related product capabilities today:
* Active Directory
* LDAP
* Kerberos
Do not document these as current shipping directory capabilities:
* SAML
* RADIUS
## Why use Directory Services?
* **Centralized Management:** Manage users and groups in one place (AD/LDAP) instead of locally in SafeSquid.
* **Group-Based Policies:** Apply different access rules automatically based on directory group membership (e.g., Finance, IT, Sales).
* **Single Sign-On (SSO):** (Active Directory only) Authenticate users transparently using Kerberos tickets without browser prompts.
* **Granular Audit:** Access logs show exactly which directory user accessed which resource, simplifying compliance reporting.
## Operational requirements
* Reliable DNS and NTP are required for stable directory-backed authentication.
* Kerberos is the documented transparent path for Active Directory environments.
* If transparent authentication is not viable, use prompt-based authentication and keep the user-experience trade-off explicit.
## Choose your integration method
### [Active Directory (AD)](/use_cases/authentication/active_directory)
Best for Windows-centric environments. Supports **SSO Authentication** for the best user experience and **Simple Authentication** for non-domain devices or specific use cases.
### [OpenLDAP](/use_cases/authentication/openldap)
Best for Linux/Unix-heavy environments or organizations using OpenLDAP for identity. Supports **Simple Authentication** (LDAP bind) to validate credentials against the directory.
## Verification and validation
After integration, confirm:
* users and groups are visible in the SafeSquid directory view
* authentication succeeds with a known test account
* group-based policies differentiate users as expected
* logs and reports show directory-backed identity instead of anonymous IP-only attribution
## Source register
| Topic | Status | Source |
| - | - | - |
| AD: SSO + Simple paths | **Confirmed** | [Active Directory hub](/use_cases/authentication/active_directory) |
| OpenLDAP: Simple LDAP integration | **Confirmed** | [OpenLDAP hub](/use_cases/authentication/openldap) |
| Group-based policy linkage | **Confirmed** | [Access Restriction](/use_cases/access_restriction/access_restriction) |
## Next steps
1. Choose your directory service above.
2. Follow the **Setup Integration** guide to link SafeSquid with your directory.
3. Configure **Simple** or **SSO** authentication rules.
4. Combine with [Access Restriction](/use_cases/access_restriction/access_restriction) to enforce policies by directory group.
# Internal User Authentication
Source: https://docs.safesquid.com/use_cases/authentication/internal_users
Authenticate users by assigning usernames and passwords via the SafeSquid interface when no Active Directory is available.
# Set Up Internal User Authentication Without Active Directory
When no Active Directory (AD) server is available for SafeSquid LDAP, administrators can authenticate users by assigning usernames and passwords via the SafeSquid interface. This is done using the internal user database.
## Adding users using SafeSquid interface for authentication
![clicking on configure in SafeSquid interface]()
![click on search in access profiles]()
![User list in SafeSquid interface]()
![Add or edit user entry]()
![User policy form]()
![Save or submit user details]()
![User list with new entry]()
![Configuration applied successfully]()
## Source register
| Topic | Status | Source |
| - | - | - |
| Internal user database via UI | **Confirmed** | Procedure screenshots on this page |
| Parity with [BASIC](/use_cases/authentication/basic) / credential store | **Draft** | Treat as overlapping capability; align narrative with engineering if titles differ |
## Next steps
* [BASIC Authentication](/use_cases/authentication/basic) for RFC 7617 and local store detail.
* [Directory Services](/use_cases/authentication/directory_services) when AD/LDAP becomes available.
# Network Signature
Source: https://docs.safesquid.com/use_cases/authentication/network_signature
Network Signature reference and operational guidance for SafeSquid SWG administrators.
# Apply Policy by Network Signature
Maps client IP addresses or ranges to user-groups so access restriction rules and reporting apply by network segment. No user login required; policy is enforced by source IP or subnet. Use when user identity is unavailable (device-only access, legacy apps, shared kiosks).
SafeSquid evaluates Network Signature rules (Allow List) **top to bottom** and applies the **first matching rule**. Place specific IP rules above broader ranges to ensure correct policy application. See [Rule Order Matters](#troubleshooting) below for details.
## When to use Network Signature
| Use Network Signature When | Use User Authentication Instead |
| - | - |
| IoT devices, printers, shared kiosks | User workstations with logins |
| Legacy apps without proxy auth support | Modern apps with credential prompts |
| Policy by location/VLAN/segment | Policy by individual user |
| Device-level accountability acceptable | User-level attribution required (SOC 2, PCI DSS) |
* SafeSquid deployed and operational
* Admin access to [Configuration Portal](/architecture/overview/safesquid_swg)
* Known client IP addresses or subnets (static or predictable ranges)
Network Signature attributes traffic to IP/subnet and group, **not to a named user**. Where regulations require user-level attribution (e.g., PCI DSS, HIPAA), combine with user authentication or document the scope of IP-only policies for auditors.
## Configure IP-based user-groups
1. **Access SafeSquid Configuration** Open the [Configuration Portal](/architecture/overview/safesquid_swg) and click **Configure**.
2. **Navigate to Access Restrictions** **Application Setup** -> **Access Restrictions** -> **Allow List**
3. **Create New Policy** Click **Add New**.
4. **Define IP Range** Enter the IP address or range in the **IP Address** field. **Supported formats:** Single IP: `192.168.1.50` Multiple IPs: `192.168.1.50, 192.168.1.51, 192.168.1.52` IP range: `192.168.1.50-192.168.1.100` CIDR notation: `192.168.1.0/24`
5. **Assign User-Group** In **Add to User-Groups**, specify a unique group name (e.g., `FINANCE_DEVICES`, `GUEST_KIOSKS`, `IOT_SENSORS`).
6. **Save Policy** Click the checkmark to save.
Set **PAM Authentication** to **TRUE** or add **Username/Password** if you want that IP range to *also* require user login. This allows "IP range + user authentication" for specific segments.
## Configuration screenshots
![SafeSquid Configure page]()
![Access Restrictions section]()
![Allow List tab]()
![Add New button]()
![IP Address field]()
![User-Groups field]()
## Example: Segmented network policies
| Segment | IP Range | User-Group | Authentication | Policy Goal |
| - | - | - | - | - |
| Finance workstations | 192.168.10.0/24 | FINANCE | PAM required | User-level + department policy |
| Guest kiosks | 192.168.20.10-20 | GUEST\_KIOSKS | None | Restricted browsing, no login |
| IoT devices | 192.168.30.0/24 | IOT\_DEVICES | None | Update servers only |
| Executive floor | 192.168.5.0/24 | EXECUTIVES | AD/LDAP required | Premium access + audit |
## Verification
1. **Test from Client** Send traffic through the proxy from a client in the configured IP range. The client is assigned the configured user-group and matching access rules apply.
2. **Check Interface** **Access Restrictions** -> **Allow List** shows the rule with IP range and user-group
3. **Review Logs** `tail -f /var/log/safesquid/identity.log` Or **Reports** -> **Detailed Logs** Logs show client IP and assigned user-group
4. **Confirm Policy Application** Access a restricted site from the client; confirm the group-specific policy is enforced (allowed/blocked as configured)
## Troubleshooting
| Symptom | Likely Cause | Fix |
| - | - | - |
| Wrong policy applied | Client IP not in range or rule order issue | Verify client IP is within the configured range; check rule order in Allow List (more specific rules should be above broader ones) |
| No group assigned | IP mismatch or typo in range | Confirm IP field syntax; test from a known IP in the range |
| Unexpected auth prompt | Rule has PAM or credentials set | For IP-only policy (no user login), ensure PAM is set to FALSE and username/password fields are empty |
| Overlapping ranges | Multiple rules match same IP | Consolidate rules or use more specific ranges; SafeSquid uses first matching rule |
SafeSquid evaluates Allow List rules **top to bottom**. Place narrow, specific IP rules above broad ones:
1. 192.168.10.50 (single executive IP with premium access)
2. 192.168.10.0/24 (department subnet with standard access)
3. 0.0.0.0/0 (default policy for all others)
## Advanced: Dynamic IP assignment
For environments with DHCP where client IPs change:
1. **DHCP reservations:** Assign static IPs via DHCP for critical devices
2. **VLAN-based ranges:** Use predictable ranges per VLAN; map VLAN subnets to user-groups
3. **Combine with MAC-based DHCP:** Tie MAC addresses to IP reservations, then use Network Signature on those IPs
4. **Upgrade to user auth:** For dynamic endpoints (laptops, mobile), use [Directory Services](/use_cases/authentication/authentication) instead
## Next steps
* **Add user authentication:** Combine Network Signature with [Directory Services](/use_cases/authentication/authentication) or [BASIC](/use_cases/authentication/authentication) for user-aware policies
* **Refine access rules:** Use [Access Restriction](/use_cases/access_restriction/access_restriction) to define what each user-group can access
* **Enable SSL Inspection:** Configure [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) to inspect HTTPS traffic from IP-based groups
* **Report by group:** Use SafeSquid reports to analyze bandwidth and activity per user-group
# OpenLDAP
Source: https://docs.safesquid.com/use_cases/authentication/openldap
Integrate SafeSquid with OpenLDAP for centralized user authentication and group-based access control in Linux/Unix environments.
# OpenLDAP Integration
Integrate SafeSquid with OpenLDAP to enable centralized user identification and group-based access control for Linux/Unix-centric environments.
## Problem statement
Linux- and Unix-heavy environments still need attributable proxy identity and group-aware policy. Local proxy-only users do not scale well across centrally managed teams.
## Integration Workflow
| Step | Task | Goal |
| - | - | - |
| 1 | [Simple Authentication](/use_cases/authentication/openldap_simple_authentication) | Configure LDAP server connection and enable browser-prompt authentication. |
| 2 | [SSO Authentication](/use_cases/authentication/openldap_sso_authentication) | Follow the documented access flow on that page and confirm the exact scope before describing it as transparent SSO in your environment. |
## Why use OpenLDAP with SafeSquid?
* **Centralized Identity:** Use your existing OpenLDAP directory for proxy authentication.
* **Group-Based Access:** Categorize users into groups (e.g., `developers`, `marketing`) and apply different filtering rules.
* **Linux Compatibility:** Ideal for environments that don't use Active Directory but require identity-based security.
* **Audit Trails:** Identity logs attribute all web activity to specific LDAP usernames.
## Scope clarification
OpenLDAP is a confirmed directory integration path. Do not assume it provides the same Kerberos-style transparent SSO experience documented for Active Directory unless the target implementation proves that behavior in your environment.
## Verification
After configuring OpenLDAP:
1. **Fetch Entries:** Confirm that LDAP users and groups are listed in the **LDAP Entities** section of the SafeSquid interface.
2. **Log Check:** Verify successful LDAP binds in `/var/log/safesquid/native/safesquid.log`.
3. **Policy Test:** Ensure that a rule restricted to an LDAP group correctly allows members and blocks others.
## Troubleshooting
**Symptom:** LDAP users exist, but authentication fails.\
**Likely cause:** Bind settings, base DN, or server reachability are wrong.\
**Isolation:** Check the connection details and bind-related logs.\
**Remediation:** Correct the LDAP settings and retry.\
**Retest:** Authenticate with a known-good LDAP user.
**Symptom:** Group-based policy does not differentiate users.\
**Likely cause:** Group retrieval or mapping is incomplete.\
**Isolation:** Confirm LDAP groups are visible in the interface and compare the policy scope.\
**Remediation:** Correct the group mapping.\
**Retest:** Compare different LDAP users against the same protected target.
## Source register
| Topic | Status | Source |
| - | - | - |
| Simple LDAP bind flow | **Confirmed** | [Simple Authentication](/use_cases/authentication/openldap_simple_authentication) |
| OpenLDAP “SSO” wording | **Needs scope check** | Keep the wording bounded to the implementation page unless transparent SSO is proven in the target design |
## Next steps
* [Configure Simple Authentication](/use_cases/authentication/openldap_simple_authentication) to establish the connection.
* [Configure SSO Authentication](/use_cases/authentication/openldap_sso_authentication) to enable user-aware policies.
* [Access Restriction](/use_cases/access_restriction/access_restriction) to define what your LDAP groups can access.
# Simple Authentication
Source: https://docs.safesquid.com/use_cases/authentication/openldap_simple_authentication
Configure OpenLDAP simple bind authentication in SafeSquid for directory-backed user identification.
# OpenLDAP Simple Authentication
Simple authentication validates users against OpenLDAP using standard LDAP bind. Users are prompted by their browser to enter their directory credentials when accessing the proxy.
## Problem statement
OpenLDAP environments still need directory-backed user identity on the proxy path, especially where group-based policy or audit attribution is required.
:::note
**Prerequisites**
* SafeSquid installed and operational.
* OpenLDAP server reachable from the SafeSquid server (default port 389).
* Admin access to the SafeSquid [Configuration Portal](/architecture/interface/configuration_portal).
* A known-good bind account and correct Base DN.
:::
## Configure OpenLDAP Connection
1. **Access SafeSquid Interface:** Click **Configure** → **Application Setup** → **Integrate LDAP**.
2. **Enable Section:** Set the **Integrate LDAP** global section to **TRUE**.
3. **Add LDAP Server:**
* Go to **LDAP Servers** tab and click **Add New**.
* **LDAP Server IP:** Enter your OpenLDAP server IP.
* **Bind DN:** Enter the admin DN (e.g., `cn=admin,dc=safesquid,dc=net`).
* **Password:** Enter the bind password using the encryption arrow.
* **Base DN:** Enter your directory base (e.g., `dc=safesquid,dc=net`).
* **LDAP Domain:** Enter your domain name.
![entering LDAP server IP]()
4. **Save Configuration:** Click the checkmark to save.
## Operational notes
* This is the confirmed OpenLDAP-backed authentication path.
* Keep the user experience explicit: this method is browser-prompt based, not Kerberos-like transparent SSO.
* Verify group visibility before relying on group-based policy outcomes.
## Verification
| Step | Action | Expected Result |
| - | - | - |
| **Test User Extraction** | Go to **LDAP Entities** tab. | You should see all users and groups from your OpenLDAP server. |
| **Check Logs** | `tail -f /var/log/safesquid/native/safesquid.log` | Look for "LDAP bind successful" messages. |
| **Network Test** | `ldapsearch -h -D "" -W` | Successful response from the LDAP server confirms credentials and connectivity. |
## Troubleshooting
## Troubleshooting
| Symptom | Likely Cause | Fix |
| - | - | - |
| No LDAP entries fetched | Incorrect Base DN or Bind DN | Verify your DN syntax and confirm the directory structure with an LDAP browser or `ldapsearch`. |
| Connection refused | Firewall, port, or routing issue | Ensure the LDAP path is open between SafeSquid and the LDAP server. |
| Authentication fails | Password mismatch | Re-enter the password in SafeSquid and ensure it is stored correctly. |
| UI shows failure | Bind account permissions | Ensure the account used for Bind DN has read permissions for the required directory scope. |
## Source register
| Topic | Status | Source |
| - | - | - |
| OpenLDAP bind, **LDAP Entities** | **Confirmed** | This page |
| Port **389** | **Confirmed** | Troubleshooting (standard LDAP) |
## Next steps
* [Enable SSO Authentication](/use_cases/authentication/openldap_sso_authentication) to apply these identities to access rules.
* [Access Restriction](/use_cases/access_restriction/access_restriction) to define policies by LDAP group.
# SSO Authentication
Source: https://docs.safesquid.com/use_cases/authentication/openldap_sso_authentication
Enable transparent authentication for OpenLDAP users in SafeSquid using directory profiles and access restrictions.
# OpenLDAP SSO Authentication
Configure Access Restrictions to utilize OpenLDAP identities. This enables identity-based policies where users are recognized by their directory username and group membership.
## Scope note
This page documents the rule-wiring flow that applies OpenLDAP-backed identity in SafeSquid policy. Do not casually equate this page with the Kerberos-based transparent SSO model documented for Active Directory.
:::note
**Prerequisites**
* [OpenLDAP Simple Authentication](/use_cases/authentication/openldap_simple_authentication) configured and successful.
* LDAP users and groups must be visible in the **LDAP Entities** tab.
:::
## Enable Authentication in Access Rules
1. **Access Restrictions:** Go to **Application Setup** → **Access Restrictions** → **Allow List**.
2. **Edit Rule:** Edit the rule matching your client segment or create a new one.
3. **Apply LDAP Profiles:**
* **LDAP Profiles:** Select specific LDAP groups (e.g., `IT_Admins`) from the dropdown.
* Leave blank to apply this rule to all directory users.
4. **Enable PAM:** Ensure **PAM Authentication** is set to **TRUE**.
5. **Save Policy:** Click the checkmark to save.
## Operational notes
* Treat this as an identity-application path unless your target environment has separately proven a transparent user experience.
* Keep the terminology precise when describing the deployment to operators or customers.
![selecting the users or user groups you want to set the authentication for]()
:::tip
**Note on Default Rules**
SafeSquid includes default entries under the **Allow List**. You can edit these to quickly map specific LDAP groups to default user-groups like `admins` or `users`.
:::
## Verification
| Action | Method | Expected Result |
| - | - | - |
| **Test Access** | Browse from a client belonging to a mapped LDAP group. | Access is allowed/denied according to the rule. |
| **Check Identity Log** | `tail -f /var/log/safesquid/identity.log` | Shows the authenticated OpenLDAP username for each request. |
| **Review Dashboard** | **Reports** → **Detailed Logs** | Verify the **Username** column is populated with directory names. |
![Confirming SSO authentication by seeing the username in SafeSquid detailed logs]()
## Troubleshooting
| Symptom | Likely Cause | Fix |
| - | - | - |
| Authentication prompt appears | This flow does not provide the same transparent experience as AD Kerberos, or the rule path does not match | Verify what user experience your environment actually supports and check LDAP profile matching. |
| User recognized but blocked | Policy restriction | Check the access rules applied to the user-group assigned in the Allow List entry. |
| No username in logs | PAM set to FALSE or identity not applied on the matching rule | Ensure **PAM Authentication** is set to **TRUE** in the matching Allow List rule. |
## Source register
| Topic | Status | Source |
| - | - | - |
| OpenLDAP identity in Allow List + **PAM Authentication** | **Confirmed** | This page (scope: transparent identity via rule wiring documented here) |
| “SSO” naming vs Kerberos AD | **Draft** | OpenLDAP flow differs from AD Kerberos SSO; use exact feature names with customers |
## Next steps
* [Access Restriction](/use_cases/access_restriction/access_restriction) to define policies for your different LDAP groups.
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) to attribute encrypted traffic to specific users.
* [Bypass Authentication](/use_cases/authentication/bypass_authentication) for automated services.
# PAM Authentication
Source: https://docs.safesquid.com/use_cases/authentication/pam
Configure PAM (Pluggable Authentication Modules) integration with SafeSquid for system-level authentication.
# Set Up PAM Authentication
PAM integration validates proxy users against the system's Pluggable Authentication Modules (PAM) stack. This allows you to use a single set of credentials for both OS-level access (SSH, Login) and proxy access.
## When to use PAM Authentication
| Use PAM Authentication When | Use Directory Services Instead |
| - | - |
| SafeSquid is running on Linux/Unix | Primary identity is in Active Directory |
| You want to use local OS users | You need Single Sign-On (SSO) |
| System already uses PAM for LDAP/Radius | Best user experience for domain PCs |
:::note
**Prerequisites**
* SafeSquid running on a PAM-capable operating system (typically Linux).
* OS users and passwords already configured.
* Admin access to the SafeSquid [Configuration Portal](/architecture/interface/configuration_portal).
:::
## Enable PAM in Access Rules
1. **Access Configuration:** Open the [Configuration Portal](/architecture/interface/configuration_portal) and click **Configure**.
2. **Navigate to Allow List:** **Application Setup** → **Access Restrictions** → **Allow List**.
3. **Configure Rule:**
* Edit the entry that matches your client segment.
* **PAM Authentication:** Set to **TRUE**.
* **Username/Password:** Leave these empty (we are using OS PAM, not local SafeSquid credentials).
4. **Save and Apply:** Click the checkmark to save.
:::tip
**Note on Local Users**
If you create a user via `useradd` on the Linux host, SafeSquid will be able to authenticate them once PAM is set to TRUE.
:::
## Verification
| Action | Method | Expected Result |
| - | - | - |
| **Test Login** | Access a website from a client. | A browser login prompt appears; enter Linux OS credentials. |
| **Check Logs** | `tail -f /var/log/safesquid/identity.log` | Shows the OS username for each authenticated request. |
| **Verify Rule** | Check **Access Restrictions** → **Allow List**. | The rule shows **PAM Authentication** is **TRUE**. |
## Troubleshooting
| Symptom | Likely Cause | Fix |
| - | - | - |
| Authentication prompt does not appear | Rule mismatch | Ensure the rule matches the client IP and is placed high enough in the Allow List. |
| OS credentials rejected | PAM stack mismatch | Verify the system PAM configuration (e.g., `/etc/pam.d/safesquid`) if it exists, or ensure the global PAM service is working. |
| Login prompt repeats | Incorrect credentials | Verify the user exists on the Linux host and the password is correct. |
## Source register
| Topic | Status | Source |
| - | - | - |
| PAM stack delegation to OS | **Confirmed** | This page |
| Allow List **PAM Authentication** = TRUE | **Confirmed** | Verification table |
## Next steps
* [Local Credential Store (BASIC)](/use_cases/authentication/basic) for SafeSquid-only users.
* [Directory Services](/use_cases/authentication/directory_services) for enterprise identity integration.
* [Bypass Authentication](/use_cases/authentication/bypass_authentication) for services that cannot authenticate.
# Setup Active Directory Integration
Source: https://docs.safesquid.com/use_cases/authentication/setup_active_directory_integration
Link SafeSquid with Active Directory to synchronize users and groups for identity-based web security policies.
# Complete Active Directory Setup to Sync Users and Groups
Establish a connection between SafeSquid and Active Directory (AD) to synchronize user and group entities. This is the foundational step for both Simple and SSO authentication.
## Problem statement
If SafeSquid cannot reliably read AD users and groups, every later authentication flow becomes brittle. This setup step is where directory truth enters the proxy.
:::note
**Prerequisites**
* SafeSquid installed and operational.
* Windows Server with Active Directory installed and reachable from the SafeSquid server.
* [LDAP Admin](https://sourceforge.net/projects/ldapadmin/) installed (optional, used for verifying AD structure).
* A domain account with read permissions to the directory (Administrator or a dedicated service account).
* Working DNS and time synchronization between SafeSquid and the AD environment.
:::
## 1. Verify Active Directory structure
Before configuring SafeSquid, ensure your users and groups are organized in AD. Use **Active Directory Users and Computers** on your Windows Server.
![In tools section of AD server, going to active directory users and computers]()
:::tip
**Note the Base DN**
Your Base DN usually follows your domain name. Example: `safesquid.test` → `DC=safesquid,DC=test`.
:::
## 2. Link LDAP Admin with AD (Optional Verification)
Use LDAP Admin to test connectivity and find the correct DNs (Distinguished Names) for your configuration.
1. **New Connection:** Enter the AD Host IP and your credentials.
2. **Test Connection:** Click **Test connection** to verify connectivity before proceeding to SafeSquid.
3. **Fetch DNs:** If the tree is empty, right-click the connection → **Properties** → **Fetch DNs**.
![Entering the username and password in username password field]()
## 3. Integrate LDAP with SafeSquid
1. **Access SafeSquid Interface:** Open the [Configuration Portal](/architecture/interface/configuration_portal) and click **Configure**.
2. **Navigate to LDAP Integration:** **Application Setup** → **Integrate LDAP**. Click the **+** (Add new) icon.
3. **Configure Connection Details:**
* **LDAP Server FQDN / IP:** Enter your AD server details.
* **Bind DN:** Enter the service account username (e.g., `Administrator@safesquid.test`).
* **Password:** Click the arrow to enter and confirm the password.
* **Base DN:** Enter your directory base (e.g., `DC=safesquid,DC=test`).
* **LDAP Domain:** Enter your AD domain (e.g., `safesquid.test`).
![Filling the required fields as per the configuration]()
4. **Save Policy:** Click the checkmark to save.
## Operational notes
* Use a dedicated service account where possible instead of embedding broad administrative dependency in the long-term configuration.
* Record the Base DN, bind format, and LDAP domain values in deployment notes so later troubleshooting does not begin from guesswork.
* This step establishes the data plane for later simple-auth or Kerberos-based flows. But it does not by itself prove end-user authentication is working.
## Verification
| Step | Action | Expected Result |
| - | - | - |
| **Check Entities** | Go to **LDAP Entities** in the SafeSquid interface. | You should see a list of users and groups fetched from AD. |
| **Log Review** | Run `tail -f /var/log/safesquid/native/safesquid.log` | Look for "LDAP bind successful" or "fetched X entries" messages. |
| **Test Rule** | Create an access rule with an AD group in **LDAP Profiles**. | The rule should correctly identify members of that group. |
## Troubleshooting
## Troubleshooting
| Symptom | Likely Cause | Fix |
| - | - | - |
| No LDAP entries fetched | Incorrect Base DN or Bind DN | Verify DNs using LDAP Admin; ensure the bind format matches your AD environment. |
| Authentication failed | Wrong password or account locked | Re-enter the password in the encrypted password field; check AD for account lockouts. |
| Connection timeout | Network, firewall, DNS, or routing issue | Ensure the required LDAP path is reachable from SafeSquid to AD. |
| Empty LDAP Entities | Permissions issue | Ensure the bind account has read permissions for the target OUs or containers. |
## Source register
| Topic | Status | Source |
| - | - | - |
| LDAP bind, Base DN, LDAP Entities | **Confirmed** | This page |
| Ports **389** / **636** | **Confirmed** | Troubleshooting table (standard LDAP/LDAPS) |
## Next steps
* [Configure Simple Authentication](/use_cases/authentication/ad_simple_authentication) (Browser Prompt)
* [Configure SSO Authentication](/use_cases/authentication/ad_sso_authentication) (Kerberos/Transparent)
* [Access Restriction](/use_cases/access_restriction/access_restriction) (Apply policies by AD group)
# User Groups
Source: https://docs.safesquid.com/use_cases/authentication/user_groups
Configure user groups in SafeSquid for group-based web access policies, enabling differentiated security controls for departments, roles, and teams.
# User Identification
Source: https://docs.safesquid.com/use_cases/authentication/user_identities
Configure user identity recognition methods in SafeSquid including IP-based authentication, directory service integration, and credential management for policy enforcement.
# User identity drives policy and reporting
## User identity recognition methods
User identity drives policy enforcement, defines digital boundaries, and governs behavior. SafeSquid enables identity recognition through modular methods tailored to network architecture, trust design, and user mobility. Each method not only shapes access but also impacts the authentication experience.
### [IP-Based Recognition](/architecture/overview/safesquid_swg)
In static networks, identity begins with IP. SafeSquid maps static IP addresses to users or groups, validating identity by network origin. It requires no prompts, credentials, or interaction---identity is inferred and immediate. Ideal where user-device relationships remain constant.
### [OpenLDAP Integration](/use_cases/authentication/openldap)
As environments adopt directory services, OpenLDAP introduces structured identity. SafeSquid supports two authentication paths:
* **Kerberos SSO** System login provides identity. No user prompts. SafeSquid reads the Kerberos ticket from the session and authenticates silently. Suitable for managed, domain-aware environments.
* **Simple** Where SSO isn't feasible, SafeSquid prompts for credentials. User input is validated against OpenLDAP. Interaction is explicit, but effective for guest or unmanaged devices.
### [Active Directory Integration](/use_cases/authentication/active_directory)
For enterprise environments, Active Directory too offers seamless integration with:
* **Kerberos SSO**
* **Simple**
### Without Directory Services
Where directories are absent, SafeSquid provides internal mechanisms:
* [Credential-Based Authentication](/use_cases/authentication/basic) User accounts and encrypted credentials are stored locally. SafeSquid presents a login prompt, validates inputs internally, and applies identity-based policies. Entirely self-contained.
* **PAM Authentication** In Linux-based environments, SafeSquid leverages the Pluggable Authentication Module (PAM) framework for user identification. PAM enables SafeSquid to authenticate users through the host system's authentication stack, which may include system accounts, RADIUS, smartcards, biometric modules, or custom PAM configurations.
### [User Groups](/use_cases/authentication/user_groups)
Configure user groups for group-based web access policies. User groups enable differentiated security controls for departments, roles, and teams.
### Multifactor Authentication
For elevated security, SafeSquid combines identity sources. A typical flow begins with IP-based recognition---identifying the device---followed by a credential challenge through AD, OpenLDAP, PAM, or local store. Access is granted only when both factors align, ensuring dual-layer assurance without external token systems.
## Next steps
* **[SafeSquid SWG Overview](/architecture/overview/safesquid_swg)** - SafeSquid Secure Web Gateway overview — software-defined deployment, core architecture, enforcement components, intelligence feeds, browser security, and operational services.
* **[OpenLDAP](/use_cases/authentication/openldap)** - integrate SafeSquid with OpenLDAP for centralized user authentication and group-based access control in Linux/Unix environments.
* **[Active Directory](/use_cases/authentication/active_directory)** - integrate SafeSquid with Active Directory for seamless user authentication, SSO, and group-based access control.
# Allow Specific Page on Facebook
Source: https://docs.safesquid.com/use_cases/content_modifier/allowing_specific_page_on_facebook
Allow specific Facebook pages and block the rest in SafeSquid for controlled social media usage.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Allow one Facebook page and block the rest
Many organizations block Facebook but need to allow a specific page (e.g. company page). SafeSquid SWG can allow a particular page for selected groups (e.g. social media team), partial or read-only for others, and by time of day. In the example below, only the SafeSquid page is allowed; other pages show a block template.
## Prerequisites
HTTPS Inspection should be enabled in SafeSquid. If not enabled, refer to the document - [How to enable HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection).
## Steps
[Access the SafeSquid User Interface](/architecture/interface/configuration_portal)
![Select Configure section from safesquid user interface to allow only specific page of Facebook]()
![Select Request typr to allow only specific page of Facebook]()
![Add new policy to allow only specific page of Facebook]()
![Give appropriate comment to the newly added policy that allow only specific page of Facebook]()
![Select method of the newly added policy that allow only specific page of Facebook]()
![Enter hostname in newly added policy that allow only specific page of Facebook]()
![Give appropriate Request profile for adding new connection in policy that allow only specific page of Facebook]()
![Save newly added policy that allow only specific page of Facebook]()
![Add new policy that allow only specific page of Facebook]()
![Give appropriate comment for future use in policy that allow only specific page of Facebook]()
![Select method of policy that allow only specific page of Facebook]()
![Enter file portion in policy that allow only specific page of Facebook]()
![Enter hostname of webserver in policy that allow only specific page of Facebook]()
![Enter appropriate Request profile in policy that allow only specific page of Facebook]()
![Save policy that allow only specific page of Facebook]()
![Save policy that allow only specific page of Facebook]()
![Add new policy that allow only specific page of Facebook]()
![Give appropriate comment for future use in policy that allow only specific page of Facebook]()
![Select method of policy that allow only specific page of Facebook]()
![Enter hostname of requested webserver in policy that allow only specific page of Facebook]()
![Enter appropriate Request profile in policy that allow only specific page of Facebook]()
![Save policy that allow only specific page of Facebook]()
![Add new policy that allow only specific page of Facebook]()
![Give appropriate comment for future use in policy that allow only specific page of Facebook]()
![Select Request type in the policy that allow only specific page of Facebook]()
![Select Action block in the policy that allow only specific page of Facebook]()
![Give appropriate Added profiles to the policy that allow only specific page of Facebook]()
![Save configuration that allow only that allow only specific page of Facebook]()
![Click and add policy that allow only specific page of Facebook]()
![Comment out in the policy that allow only specific page of Facebook]()
![Select request type in the policy that allow only specific page of Facebook]()
![Select Action allow in the policy that allow only specific page of Facebook]()
![Give appropriate Added profiles to the policy that allow only specific page of Facebook]()
![Save policy that allow only that allow only specific page of Facebook]()
![Save configuration that allow only that allow only specific page of Facebook]()
## Next steps
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Block Advertisements And Banners
Source: https://docs.safesquid.com/use_cases/content_modifier/block_advertisements_and_banners
Block ads and banners in SafeSquid to improve load time, security, and bandwidth and reduce distractions.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Block Advertisements to Speed Up and Secure Browsing
## Ads create security risk, waste bandwidth, and hurt user experience
Ad networks can deliver malware, tracking, and unwanted scripts; ads also increase load time and bandwidth use. Blocking ads at the gateway reduces exposure to ad-based threats, improves performance, and supports acceptable-use policy. SafeSquid BLOCK ADVERTISEMENT policy replaces ad content with a configurable template so users see cleaner pages without client-side ad blockers.
## Key benefits
Reduces malware and tracking exposure from ad networks. Lowers bandwidth and CPU use. Cleaner pages with fewer distractions. Evidence for auditors: policy is visible in **Configure** → **Access Profiles** (or **Templates**). Access logs show traffic that matched the policy. **Limitation:** Some sites may break if they depend on specific ad endpoints; use bypass or allow rules for exceptions.
## Prerequisites
**SafeSquid-side:** HTTPS Inspection enabled so SafeSquid can inspect and modify HTTPS content. See [Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection) if not yet enabled. Admin access to the Configuration Portal.
**Client-side:** No change required; blocking is transparent.
## Enable BLOCK ADVERTISEMENT policy
1. Access the SafeSquid interface via the [Configuration Portal](/architecture/interface/configuration_portal) — web interface for policy and system settings. In the interface header, click **Configure** to open the configuration menu.
![Configuration Portal header with Configure menu highlighted]()
2. In **Access Profiles** (or **Templates**), use the search box to find the default policy; search for **BLOCK ADVERTISEMENT**.
![Search box in Access Profiles or Templates list]()
![Search for BLOCK ADVERTISEMENT default policy]()
3. Open the policy: click **Edit** on the BLOCK ADVERTISEMENT row to open the policy editor. Set **Enabled** to **TRUE**, then click **Save** (or the equivalent save control in the policy section) to save the policy.
![Edit button on the BLOCK ADVERTISEMENT policy row]()
![Enabled toggle set to TRUE in the policy form]()
![Save button to persist the policy changes]()
4. Alternatively, enable from **Templates** in custom settings: open the BLOCK ADVERTISEMENT template, set **Enabled** to **TRUE**, and save.
![Enable BLOCK ADVERTISEMENT from Templates in custom settings]()
![Set Enabled to True in template]()
![Save the template]()
## Verification and Evidence
* **Interface:** **Configure** → **Access Profiles** (or **Templates**) shows BLOCK ADVERTISEMENT with **Enabled** TRUE.
* **Traffic:** Open a site that normally shows ads (e.g. [https://www.youtube.com/](https://www.youtube.com/)); ads should be replaced by the SafeSquid template.
![Blocked ad replaced by SafeSquid template on YouTube]()
* **Audit:** Access logs and reports show traffic matching the policy; export reports from the [Reporting Module](/use_cases/audit_and_forensics/reporting_module) for evidence.
:::note
Administrators can replace the default template with a custom template.
:::
## Troubleshooting
| Symptom | Likely cause | Resolution | Verification |
| - | - | - | - |
| Ads still visible | HTTPS Inspection not enabled or policy not applied | Enable HTTPS Inspection; ensure BLOCK ADVERTISEMENT is enabled and profile applied to the connection | Reload page; confirm template replaces ads |
| Site broken or login fails | Site depends on blocked ad domain | Add bypass or allow rule for that domain or path | Retest site after rule change |
| Policy not in list | Default policies not loaded | Restore defaults or contact support for policy set | Search again in Access Profiles |
## Next steps
* [Block inappropriate images using Image Analyzer](/use_cases/data_leakage_prevention/block_inappropriate_images_by_using_image_analyzer) for visual content filtering.
* [Header Re-Write](/use_cases/header_rewrite/header_obfuscation) for header filtering and privacy.
* [Content Modifier](/use_cases/content_modifier/content_modifier) for custom regex-based content rewriting.
# Content Modifier
Source: https://docs.safesquid.com/use_cases/content_modifier/content_modifier
Configure SafeSquid's Content Modifier to dynamically alter HTML, headers, and data in real-time for security and custom web policies.
# Real-time content rewriting for security and policy
## Uninspected or unmodified content increases risk and compliance gaps
Web pages and responses can contain unwanted scripts, tracking, or sensitive data. Without in-transit modification, organizations cannot enforce branding, remove risky content (e.g. ActiveX, inline scripts), or normalize headers for downstream systems. Risk includes malware delivery, policy violations, and inconsistent handling of MIME types. SafeSquid Content Modifier applies regex-based rewrites to body, client headers, server headers, and POST data so policies apply in real time.
## Key benefits of Content Modifier
Content Modifier enables security and operational control: strip or replace ActiveX, JavaScript, and cookies by profile. Rewrite titles or inject inspection notices for audit; normalize Accept headers (e.g. request PNG/JPG instead of AVIF/WEBP). Supports compliance use cases where content must be altered before delivery (e.g. data masking, branding). **Limitation:** Regex errors or broad MIME matching can affect page layout or break applications. Test rules in a non-production profile first.
## Prerequisites
**Client-side:** No change required; modification is transparent to the client.
**SafeSquid-side:** SafeSquid deployed and operational; admin access to the configuration interface. [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) enabled if modifying HTTPS response body. [Access Restriction](/use_cases/access_restriction/access_restriction) and profiles configured so modifier policies can target the right connections.
## Enable and configure Content Modifier in SafeSquid
Access the SafeSquid interface via the [Configuration Portal](/architecture/interface/configuration_portal).
### Open the Configure page
![Navigate to Configure in the SafeSquid interface]()
### Open Real-time content security
![Open Real-time content security section]()
### Open the Content modifier section
![Open Content Modifier section in Real-time content security]()
## Global
### Enabled
Enable or Disable this section.
* **TRUE**: Enable content rewriting
* **FALSE**: Disable content rewriting
![Content Modifier global Enabled toggle and options]()
![Content Modifier global settings view]()
![Content Modifier global configuration]()
## Rewriting Policies
![Rewriting Policies list and add entry]()
![Rewriting policy entry configuration]()
![Content Modifier policy pattern and replace configuration]()
List of regular expression substitutions to apply to matching files.
### Enabled
Enable or Disable this Entry.
* **TRUE**: Enable this Entry
* **FALSE**: Disable this Entry
### Comment
For documentation and future references, explain the relevance of this entry with your policies.
That is, by reading the policies, a future user can understand the purpose of that entry.
### Profiles
Specify the Profiles applicable for this entry.
This entry will be applicable only if the connection has any one of the specified profiles.
Leave it Blank, to apply for all connections irrespective of any applied profile.
To avoid application to a connection that has a profile, use a negated profile (!profile).
### Mime type
Specify regular expressions matching the MIME types for which this entry is applicable.
According to their nature and format, MIME-type is a way of identifying files on the Internet.
It is highly advisable that you set this to some mime type; otherwise, all files will be checked.
**Example**: text/html, ^image/, ^application/, application/x-shockwave-flash.
### Pattern
A regular expression pattern matching the area of text inside the file, 'to modify'.
This may be trailed with a '/' followed by flag characters like in Perl to modify options used to compile the regular expression and must be if a '/' is used anywhere else in the regular expression.
### Replace
Speify the replacement text to use in place of the area of text matching the pattern mentioned in the above field.
It may contain back-references to strings captured using parenthesis in the pattern.
### Applies to
This option is to select what the rewrite entry applies to.
* **BODY**: Rewrite the body of the webpage or file
* **CLIENT**: Rewrite the client header, this happens before Middleman parses it so be careful not to remove any headers needed to handle the request properly
* **SERVER**: Rewrite the header from the remote web server, the same conditions from the client header apply
* **POST:** Rewrite POST/PUT data sent when submitting a form or uploading a file
## Example
### Rule#1
This rule modifies the title tag of webpages to indicate that SafeSquid inspected the webpage. This rule is to be applied to every connection. To ensure the title tag is modified the chunked response needs to be buffered. Regex (Regular Expression) pattern matching selects the title tag of webpages. Replace with the title tag Inspected by SafeSquid.
![Example rule: modify title tag to show inspected by SafeSquid]()
### Rule#2
We want to request PNG & JPG images instead of AVIF & WEBP from a remote server.
AVIF images and ignore by SafeSquid's image analyzer.
Regex (Regular Expression) pattern matching selects the header request sent from the client to SafeSquid.
Modify the header response and request for PNG & JPG images instead of AVIF & WEBP.
![Example: request PNG and JPG instead of AVIF and WEBP]()
![Content Modifier header rewrite result]()
## Verification and Evidence
* **Interface:** **Configure** → **Real-time content security** → **Content Modifier** shows **Enabled** and the list of rewriting policies. Confirm each entry has the intended **Profiles**, **Mime type**, **Pattern**, and **Replace** values.
* **Traffic:** Load a page or trigger a request that matches a rule. Confirm the response body or headers reflect the replacement (e.g. title contains "Inspected by SafeSquid", or Accept header requests image types as configured).
* **Logs:** SafeSquid access and content logs can indicate requests that matched modifier profiles. Use for audit when demonstrating that content was altered per policy.
## Troubleshooting
| Symptom | Likely cause | Resolution | Verification |
| - | - | - | - |
| Page broken or blank | Regex too broad or replace removed required markup | Narrow **Mime type** and **Pattern**; avoid replacing structural HTML | Reload page; confirm layout and functionality |
| Rule not applied | Profile or MIME mismatch; rule disabled | Ensure connection has a matching profile; set **Enabled** TRUE; check **Applies to** (BODY/CLIENT/SERVER/POST) | Trigger request that matches profile and MIME; inspect response |
| Header removal breaks site | CLIENT or SERVER rewrite removed required header | Avoid removing Host, Content-Length, or other required headers | Retest request; check browser or client for errors |
## Detailed reference and next steps
### [Rewriting Policies Reference](/use_cases/header_rewrite/rewriting_policies_reference)
Field-by-field reference for every policy parameter (Enabled, Profiles, Mime type, Pattern, Replace, Applies to) with practical examples — title tag injection, image format enforcement, and header rewriting.
### Related sections
* [Header Re-Write](/use_cases/header_rewrite/header_obfuscation) for filtering or modifying specific headers.
* [Cookie Inspection](/use_cases/cookie_inspection/cookie_inspection) for cookie filtering and policy.
* [Data Leakage Prevention](/use_cases/data_leakage_prevention/data_leakage_prevention) for DLP and compliance templates.
## Next steps
Use with [Access Restriction](/use_cases/access_restriction/access_restriction) profiles; enable [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) when modifying HTTPS response body.
# Facebook Read Only Mode
Source: https://docs.safesquid.com/use_cases/content_modifier/facebook_read_only_mode
Put Facebook in read-only mode via SafeSquid so users can view but not comment or share.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Allow Facebook viewing but block posting and engagement
Organizations often want to allow Facebook for morale or recruitment but limit risk (cyberbullying, inappropriate posts). SafeSquid can put Facebook into read-only mode: users can view content but not comment, like, or share. Access can be full for social media groups, read-only for others, and time-based (e.g. relaxed at lunch).
## Facebook read-only mode
**Understand the possibilities**
1. Restricted Like, comment and share.
2. Blocking selective Facebook apps.
3. Allow Facebook login only to specific user or group of users.
4. Block Facebook chat.
## Prerequisites
HTTPS Inspection should be enabled in SafeSquid. If not enabled, refer to the document - [How to enable HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection).
## [Access the SafeSquid User Interface](/architecture/interface/configuration_portal)
![Access safesquid user interface to enable Facebook read only mode]()
![Search 'FACEBOOK READ ONLY MODE' in search section]()
## Search policy: "FACEBOOK READ ONLY MODE" to Search
![Search 'FACEBOOK READ ONLY MODE' in access profiles under restriction policies]()
## Edit policies and profiles to Enable as TRUE
![Enables 'FACEBOOK READ ONLY MODE' as true to make Facebook read only mode]()
![Click enabled 'FACEBOOK READ ONLY MODE' policy as true to make Facebook read only mode]()
![Save 'FACEBOOK READ ONLY MODE' policy as true to make Facebook read only mode]()
## Access FACEBOOK to verify
![Access Facebook to verify Facebook read only mode policy]()
![Test result of Facebook read only mode policy]()
![Test result of Facebook read only mode policy]()
![Test result of Facebook read only mode policy]()
![Test result of Facebook read only mode policy]()
## Next steps
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Cookie Filter Configuration and Reference
Source: https://docs.safesquid.com/use_cases/cookie_inspection/cookie_filter_configuration
Configure and reference SafeSquid cookie filter: Global, Allow, and Deny rules, expiry and profile options, and solution verification.
# Review Cookie Filter Configuration Options
Cookie filtering changes application behavior at the session layer. Treat it as a control that can intentionally break login persistence, not as a cosmetic privacy toggle.
## [Access SafeSquid interface](/architecture/interface/configuration_portal)
## Go to configure page
![Configure page with Cookie Filter in sidebar]()
## Global
### Enabled
Enable or Disable the cookie filtering section.
* **TRUE:** Enable cookie filtering section
* **FALSE:** Disable the cookie filtering section
![Cookie Filter Global section with Enabled and Policy options]()
### Policy
Select the default action to take, when no matching entry for a requested cookie is found.
* **ALLOW:** When Policy is set to Allow, a requested cookie is allowed, when no matching entry is found
* **DENY:** When Policy is set to Deny, a requested cookie is denied, if no matching entry is found
Choose the global policy carefully:
* `ALLOW` with narrow deny rules is safer when business applications depend heavily on cookies.
* `DENY` with narrow allow rules is stricter but riskier if you have not mapped required session-cookie behavior.
## Allow
![Cookie Filter Allow sub-section]()
When the Policy is Deny, rules defined under this sub-section, are exclusively allowed access.
Add a new allow entry to explicitly permit cookie transfer for all or a specific set of conditions. This defines cookie transfer whitelists.
### Enabled
Enable or Disable this entry
**TRUE:** Enable this entry.
**FALSE:** Disable this entry.
### Comment
For documentation and future references, explain the relevance of this entry to the deployment policies.
### Profiles
Specify the Profiles applicable for this entry.
This entry will be applicable only if the connection has any one of the specified profiles.
Leave it Blank, to apply for all connections irrespective of any applied profile.
To avoid application to a connection that has a profile, use a negated profile (! profile).
### Expiry year range
Mention the cookie expiry year range this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** 2016-2017, here cookie will expire after the year 2017.
### Expiry month range
Select the cookie expiry month range this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** January -- March, here cookie expires after March.
### Expiry day range
The cookie expiry day range this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** 1-20, here cookie will expire after the 20th day.
### Expiry weekday range
The cookie expiry weekday ranges this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** Monday -- Friday, here cookie will expire after Friday.
### Expiry hour range
The cookie expiry hour ranges this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** 1-10, Here cookie will expire after 10 AM.
### Expiry minute range
The cookie expiry minute range this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** 15-30, Here cookie will expire after 10:30 AM.
In the above example, Hours are included in the Hour range.
### Domain
Here you can mention the domain (website) names by separating with pipe (|) which you want to allow or deny. You can use regular expressions to match the domains.
**Example:** safesquid.com|google.com.
### Path
A regular expression matching the cookie's path attribute.
### Direction
The direction of the cookie this entry applies to. Can be either in (Set-cookie sent by website), out (Cookie sent by browser), or both.
* **IN:** For Inbound Connections only. That is only for the cookies sent by the hosts(websites).
* **OUT:** For Outbound Connections only. That is only for the cookies sent by the browser.
* **BOTH:** For Both Inbound and Outbound connections. For cookies sent by the websites as well as cookies sent by the browser.
### Time match mode
Select the appropriate mode to match the multiple time ranges.
**ABSOLUTETIME:**
When the absolute time match mode is used, any time between the starting and ending time will be matched.
Example: The weekday range specified is Monday to Friday and the Hour Range is 9 to 17.
The Absolute match mode will match any time starting Monday, 9 AM and ending Friday, 17 PM.
So, it will be active from Monday 9 AM to Friday 5 PM.
**ALLRANGES:**
With all ranges time match mode, however, a time within all of the ranges will match.
Example: The weekday range specified is Monday to Friday and the Hour Range is 9 to 17.
All ranges will match any time between 9 AM to 17 PM, on all weekdays from Monday to Friday.
So, it will be active every day from Monday to Friday between 9 AM to 5 PM.
### Example
#### Rule#1
This rule allows cookie filtering for connections with the profile "COOKIE ALLOW". Users who require access to log-in webpages and personal accounts need cookie access. Use the cookie -> Allow subsection to allow cookies.
![Allow rule for COOKIE ALLOW profile]()
#### Rule#2
This rule allows cookies for domain safesquid.com Despite the deny rule, connections to domain safesquid.com will not drop cookies This can be used in a situation where login is required for mission-critical applications.
![Allow cookies for domain safesquid.com rule]()
## Deny
When the Policy is Allow, rules defined under this sub-section, are exclusively denied access.
Here, you can add rules under Deny that would explicitly result in blocking or denial of cookie transfer to all or a specific set of conditions.
This effectively allows you to set a variety of intelligently and creatively defined Cookie Transfer Blacklist(s).
![Cookie Filter Deny sub-section with rule list]()
### Enabled
Enable or Disable this entry
* **TRUE:** Enable this entry
* **FALSE:** Disable this entry
### Comment
For documentation and future references, explain the relevance of this entry to the deployment policies.
### Profiles
Specify the Profiles applicable for this entry.
This entry will be applicable only if the connection has any one of the specified profiles.
Leave it Blank, to apply for all connections irrespective of any applied profile.
To avoid application to a connection that has a profile, use a negated profile (! profile).
### Expiry year range
Mention the cookie expiry year range this entry applies to
The cookie from a particular host (website), will be expired after this range.
**Example:** 2016-2017, here cookie will expire after the year 2017.
### Expiry month range
Select the cookie expiry month range this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** January -- March, here cookie expires after March.
### Expiry day range
The cookie expiry day range this entry applies to.
The cookie from a particular host (website), will be expired after this range.
Example: 1-20, here cookie will expire after the 20th day.
### Expiry weekday range
The cookie expiry weekday ranges this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** Monday -- Friday, here cookie will expire after Friday.
### Expiry hour range
The cookie expiry hour ranges this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** 1-10, Here cookie will expire after 10 AM.
### Expiry minute range
The cookie expiry minute range this entry applies to.
The cookie from a particular host (website), will be expired after this range.
**Example:** 15-30, Here cookie will expire after 10:30 AM.
In the above example, Hours are included in the Hour range.
### Domain
Here you can mention the domain(website) names by separating with pipe (|) which you want to allow or deny. You can use regular expressions to match the domains.
**Example:** safesquid.com|google.com
### Path
A regular expression matching the cookie's path attribute.
### Direction
The direction of the cookie this entry applies to. Can be either in (Set-cookie sent by website), out (Cookie sent by browser), or both.
* **IN:** For Inbound Connections only. That is only for the cookies sent by the hosts(websites).
* **OUT:** For Outbound Connections only. That is only for the cookies sent by the browser.
* **BOTH:** For Both Inbound and Outbound connections. For cookies sent by the websites as well as cookies sent by the browser.
### Time match mode
Select the appropriate mode to match the multiple time ranges.
**ABSOLUTETIME:**
When the absolute time match mode is used, any time between the starting and ending time will be matched.
Example: The weekday range specified is Monday to Friday and the Hour Range is 9 to 17.
The Absolute match mode will match any time starting Monday, 9 AM and ending Friday, 5 PM.
So, it will be active from Monday 9 AM to Friday 5 PM.
**ALLRANGES:**
With all ranges time match mode, however, a time within all of the ranges will match.
Example: The weekday range specified is Monday to Friday and the Hour Range is 9 to 17.
All ranges will match any time between 9 AM to 17 PM, on all weekdays from Monday to Friday.
So, it will be active every day from Monday to Friday between 9 AM to 5 PM.
### Example
#### Rule#1
The default rule for dropping cookies is used by SafeSquid.
Connections with the profile "READ ONLY" will ensure users are unable to log in.
Cookies sent in both directions are dropped.
![DROP COOKIES rule with READ ONLY profile]()
#### Rule#2
Connections with the profile "DROP COOKIES FOR GOOGLE" will drop all cookies for the domain google.com.
Cookies will be dropped for both incoming and outgoing requests.
![DROP COOKIES FOR GOOGLE rule for domain google.com]()
## Verification and Evidence
* **Interface Checks**: In [Configuration Portal](/architecture/interface/configuration_portal), Restriction Profiles → Cookie Filter: Global and policy entries match intent (Allow/Deny, profiles). Test URLs or domains show correct category in Categorize Web-sites if used.
* **Log Analysis**: Access logs reflect cookie allow/deny per policy; blocked cookie exchange may show in response or request logs.
* **Performance Validation**: Browsing with Allow profile allows login and cookies. With Deny or Drop profile, target sites do not receive or retain cookies as configured.
**Related**: [Access Restriction](/use_cases/access_restriction/access_restriction), [Header Obfuscation](/use_cases/header_rewrite/header_obfuscation), [Configuration Portal](/architecture/interface/configuration_portal), [Troubleshooting](/troubleshooting/troubleshooting)
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
* **[Access Restriction](/use_cases/access_restriction/access_restriction)** - build SafeSquid access policies that make web decisions by identity, destination, time, application, and content so enforcement stays precise and auditable.
* **[Header Re-Write](/use_cases/header_rewrite/header_obfuscation)** - configure SafeSquid header filter to allow, deny, or insert HTTP headers for client-server communication control.
# Cookie Inspection
Source: https://docs.safesquid.com/use_cases/cookie_inspection/cookie_inspection
Configure SafeSquid cookie filter to manage, allow, or block cookies for user privacy and policy enforcement.
## Problem
Websites set cookies for sessions, tracking, and advertising. Unrestricted cookies enable silent logins to personal mail and shopping sites, expand tracking surface, and complicate compliance. Administrators need host-scoped allow and deny rules aligned with acceptable-use policy.
## Benefits
The Cookie Filter lets administrators choose which hosts (websites) may send and receive cookies. Administrators control cookie exchange between remote websites and browsers, support privacy goals, and block login flows to selected destinations while keeping search or read-only access where configured.
## Advantages
**Confirmed:** Cookie filter integrates with SafeSquid profiles and the same Real-time content security workflow as [Header Re-Write](/use_cases/header_rewrite/header_obfuscation) and [Access Restriction](/use_cases/access_restriction/access_restriction).
## Call to action
Open the Configuration Portal path documented in [Cookie Filter Configuration and Reference](/use_cases/cookie_inspection/cookie_filter_configuration). Define Global policy and Allow/Deny rules (profiles, domain, path, direction, time). Test with a controlled client and verify expected login block or allow behavior.
## Verification and validation
After configuring cookie inspection, test both:
* a destination that should still receive or send cookies
* a destination that should fail or lose login persistence because cookie transfer is blocked
Use a controlled client and compare browser behavior before and after the rule change.
## Troubleshooting
**Symptom:** Users can still log in to a site that should be cookie-restricted.\
**Likely cause:** The domain, path, direction, or profile match is too broad or wrong.\
**Isolation:** Compare the request against the configured cookie rule scope.\
**Remediation:** Narrow or correct the rule.\
**Retest:** Repeat the same login flow and confirm cookie-dependent behavior changes.
**Symptom:** A business-critical site unexpectedly breaks.\
**Likely cause:** Cookie filtering is denying a required session cookie.\
**Isolation:** Test the site against the allow and deny policy with developer tools or controlled browser behavior.\
**Remediation:** Add a narrowly scoped allow entry for the required host or path.\
**Retest:** Confirm the site works without weakening unrelated cookie restrictions.
## Cookie filter controls which hosts can send and receive cookies
An HTTP cookie is a small piece of data sent from a website and stored in the browser while the user browses.
**Example:** Block cookies from advertising sites such as tribalfusion.com and doubleclick.net to prevent private information from being transferred. Users can query search engines (Google, Yahoo) but cannot log into personal accounts (Gmail, shopping, trading sites).
## Cookie filter configuration guides
### [Cookie Filter Configuration and Reference](/use_cases/cookie_inspection/cookie_filter_configuration)
Cookie allow/deny behavior requires correct Global policy and Allow/Deny rules. The document covers the Configuration Portal path, Global and Policy options, and Allow/Deny rule parameters (profiles, expiry, domain, path, direction, time match). Example rules and solution verification support validation. Use the document to configure and validate cookie filtering.
## Next steps
Combine with [Header Obfuscation](/use_cases/header_rewrite/header_obfuscation) and [Access Restriction](/use_cases/access_restriction/access_restriction) for full request/response and privacy control.
# Configuration Sync
Source: https://docs.safesquid.com/use_cases/customisation/configuration_sync
Discover how to enable configuration synchronization across a SafeSquid proxy cluster to ensure consistent policy deployment, reduce administrative overhead, and improve system reliability and security.
# Keep all proxy nodes in sync with master configuration
Without configuration synchronization, each proxy node must be updated manually. Inconsistencies cause policy gaps, vulnerabilities, and extra maintenance. SafeSquid configuration sync propagates policy and settings from the master to slave nodes so all nodes stay uniform and administrative overhead is reduced.
## What gets synced
**Synchronized from master to slaves:**
* Access policies (Access restrictions, Content Security, etc.)
* User groups and identity rules
* SSL Inspection settings
* Application signatures and web categories
* Extended policies (DLP, Anti-Virus, etc.)
**NOT synchronized (local to each node):**
* Network interface settings (IP, ports)
* System logs (each node logs independently)
* Performance counters
* Startup parameters (including master IP/port on slave)
## How sync works
* **Trigger**: Sync occurs automatically when you make configuration changes on the master and apply them
* **Frequency**: Near real-time (within \~1-5 minutes after applying changes on master)
* **Mechanism**: Slaves poll master at regular intervals for configuration updates
* **Restart required**: Some changes (e.g., startup params, network settings) require slave restart to apply
## Prerequisites
* Master and slave instances already connected (see [Master-Slave setup](/use_cases/scaling_and_high_availability/master_slave))
* If authentication is enabled on master, slave IP must be in Access restrictions → Allow list
**Important**: If proxy authentication is required for all network traffic, create an allow-list policy on the master for the slave proxy IP. Otherwise the slave cannot reach the master Configuration Portal to sync policies.
Below is an example of creating a user group for the slave proxy instance:
![A screenshot of a computer]()
## Configure sync on slave server
Perform these steps on each slave server to enable configuration sync from the master.
## Access the web interface and go to Support
![accessing safesquid web interface and going to support]()
## Select Startup params
![selecting startup params option]()
## Click on the edit button.
![clicking on edit button]()
## Add the master proxy server IP address
![Adding the master proxy server IP address]()
## Add the master proxy server port number
![Adding the master proxy server port number]()
## Now click on the correct icon to save the configuration.
![clicking on the correct icon to save the configuration]()
## Now click on restart for applying changes.
![clicking on restart for applying changes]()
Click **Yes** to back up SafeSquid configuration to the cloud, or **No** to skip cloud backup.
Click **Submit** after selecting the appropriate option.
![clicking on submit after selecting yes or no for backup configuration]()
After restart, the slave begins syncing configuration from the master. Policy changes made on the master will propagate to this slave automatically.
## Verify sync is working
1. Make a test policy change on the master (e.g., add a test user group)
2. Apply the change: Configuration Portal → Support → Restart SafeSquid (on master)
3. Wait 1-5 minutes
4. Open Configuration Portal on the slave
5. Verify the test policy appears on the slave
**Expected result**: Changes made on master appear on slave within a few minutes without manual intervention.
## Troubleshooting
**Policies not syncing to slave:**
* Verify slave Startup params show correct master IP and port: Configuration Portal → Support → Startup params
* Check network connectivity from slave to master's configured LISTEN\_PORT (8080 in verified screenshots; confirm the actual value on the master): `telnet `
* If authentication enabled, verify slave IP in master Access restrictions → Allow list
* Restart slave: Configuration Portal → Support → Restart SafeSquid
**Sync is slow (>10 minutes):**
* Check network latency between master and slave: `ping `
* Verify master is not overloaded (CPU/memory usage)
* Check slave logs for sync errors: `tail -f /var/log/safesquid/extended/extended.log`
**Changes sync but don't apply:**
* Restart slave to apply configuration changes: Configuration Portal → Support → Restart SafeSquid
* Some changes (network settings, startup params) require manual restart
**Related**: [Master-Slave setup](/use_cases/scaling_and_high_availability/master_slave), [Configuration Portal](/architecture/interface/configuration_portal), [Troubleshooting](/troubleshooting/troubleshooting)
## Next steps
* **[Master-Slave](/use_cases/scaling_and_high_availability/master_slave)** - configure SafeSquid master-slave architecture for centralized policy sync and reporting across slave instances.
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
* **[Troubleshooting](/troubleshooting/troubleshooting)** - comprehensive diagnostic procedures and resolution guides for common SafeSquid proxy issues, connection failures, and configuration problems.
# Configure Cloud Restore
Source: https://docs.safesquid.com/use_cases/customisation/configure_cloud_restore
Required setup, how Cloud Restore works, and step-by-step configuration to restore SafeSquid configuration and SSL certificates from the cloud.
# Complete Cloud Restore Setup for SafeSquid
Cloud Restore links backup and restore behavior to the SafeSquid activation key. It is useful for replacing or rebuilding appliances, but it does not restore the full operating environment.
## How Cloud Restore works
**Backup process:**
1. You make configuration changes in SafeSquid Configuration Portal
2. Click **Support → Restart SafeSquid** and select **Yes** for cloud backup
3. SafeSquid uploads `config.xml` and SSL certificates to cloud storage (linked to your activation key)
**Restore process:**
1. Install SafeSquid on new or rebuilt appliance
2. Activate with the same activation key used for backup
3. Click **Cloud Restore** in Configuration Portal
4. SafeSquid downloads and applies the backed-up configuration and SSL certificates
5. Restart SafeSquid to apply restored settings
**Files restored:**
* `/usr/local/safesquid/security/policies/config.xml` (all policies and settings)
* `/usr/local/safesquid/security/ssl/ROOT_X509File.cer` (SSL root certificate)
* `/usr/local/safesquid/security/ssl/ROOT_PrivateKeyFile.pem` (SSL private key)
The restore prompt appears only when SafeSquid finds a cloud backup matching your activation key.
## Prerequisites
* SafeSquid installed and activated with the same activation key on both backup and restore appliances
* Internet connectivity to SafeSquid cloud storage
* Monit service running (required for automatic service restart after restore)
* A recovery runbook for settings Cloud Restore does **not** restore, such as network configuration and third-party integration secrets
**Check Monit status:**
```bash theme={null}
systemctl status monit
```
If Monit is not running:
```bash theme={null}
systemctl start monit
systemctl enable monit
```
## Configure Cloud Restore
## [Access the SafeSquid User Interface](/architecture/interface/configuration_portal)
![Access the SafeSquid User Interface to configure cloud restore]()
![verify same Activation key before configure cloud restore]()
![Select configure cloud restore option]()
![Click on restore to configure cloud restore]()
![Confirmation of configure cloud restore]()
After restore completes, SafeSquid restarts automatically. Wait 1-2 minutes for the service to fully start.
## Verify restoration
1. Open the Configuration Portal.
2. Navigate to **Configure → Application Setup → Access restrictions** (or any configured section).
3. Confirm policies match the state from your original appliance.
4. Check the SSL certificate: there is no distinct "SSL Inspection" section in the console
(confirmed live, 2026-08-28, build `2026.0627.1344.3`) — HTTPS-inspection policy lives as
individual rule entries inside **Configure → Restriction Policies → Access Profiles** (for
example a `BYPASS SSL INSPECTION` Added Profile value). Confirm those entries match the
original appliance, and separately confirm the certificate details match the original CA by
inspecting the certificate in a client's browser.
5. Test client connection to verify proxy functionality.
**Expected result**: All policies, user groups, and SSL certificates should match the backed-up configuration.
Also verify the non-restored items separately:
* interface IP and routing
* DNS and NTP behavior
* directory integration secrets or external connector settings
* traffic flow through the rebuilt appliance
## Trigger manual backup before major changes
Before making risky configuration changes, trigger a manual backup:
1. Configuration Portal → Support → Restart SafeSquid
2. Select **Yes** when prompted "Backup current configuration to cloud?"
3. Click **Submit**
This creates a restore point you can revert to if changes cause issues.
## Troubleshooting
**"No cloud backup found" error:**
* Verify you're using the same activation key that was used for backup
* Check internet connectivity: `ping cloud.safesquid.com` (or SafeSquid cloud endpoint)
* Ensure a backup was actually created (restart with "Yes" for cloud backup on original appliance)
**Restore completes but policies missing:**
* Verify you restarted SafeSquid after restore: Configuration Portal → Support → Restart SafeSquid
* Check file permissions: `ls -l /usr/local/safesquid/security/policies/config.xml` (should be owned by safesquid user)
* Check logs: `tail -f /var/log/safesquid/extended/extended.log` (look for restore errors)
**SSL certificates not working after restore:**
* Verify certificate files exist:
```bash theme={null}
ls -l /usr/local/safesquid/security/ssl/ROOT_X509File.cer
ls -l /usr/local/safesquid/security/ssl/ROOT_PrivateKeyFile.pem
```
* Reimport SSL certificate to client browsers if needed: [Import Certificate](/use_cases/ssl_inspection/import_certificate_chrome_ie)
**Monit not restarting SafeSquid automatically:**
* Check Monit status: `systemctl status monit`
* Verify Monit configuration includes SafeSquid: `monit status`
* Manually restart if needed: `systemctl restart safesquid`
**Related**: [Disaster Recovery overview](/use_cases/scaling_and_high_availability/disaster_recovery), [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering), [Troubleshooting](/troubleshooting/troubleshooting)
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
* **[Import Certificate into Chrome or Internet Explorer](/use_cases/ssl_inspection/import_certificate_chrome_ie)** - step-by-step import of SafeSquid SSL certificate into Chrome or Internet Explorer for HTTPS inspection trust.
* **[Backup Strategy](/use_cases/scaling_and_high_availability/disaster_recovery)** - decide what SafeSquid backs up, what it does not, and what the disaster-recovery plan must cover separately before the deployment depends on Cloud Restore.
# Custom Templates
Source: https://docs.safesquid.com/use_cases/customisation/custom_templates
Create custom templates in SafeSquid for error pages, branding, and blocked-content replacement using HTML, images, or executables.
# Replace blocked or error pages with custom content
SafeSquid uses templates to replace pages that cannot be displayed (filtering, error, or other conditions). Custom templates support non-English messages, company logos, and contact text (e.g. "If this site was blocked in error, contact [helpdesk@mycompany.com](mailto:helpdesk@mycompany.com)"). Templates can be HTML, images, audio, or executables. Built-in examples include tinygif, checkeredgif, and tinyswf; checkeredgif is the default replacement for images blocked by the pornographic image filter.
## Prerequisites
Create your own html file and place that file in the below paths
for windows version of SafeSquid:
**c:ProgramDatausrlocalsafesquidui\_roottemplates**
The path for Linux version of SafeSquid is:
**/usr/local/safesquid/ui\_root/templates/**
**Note**: If you want to use any images in the html file make sure that the image also exist in the same path.
## Example:
Here i am creating below html page:
![Create Custom Templates or template list in SafeSquid interface]()
I Am saving this file with name:
**Custom\_template.html**
I will use this file in the below configuration
## [Access the SafeSquid user interface](/architecture/interface/configuration_portal)
### Go to Configure Page
![Clicking on configure in SafeSquid interface]()
### Go to Custom Settings
![Clicking to custom settings]()
### Go to Templates
![Clicking on templates]()
### Clone existing entry
![Cloning the existing entry by clicking on clone]()
### Edit the original entry
![Clicking on edit to edit the policies]()
You must edit the original entry, because the entries in template section are processed from top to bottom
![Editing the comment as per your entry]()
![In profiles, selecting the required profile in the drop down menu]()
![Do not change the "name" field]()
![Giving the name of your html file in file field]()
![clicking on save policy to save it]()
![Saved rule]()
## Testing
![Testing the template]()
## Saving the Configuration
![clicking on save config to save the policy]()
## Verification and Evidence
* **Interface Checks**: In [Configuration Portal](/architecture/interface/configuration_portal), Custom Settings → Custom Templates: new template appears in the list with correct content and is assigned to the intended policy or block page.
* **Log Analysis**: When a block or redirect occurs, the custom template is served. Config logs show the template change if applicable.
* **Performance Validation**: Trigger a block or use case that invokes the template; the custom message or page displays as designed.
**Related**: [Startup Parameters](/use_cases/customisation/startup_parameters), [Customisation](/use_cases/customisation/customisation), [Access Restriction](/use_cases/access_restriction/access_restriction), [Troubleshooting](/troubleshooting/troubleshooting)
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
* **[Startup Parameters](/use_cases/customisation/startup_parameters)** - configure SafeSquid startup parameters (LISTEN\_IP, MASTER\_IP, LOG\_LEVEL, threading) for performance and reliability.
* **[Customisation](/use_cases/customisation/customisation)** - customize SafeSquid's behavior through custom templates for error pages and branding, and startup parameters for performance tuning and operational configuration.
# Customisation
Source: https://docs.safesquid.com/use_cases/customisation/customisation
Customize SafeSquid's behavior through custom templates for error pages and branding, and startup parameters for performance tuning and operational configuration.
# Customize SafeSquid templates and startup parameters
SafeSquid customization covers custom templates (error pages, branding) and startup parameters (performance and operational configuration). The documents below describe each.
## Custom templates and startup configuration guides
### [Custom Templates](/use_cases/customisation/custom_templates)
Organizations face user confusion when blocked content displays generic error messages without branding or escalation procedures. Custom templates enable branded error pages in any language with company logos, help desk contacts, and policy explanations. User awareness and corporate identity improve while support tickets decrease. Use the document to configure custom templates for blocking scenarios.
### [Startup Parameters](/use_cases/customisation/startup_parameters)
Default SafeSquid configurations may not match enterprise requirements for threading, memory, logging, cluster sync, or socket tuning. Startup parameters control listening interfaces, thread management, buffer sizes, and master-slave configurations. Organizations optimize proxy performance and enable clustering or remote logging. Use the document to configure startup.ini and tune the proxy.
## Next steps
After tuning, verify with Verify your setup and [Performance Plot](/use_cases/performance_acceleration/performance_plot); for clustering see [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering).
# Startup Parameters
Source: https://docs.safesquid.com/use_cases/customisation/startup_parameters
Configure SafeSquid startup parameters (LISTEN_IP, MASTER_IP, LOG_LEVEL, threading) for performance and reliability.
# Tune SafeSquid Configuration With Startup Parameters
## Startup parameters control proxy behavior and tuning
SafeSquid loads default configuration/startup parameters from the startup.ini file. You can modify the startup parameter values from SafeSquid GUI. Modified values of startup parameters are stored in **/opt/safesquid/startup.ini** file.
SafeSquid loads default setup parameters from the setup.ini file. To modify setup parameters, you should take a copy of the setup.ini file and store it as **/opt/safesquid/setup.ini** before editing it manually.
## Startup Parameters
| **Field** | **Explanation** |
| - | - |
| **LISTEN\_IP** | A proxy server acts as an intermediate/bridge between the internet and the user's computer. The socket on which SafeSquid should bind, and then serve is LISTEN\_IP. LISTEN\_IP is the IP address that listens for incoming TCP connections. The default value for LISTEN\_IP is "\*" which allows SafeSquid to bind the instance to more than one IP address. |
| **LISTEN\_PORT** | LISTEN\_PORT is an HTTP port that will listen for all incoming requests in the SafeSquid proxy. SafeSquid instance binds on LISTEN\_IP: LISTEN\_PORT and serves the request. The default value for LISTEN\_PORT is 8080. |
| **MASTER\_IP** | MASTER\_IP is an IP address of a Master server in a Master-Slave settings/configuration. Master-Slave settings/configuration is generally used to ensure automatic synchronization of policies among various clustered services, or even remote proxy servers. SafeSquid can be invoked as a Slave and can be configured to synchronize and fetch configuration parameters and policies from a remote-based SafeSquid Master server. The default value for MASTER\_IP is "" which is for standalone proxy service. |
| **MASTER\_PORT** | MASTER\_PORT is an HTTP port that along with MASTER\_IP is used for Master-Slave settings/configuration. The default value for MASTER\_PORT is "". For standalone proxy service always keep MASTER\_IP and MASTER\_PORT blank. |
| **SEND\_SOCKET\_BUFFERS** | The SafeSquid throughput can be boosted by TCP tuning of the socket buffers. Each network socket is allocated a send buffer for outbound packets and a receive socket for inbound packets. SEND\_SOCKET\_BUFFERS is used for tuning the outbound data buffer. The default value for SEND\_SOCKET\_BUFFERS is 131072. |
| **RECEIVE\_SOCKET\_BUFFERS** | The SafeSquid throughput can be boosted by TCP tuning of the socket buffers. Each network socket is allocated a send buffer for outbound packets and a receive socket for inbound packets. RECEIVE\_SOCKET\_BUFFERS is used for tuning the inbound data buffer. The default value for RECEIVE\_SOCKET\_BUFFERS is 131072. |
| **TCP\_KEEPIDLE\_TIME** | TCP\_KEEPIDLE\_TIME is the time (in seconds) to keep an idle TCP connection active. The default value for TCP\_KEEPIDLE\_TIME is 900. |
| **TCP\_KEEPINTVL\_TIME** | TCP\_KEEPINTVL\_TIME is the interval between packets sent to validate the TCP connection. Default value for TCP\_KEEPINTVL\_TIME is 75. |
| **TCP\_KEEPCNT\_COUNTS** | TCP\_KEEPCNT\_COUNTS is the number of keepalive probes to be sent before terminating the connection. The default value for TCP\_KEEPCNT\_COUNTS is 9. |
| **PASSWORD\_CACHE\_SIZE** | SafeSquid provides an excellent Password Caching feature which is used to reduce the latency when authentication is desired from a remote authentication system. PASSWORD\_CACHE\_SIZE is the maximum number of password cache entries stored in memory. The default value for PASSWORD\_CACHE\_SIZE is 8111. |
| **PASSWORD\_CACHE\_EXPIRE\_TIME** | PASSWORD\_CACHE\_EXPIRE\_TIME is the time (in seconds) to keep the password cache entries in memory and clean the entry after the expiry time. The default value for PASSWORD\_CACHE\_EXPIRE\_TIME is 3600 seconds. |
| **NEVER\_SYNC** | The SafeSquid service when invoked as SLAVE fetches policies from a remote SafeSquid server. You can specify the section's name in a comma-separated format that need not be fetched from the Master instance for synchronization. The default value for NEVER\_SYNC is "cache". |
| **ALWAYS\_SYNC** | The SafeSquid service when invoked as SLAVE fetches policies from a remote SafeSquid server. You can specify the section's name in a comma-separated format that should be fetched from the Master instance for synchronization. The default value for ALWAYS\_SYNC is "". |
| **LOG\_SIZE\_LIMIT** | LOG\_SIZE\_LIMIT is the size (in bytes) that specifies the maximum size of any log file, after which SafeSquid executes log rotation. The default value for LOG\_SIZE\_LIMIT is 524288000 in bytes. |
| **SYNCTIME** | SYNCTIME is the time (in seconds) after which the slave server will synchronize with the Master server by fetching policy configuration. The default value for SYNCTIME is 99 seconds. |
| **LOG\_LEVEL** | LOG\_LEVEL is the numerical value that determines the details that will be logged in the log file, like REQUESTS, SECURITY, REDIRECT, etc. This parameter affects only the SafeSquid Native Log. You can control the verbosity of the Native log with this parameter. Selecting too many options could affect the size of the log file. The default value for LOG\_LEVEL is 134217727. Note: For debugging set 268435455. ADVICE-0; REQUEST-1; NETWORK-2; LDAP-4; HEADER-8; INTERFACE-16; COOKIE-32; REDIRECT-64; TEMPLATE-128; TEXT\_ANALYZER-256; REWRITE-512; LIMITS-1024; CACHE-2048; PREFETCH-4096; ICP-8192; FORWARD-16384; SYNC-32768; ANTIVIRUS-65536; EXTERNAL-131072; ICAP-262144; SSL-524288; CATEGORY-1048576; URLCOMMAND-2097152; MODULE-4194304; SECURITY-8388608; WARN-16777216; ERROR-33554432; PROFILES-67108864; DEBUG-134217728. |
| **PROCESS\_OLD\_LOGS** | PROCESS\_OLD\_LOGS is the numeric value that specifies the activity to be done during Log Rotation. When the log file exceeds the LOG\_SIZE\_LIMIT, SafeSquid executes the Log Rotation process. If PROCESS\_OLD\_LOGS value is set to 0 then SafeSquid will just open a new log file and delete the earlier file. If PROCESS\_OLD\_LOGS value is set to 1 then SafeSquid will open a new log file and compress the earlier file with the current time-stamp. If PROCESS\_OLD\_LOGS value is set other than 0 and 1 then SafeSquid will open a new log file and rename the earlier file with the current time-stamp. The default value for PROCESS\_OLD\_LOGS is 1. |
| **STACKSIZE** | STACKSIZE is the numeric value defined for the stack size of a thread created by SafeSquid. If STACKSIZE is specified as 20, then the SafeSquid executable will set the thread stack size to 2^20 i.e. 1024KB. For optimum use of memory, this value should be a multiple of page size. The default value for STACKSIZE is 21. |
| **MALLOC\_CHECKING** | This feature is not yet described. |
| **OVERLOAD\_FACTOR** | OVERLOAD\_FACTOR is a numeric value used to dynamically control the number of connections held in the client pool. OVERLOAD\_FACTOR along with MAXTHREADS strengthen SafeSquid's capability to deal with DDoS attacks or even when such conditions get developed unintentionally. The default value for OVERLOAD\_FACTOR is 10. |
| **SOCKET\_TIMEOUT** | SOCKET\_TIMEOUT is the minimum time (in seconds) a socket handle will be monitored by SafeSquid for a consecutive incoming request on an established connection. If the client-side application supports pipelining, the subsequent request will be handled with nearly zero latency. SafeSquid will additionally check for a socket's availability for 10 times the socket\_timeout before considering it a dead socket. The default value for SOCKET\_TIMEOUT is 6 seconds. |
| **THREAD\_TIMEOUT** | SafeSquid can use the same thread to handle consecutive connections. THREAD\_TIMEOUT is the minimum time (in seconds) a thread is kept alive after serving a request, and can serve a new request immediately after serving the first request. Keeping a higher THREAD\_TIMEOUT reserves virtual memory for a longer period but reduces the CPU overheads involved in the creation of a new thread. Keeping a lower THREAD\_TIMEOUT releases virtual memory faster and may be beneficial if the environment requires a large number of concurrent threads while conserving virtual memory. The default value for THREAD\_TIMEOUT is 10 seconds. |
| **HOSTNAME** | HOSTNAME is your SafeSquid server hostname, the name by which the proxy's host or service name is referred. HOSTNAME is also used as the \[realm] parameter for the authentication process. HOSTNAME can be configured even in the General Section of SafeSquid's run-time configuration. HOSTNAME can be set to the IP address if you intend to manage SafeSquid without setting it as your browser's proxy server. Note: If you intend this instance to be a part of a load-balanced clustered service, then ensure each instance participating in the cluster has a common HOSTNAME. The default value for HOSTNAME is "". |
| **DOMAIN** | DOMAIN is the Domain Name for the SafeSquid server. A domain name represents an Internet Protocol (IP) resource, such as a personal computer used to access the Internet, a server computer hosting a website, or the website itself or any other service communicated via the Internet. The default value for DOMAIN is "". |
| **MAXTHREADS** | MAXTHREADS is a numeric value to define the maximum number of concurrent threads SafeSquid will open. The default value for MAXTHREADS is 8192. |
| **MAX\_FDS** | MAX\_FDS is a numeric value to define the maximum number of handles that can be used for input/output resources. The default value for MAX\_FDS is 32768. |
| **EXTENDED\_UDP\_IP** | EXTENDED\_UDP\_IP is the UDP IP to write extended logs on the UDP server. The default value for EXTENDED\_UDP\_IP is "". |
| **EXTENDED\_UDP\_PORT** | EXTENDED\_UDP\_PORT is a UDP port to write extended logs on a UDP server. The default value for EXTENDED\_UDP\_PORT is "". |
| **NATIVE\_UDP\_IP** | NATIVE\_UDP\_IP is the UDP IP to write native logs on the UDP server. SafeSquid will write native logs on the UDP server using UDP sockets when both NATIVE\_UDP\_IP and NATIVE\_UDP\_PORT are mentioned. The default value for NATIVE\_UDP\_IP is "". |
| **NATIVE\_UDP\_PORT** | NATIVE\_UDP\_PORT is a UDP port to write native logs on the UDP server. SafeSquid will write native logs on the UDP server using UDP sockets when both NATIVE\_UDP\_IP and NATIVE\_UDP\_PORT are mentioned. The default value for NATIVE\_UDP\_PORT is "". |
| **CONFIG\_UDP\_IP** | CONFIG\_UDP\_IP is the UDP IP to write config logs on the UDP server. The default value for CONFIG\_UDP\_IP is "". |
| **CONFIG\_UDP\_PORT** | CONFIG\_UDP\_PORT is a UDP port to write config logs on the UDP server. The default value for CONFIG\_UDP\_PORT is "". |
| **REAL\_TIME\_DB\_WRITE** | REAL\_TIME\_DB\_WRITE determines whether SafeSquid logs should be written in the SQLite database. If REAL\_TIME\_DB\_WRITE is set to 1, real-time logs will be written. If set to 0, they will not be written. Default: 1. |
| **STATEMENT\_COUNT** | SafeSquid uses the STATEMENT\_COUNT parameter to optimize writing into the SQLite database. STATEMENT\_COUNT is the maximum number of log lines written into the database in one transaction. The default value of STATEMENT\_COUNT is 100. |
:::note
You can tune up the SafeSquid for better results. You can modify Startup Parameters to obtain better performance by tweaking the overall system & application tuning. Quite a few users have experienced difficulties due to a lack of understanding of SafeSquid's configuration, and possibly due to insufficient documentation on the subject.
:::
## Next steps
* **[Master-Slave](/use_cases/scaling_and_high_availability/master_slave)** - configure SafeSquid master-slave architecture for centralized policy sync and reporting across slave instances.
* **[Configuration Sync](/use_cases/customisation/configuration_sync)** - discover how to enable configuration synchronization across a SafeSquid proxy cluster to ensure consistent policy deployment, reduce administrative overhead, and improve system reliability and security.
# External Parser
Source: https://docs.safesquid.com/use_cases/data_leakage_prevention/adaptable_external_parser
Use SafeSquid External Parser to send request or response content to a custom program for specialized inspection, transformation, or policy decisions.
# Invoke custom inspection logic safely
## Problem statement
Some enterprises need content checks that go beyond built-in controls. They may need a custom parser, a proprietary classifier, or an integration with internal inspection tooling. Without a controlled way to extend inspection, teams either miss required controls or build unsafe side paths around the proxy.
## Client scenario
Use External Parser when you need to:
* send content to a custom executable or script
* inspect request bodies, response bodies, or both
* integrate specialized internal logic into the web-control path
* test advanced content decisions without replacing SafeSquid
This is a powerful feature. Treat it as an extension point that can affect performance, reliability, and content-handling safety.
## Key benefits
External Parser lets SafeSquid call a custom program during transaction processing. That can support specialized DLP logic, proprietary content checks, and workflow-specific enforcement that built-in controls do not cover directly.
## Prerequisites
### Client-side preparations
* Ensure the relevant traffic passes through SafeSquid.
* For HTTPS traffic, enable HTTPS inspection if the parser must see decrypted content.
### SafeSquid-side setup
* Prepare the executable or script and confirm it handles input safely.
* Decide whether content should be passed by `Pipe` or `File`.
* Test the parser on representative payloads before applying it broadly.
* Ensure the host has enough capacity because external processing adds latency and failure risk.
## Setup instructions
### Enable the global section
In **Configure → Custom Settings → External Applications**, set **Enabled** to `TRUE`.
This activates the section that allows SafeSquid to invoke external programs.
### Create an application policy
Under **Application Policies**, add a policy entry and define:
* **Enabled**
* **Comment**
* **Profiles**
* **Executable**
* **Type**
* **Applies to**
* **Run once per session**
* **Send header**
### Set the executable path carefully
Use **Executable** to define the program and arguments. If you do not use an absolute path, SafeSquid relies on the host `PATH`, which is harder to audit and troubleshoot.
### Choose how content is passed
Set **Type** based on parser behavior:
* `Pipe` sends content to standard input
* `File` writes content to a temporary file and passes the file path as the last argument
Choose the method your parser is designed to handle. A mismatch here causes silent-looking failures.
### Limit scope before broad rollout
Use **Profiles** so the parser applies only to high-risk traffic or a controlled pilot group first.
This reduces latency surprises and makes troubleshooting much easier.
## Verification and validation
### Positive test
Send a controlled request or response that should trigger the parser.
Expected result:
* the parser runs
* the transaction reflects the expected modified or inspected outcome
* logs show the request path and resulting policy behavior
### Negative test
Send traffic outside the intended profile or content scope.
Expected result:
* the parser does not run unnecessarily
* unaffected traffic follows normal SafeSquid processing
### Operational checks
Verify:
* parser exit status behavior
* transaction latency before and after enabling the parser
* what happens when the parser returns a non-zero status code
## Troubleshooting guide
### The parser never seems to run
Likely causes:
* the global section is disabled
* the policy is disabled
* the request does not match the configured profile or direction
Isolation steps:
* confirm **Enabled** is `TRUE` globally and in the entry
* confirm **Applies to** matches request, response, or both
* confirm the traffic matches the intended profile
Remediation:
* enable the correct objects
* correct the scope
* retest with a controlled request
### The parser runs but has no visible effect
Likely causes:
* the executable exits with a non-zero status
* the parser output is not in the expected format
* the wrong headers are being sent
Isolation steps:
* test the executable outside SafeSquid
* confirm the output format is valid
* confirm whether request headers, response headers, or both are being sent
Remediation:
* fix the executable behavior
* correct the output format
* retest with a known-good sample
### Performance degrades after enabling the parser
Likely causes:
* the parser runs on too much traffic
* file-based processing adds overhead
* the executable is slow or unstable
Isolation steps:
* compare latency before and after deployment
* check whether the parser applies globally instead of to a pilot profile
* measure execution time on representative payloads
Remediation:
* narrow scope with profiles
* optimize the parser
* switch passing mode if appropriate
* retest under load
## Related controls / next steps
* Use [Content Fingerprints](/use_cases/data_leakage_prevention/true_mime_fingerprints) when file-type validation is the main need.
* Use [Text Analyzer](/use_cases/data_leakage_prevention/text_analyser) and [Image Analyzer](/use_cases/data_leakage_prevention/image_analyser_ai) before building custom logic for problems SafeSquid already solves natively.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) to investigate parser-side effects and request outcomes.
# Block Emails or Files including Archives or Social Posts using Keywords
Source: https://docs.safesquid.com/use_cases/data_leakage_prevention/block_emails_or_files_including_archives_or_social_posts_using_keywords
Block emails, files, archives, and social posts by keyword in SafeSquid for data leakage protection.
# Block Emails, Files and Social Posts Using Keywords
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
## Problem and benefit
When an employee or user on the network leaks confidential information intentionally or unintentionally, the organization can suffer large losses. Data leakage can occur through many channels. Users may upload important documents to the internet. Even when content filtering blocks Microsoft Word and Excel uploads, users can create archives and attempt to upload them. Many organizations do not block archive files because administrators use them to transfer large log files. Organizations may protect data from external intruders but not from theft or accidental disclosure by employees and partners, who may copy content from Word or Excel and email it to third parties.
In modern era, these kind of data leaks are become a challenge for organizations. Organizations are in a quest for content filtering software's which can deeply inspect archive files and able to identify whether the archive or emails contains any confidential details of organization. Most of such archive files and emails have important keywords that should be matched while tracing the Data Leakage.
This challenge is also big for security experts because when there is an upload the post data formation is different for Gmail / Google Drive/ Media fire/ Drobox etc. The wide range of formations of post data made it difficult for security experts to derive concrete solution to these challenges.
SafeSquid **Advanced DLP** in **SafeSquid SWG** analyzes post data, inspects archives via file decomposition, and identifies archive files, emails, or social posts containing keyword matches. Administrators can then block uploads by user (e.g. XYZ) or block data transfer to specific destinations (e.g. abcd.com). The Advanced DLP solution is managed from the SafeSquid Self-Service Portal, where administrators create keyword expression matches. SafeSquid SWG downloads those expressions and loads them into memory. When a user uploads an archive or writes an email, SafeSquid SWG analyzes the post data and sends it to the ClamAV daemon for signature verification. When the keyword expression matches the email or file content, ClamAV responds and SafeSquid applies the policy configured for that keyword match.
## [Manage Keyword Signatures using Self Service portal](/architecture/overview/safesquid_swg)
## Configure SafeSquid SWG for using Custom Signatures
On configure page of SafeSquid interface open the Real time content security side menu. Click on Clam antivirus section to configure the policy.
![Select Configure section to Block Emails or Files including archives or Social Posts using Keywords]()
Click on Global part of ClamAV Section and make Enabled as True.
![Select Global part of ClamAV Section and make Enabled as True to Block Emails or Files including archives or Social Posts using Keywords]()
Now click on clamav subsection to configure the policy.
![Select clamav subsection to configure the policy]()
Enable the default policy in the subsection for virus signature detection.
![Enable the default policy in the subsection for virus signature detection]()
The policy appears in the list with the configured name, conditions, and BLOCK action (see screenshot below).
![The default policy in the subsection for virus signature detection.]()
Click on bottom left Icon to save the configuration.
![Save default policy in the subsection for virus signature detection.]()
:::note
After configuring the policy as above, go to the Support page and click Refresh to refresh subscription details.
:::
## Testing signature detection
HTTPS Inspection must be enabled in SafeSquid. If not, see [How to enable HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection).
### Test using office documents
Set proxy in the client browser and open Gmail. Confirm HTTPS traffic is inspected by SafeSquid; otherwise SafeSquid cannot block mail containing the configured keyword(s).
![Testing Signature detection that Block Emails or Files including archives or Social Posts using Keywords]()
Create a dummy Microsoft file containing the configured keywords. Prepare a separate archive file for testing.
![Create a dummy Microsoft file with configured keywords for testing]()
Attach the sample Microsoft file to a mail. SafeSquid blocks the attachment per policy.
![SafeSquid block attachment by default policy for virus signature detection.]()
That's it. Your created signatures are in the action and your data is safe.
### Test using archive files
Attach the archive file to a mail; SafeSquid blocks the archive per policy.
![Testing using archive files by default policy for virus signature detection.]()
### Test using emails
Create an email draft using the keywords for which signatures were configured.
Before sending the mail SafeSquid will identify the keywords and will block the mail. You can see that **Save Failed** in gmail compose box.
![Test using emails by default policy for virus signature detection.]()
In the browser, after clicking Send the mail remains in a sending state and is blocked.
![Test using emails by default policy for virus signature detection.]()
### Test using social media posts
Open [www.facebook.com](http://www.facebook.com) and log in with test credentials.
Now try to post a status update using your keywords. When you click on submit button, you will not see your post on Facebook page.
![Test using social media posts by default policy for virus signature detection.]()
Posting the same status from the timeline is also blocked when it contains the configured keywords.
![Test using social media posts by default policy for virus signature detection.]()
Now try to post the comment, you will not be able to post any comments with those specified keywords.
![Not able to post any comments with those specified keyword due to default policy for virus signature detection.]()
The same test can be run on other sites by posting data containing the configured keywords. SafeSquid blocks posts that contain those keywords.
## Troubleshooting
### Check SafeSquid logs
You can check SafeSquid logs for troubleshooting, if things are not working as explained above.
![If default policy for virus signature detection is not working then refer SafeSquid logs for troubleshooting,]()
### Check ClamAV daemon status
You can check whether ClamAV daemon is running or not using following command.
```bash theme={null}
netstat -lnp | grep clamd
```
![Check ClamAV daemon Status in proxy sever command line]()
If you found that ClamAV daemon is not running then restart using following command.
```bash theme={null}
/etc/init.d/clamav-daemon restart
```
### Check signatures file
If ClamAV service is running then check whether you have signatures database file on disk or not using locate command.
```text theme={null}
updatedb && locate safesquid.ldb
/var/lib/clamav/safesquid.ldb
/var/lib/safesquid/content_signatures/safesquid.ldb
```
### Check ANTIVIRUS profiles applicability
![Check ANTIVIRUS profiles applicability]()
If you still got any problem, you can send us mail at [support@safesquid.net](mailto:support@safesquid.net)
## Next steps
* **[SafeSquid SWG Overview](/architecture/overview/safesquid_swg)** - SafeSquid Secure Web Gateway overview — software-defined deployment, core architecture, enforcement components, intelligence feeds, browser security, and operational services.
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
# Block Inappropriate Images by Using Image Analyzer
Source: https://docs.safesquid.com/use_cases/data_leakage_prevention/block_inappropriate_images_by_using_image_analyzer
Block inappropriate images in real time with SafeSquid Image Analyzer for safe browsing.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Block inappropriate images in real time with Image Analyzer
Use the Image Analyzer to prevent users from viewing pornographic or inappropriate images by analyzing graphical content in real time.
## Prerequisites
HTTPS Inspection should be enabled in SafeSquid. If not enabled, see the document - [How to enable HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection).
## [Access the SafeSquid User Interface](/architecture/interface/configuration_portal)
## Go to Configure page
![Go to Configure Page Section to block inappropriate images by using Image Analyzer]()
## Go to Real time content security
![Go to Real time content security section to block inappropriate images by using Image Analyzer]()
## Go to Image analyzer
![Go to Image analyzer section to block inappropriate images by using Image Analyzer]()
## Go to Filtering Policies
![Select Filtering Policies section to block inappropriate images by using Image Analyzer]()
![Verify default policy true to block inappropriate images by using Image Analyzer]()
## Testing
Try to open any pornographic website you will see that the images will block due to SafeSquid Image Analyzer
![Block search due to Image Analyzer]()
## Next steps
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Content Moderation
Source: https://docs.safesquid.com/use_cases/data_leakage_prevention/content_analyser
Combine SafeSquid categorization, text analysis, and image analysis to control inappropriate or risky web content with validation-ready policy design.
# Combine category and content controls
## Problem statement
Category filtering alone misses pages that are uncategorized, newly created, user generated, or mixed in purpose. Enterprises that need safer browsing, acceptable-use enforcement, or sensitive-content control must inspect both where traffic goes and what the content actually contains.
## Client scenario
Use this approach when you need to:
* block inappropriate or risky content across allowed and unknown sites
* combine category rules with text and image inspection
* tune policies differently for students, staff, contractors, or privileged users
* reduce reliance on a single detection method
## Key benefits
SafeSquid content moderation combines three useful control paths:
* categorization for fast domain and site-level decisions
* Text Analyzer for body-content scoring
* Image Analyzer for direct visual-content inspection
Together, these controls improve coverage across known bad sites, uncategorized pages, and allowed platforms that still contain policy-violating material.
## Prerequisites
### Client-side preparations
* Route client web traffic through SafeSquid.
* Deploy the Root CA and enable HTTPS inspection if you need to inspect encrypted sites.
### SafeSquid-side setup
* Confirm categorization, Text Analyzer, and Image Analyzer are available in the configuration portal.
* Decide which profiles need strict enforcement and which need monitored exceptions.
* Plan a tuning period before enabling broad blocking in production.
## Setup instructions
### Start with categorization
Use categorization to block clearly unwanted websites and reduce the amount of content that needs deeper inspection.
If you already know the domains that should never be accessed, category and custom categorization policies are the fastest first layer.
### Add image inspection for visual risk
Use [Image Analyzer](/use_cases/data_leakage_prevention/image_analyser_ai) where visual content matters, especially on social, media-rich, and user-generated platforms.
This closes a gap that text-only filtering cannot see.
### Add text inspection for page and payload content
Use [Text Analyzer](/use_cases/data_leakage_prevention/text_analyser) to score risky keywords, sensitive terms, or policy markers in HTML and other text-based content.
This helps with uncategorized pages, regulated data patterns, and sites that contain mixed content.
### Scope by profile instead of weakening the baseline
If some teams legitimately need broader access, use profiles and targeted exceptions. Do not lower the global protection level for everyone just to solve one workflow.
## Verification and validation
### Positive tests
Test each layer separately and then together:
* access a blocked category site
* access a page with risky text that should trigger Text Analyzer
* access a page with images that should trigger Image Analyzer
Expected result:
* category rules block known-bad destinations
* text and image controls catch content that category rules alone would miss
* logs show which layer triggered the final action
### Negative tests
Use legitimate business pages with neutral text and images.
Expected result:
* permitted sites remain usable
* legitimate business images are not blocked unnecessarily
* text scoring does not trigger on harmless content
## Troubleshooting guide
### Harmful content still appears on allowed sites
Likely causes:
* HTTPS inspection is missing
* text or image analyzers are disabled
* the content does not match current rules
Isolation steps:
* confirm the site is decrypted
* confirm both analyzer sections and rules are enabled
* inspect which profiles applied to the session
Remediation:
* enable the missing inspection path
* add or refine analyzer rules
* retest with controlled samples
### Legitimate content is blocked too often
Likely causes:
* analyzer thresholds are too aggressive
* global rules are being used where profile-scoped rules are needed
Isolation steps:
* review the exact trigger path
* compare affected users against intended policy scope
Remediation:
* tune thresholds
* narrow the rule scope
* introduce explicit exceptions for approved workflows
## Related controls / next steps
* Use [Text Analyzer](/use_cases/data_leakage_prevention/text_analyser) for keyword and pattern scoring.
* Use [Image Analyzer](/use_cases/data_leakage_prevention/image_analyser_ai) for visual-content control.
* Use [Content Fingerprints](/use_cases/data_leakage_prevention/true_mime_fingerprints) when file-type spoofing and upload control also matter.
# Data Leakage Prevention
Source: https://docs.safesquid.com/use_cases/data_leakage_prevention/data_leakage_prevention
Catch data leaks before they become breaches — detect SSN, credit cards, PHI in uploads and block them in real time.
# Catch Data Leaks Before They Become Breaches
**The scenario:** A sales rep emails a spreadsheet to their personal Gmail. Inside: 10,000 customer credit card numbers. By the time you find out, it's been forwarded three times and posted to Pastebin.
**The cost:** \$4.45M average breach (IBM, 2024). GDPR fine: up to €20M or 4% of revenue. PCI-DSS non-compliance: lose ability to process cards. Board wants answers.
**The problem:** Your users handle sensitive data daily — SSN, PHI, credit cards, trade secrets. Email, file uploads, social media posts — every channel is a potential leak. You can't inspect laptops after-the-fact; you need to **stop data at the exit point**, in real time.
**SafeSquid DLP sits at your network perimeter**, inspecting every byte before it leaves:
* **Text Analyser** scans uploads, emails, social posts for credit cards, SSN, PHI, keywords
* **Image Analyser** inspects image-based content for visual threat intelligence and sensitive-information egress
* **Compliance Templates** provide pre-built rules for PCI-DSS, HIPAA, GDPR
* **Real-time enforcement:** Block, log + alert, or quarantine for manager approval
**Outcome:** Data exfiltration attempts are caught before they become breaches. Compliance auditors get proof you're monitoring egress.
## Before/After SafeSquid DLP
| Scenario | Without DLP | With SafeSquid DLP |
| - | - | - |
| Rep emails customer list to personal Gmail | ❌ No visibility, discovered in audit 6 months later | ✅ **Blocked** — SSN pattern detected in attachment, manager notified, SIEM alert fired |
| Contractor uploads pricing spreadsheet to personal Dropbox | ❌ Data exfiltrated, posted to competitor website | ✅ **Quarantined** — "confidential" keyword detected, manager approval required before release |
| Engineer posts AWS credentials to public GitHub gist | ❌ Credentials harvested in minutes, crypto miner deployed on EC2 | ✅ **Blocked** — API key pattern detected in POST body, SIEM alert, security review triggered |
| Finance team shares SSN spreadsheet on Slack (external workspace) | ❌ Legal discovers it 8 months later during e-discovery | ✅ **Blocked** — 9-digit SSN pattern detected, upload fails with "Policy Violation: PII Detected" message |
## How SafeSquid DLP Works
SafeSquid sits between your users and the internet, inspecting **every byte** before it leaves:
### 1. Text Analyzer Scans for Patterns
Scans uploads, emails, social posts, form submissions for:
* **Credit card numbers:** Visa, Mastercard, Amex (PCI-DSS compliance)
* **Social Security Numbers:** 9-digit SSN format (HIPAA, GDPR)
* **Protected Health Information:** Patient IDs, diagnosis codes, medical record numbers
* **Keywords:** "confidential," "internal only," "DO NOT SHARE," "proprietary"
* **Custom patterns:** Your proprietary data formats (internal employee IDs, product codes)
**How it works:** Regular expression (regex) matching against content. When a match is found, the configured action triggers (block, log, quarantine).
→ [Configure Text Analyser](/use_cases/data_leakage_prevention/text_analyser)
### 2. Image Analyzer Detects Visual Content
Inspects images in uploads and attachments:
* **Image-based sensitive-content analysis:** Detects risky or sensitive visual content in uploaded images
* **Explicit content detection:** Blocks NSFW uploads to corporate Slack, SharePoint
**Use case:** Employee screenshots customer data from internal CRM and uploads the image to personal cloud storage. Image-based analysis helps prevent that visual egress path from becoming a blind spot.
→ [Configure Image Analyser](/use_cases/data_leakage_prevention/image_analyser_ai)
### 3. Compliance Templates Provide Pre-Built Rules
No need to write regex from scratch. SafeSquid includes templates for:
* **PCI-DSS:** Credit card data (Visa, Mastercard, Amex, Discover)
* **HIPAA:** PHI (patient IDs, medical record numbers)
* **GDPR:** PII (names + addresses + SSN/passport combos)
* **Custom:** Your organization's proprietary data patterns
**How to use:** Load template → Test with dummy data → Enable blocking.
→ [Load Compliance Templates](/use_cases/access_restriction/compliance_templates)
### 4. Real-Time Enforcement
When SafeSquid detects sensitive data, you choose the action:
**Block (recommended for high-risk data):**
* Upload fails immediately
* User sees: "Policy Violation: PCI Data Detected. Contact IT Security."
* SIEM alert fired
* Manager notified
**Log + Alert (for low-risk or testing):**
* Upload proceeds, but logged
* SIEM gets alert for security review
* Useful during tuning phase (identify false positives)
**Quarantine (for ambiguous cases):**
* File held in quarantine
* Manager receives approval request with file preview
* Manager can release or permanently block
* Audit trail maintained
## When to Use DLP
✅ **Your industry requires it:**\
Healthcare (HIPAA), finance (PCI-DSS, SOX), government (ITAR, FedRAMP), retail (PCI-DSS)
✅ **You handle customer PII:**\
Names, addresses, SSN, payment info, medical records, passport numbers
✅ **You have trade secrets:**\
Source code, formulas, M\&A documents, pricing strategies, customer lists
✅ **Compliance audit coming:**\
Auditors want proof you're monitoring data egress. DLP logs export to SIEM for evidence.
✅ **Recent breach or close call:**\
Board mandates "we need to prevent the next incident." DLP provides technical controls + audit trail.
## When NOT to Use DLP (Alone)
⚠️ **DLP is not endpoint protection:**\
If data is already on a USB drive, laptop, or personal phone, network DLP won't catch it. Combine with endpoint DLP (Microsoft Purview, Symantec DLP, Forcepoint).
⚠️ **DLP is not encryption:**\
Data in transit to approved services (SharePoint, OneDrive, Salesforce) should still be encrypted. DLP blocks *unapproved* channels, not all channels.
⚠️ **DLP creates false positives:**\
Credit card regex matches test data (`4111111111111111` is a test Visa number). Don't enable hard blocking on day one. Start with **log-only mode** for 2 weeks, tune patterns, then enable blocking.
⚠️ **DLP needs SSL inspection:**\
90% of uploads are over HTTPS. If SSL inspection is disabled, DLP can't see the payload — it's encrypted. Enable SSL inspection first.
## How to Configure DLP
### Step 1: Enable SSL Inspection (Required)
DLP can't inspect encrypted uploads without SSL inspection. 90% of web traffic is HTTPS.
**Action:** [Enable SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) and deploy the Root CA to client devices.
**Verification:** Visit an HTTPS site and confirm the certificate is issued by SafeSquid-Root-CA (not the website's original cert).
***
### Step 2: Load Compliance Templates
Pre-built regex patterns for PCI-DSS, HIPAA, GDPR.
**Action:** [Load Compliance Templates](/use_cases/access_restriction/compliance_templates) in the Text Analyser configuration.
**What you'll get:**
* Credit card patterns (Visa: `^4[0-9]{12}(?:[0-9]{3})?$`, Mastercard, Amex)
* SSN pattern: `^(?!000|666)[0-8][0-9]{2}-(?!00)[0-9]{2}-(?!0000)[0-9]{4}$`
* Custom keyword lists: "confidential," "proprietary," "internal only"
***
### Step 3: Configure Text Analyser
Enable content scanning in uploads, emails, form submissions.
**Action:** [Configure Text Analyser](/use_cases/data_leakage_prevention/text_analyser)
**Settings to configure:**
* **Scan scope:** Uploads, emails, POST bodies, social media posts
* **Pattern matching:** Enable compliance templates (PCI, HIPAA, GDPR)
* **Action on match:** Block, log + alert, or quarantine
* **Exclusions:** Whitelist approved file transfer services (e.g., SFTP to partner)
***
### Step 4: Link DLP to Access Restrictions
DLP detections must trigger enforcement actions (block, log, quarantine).
**Action:** [Configure Access Restrictions](/use_cases/access_restriction/access_restriction) with DLP profile matching.
**Example rule:**
* **If:** Text Analyser detects PCI data (credit card pattern)
* **Then:** Block upload + log to SIEM + notify manager
* **Except:** Allow if destination is approved payment processor (e.g., Stripe API)
***
### Step 5: Set Up SIEM Integration
Send DLP alerts to your SIEM (Splunk, QRadar, Wazuh) for security monitoring.
**Action:** [Configure SIEM Integration](/use_cases/integrations/integrations) with syslog forwarding.
**What gets logged:**
* Timestamp, user identity, source IP
* Detected pattern (e.g., "SSN detected in upload to gmail.com")
* Action taken (blocked, logged, quarantined)
* File hash (SHA256) for forensics
SafeSquid's broader evidence model also includes bypass, privileged-access, and deep-content security records that can help explain why a DLP decision did or did not occur.
***
### Step 6: Test with Dummy Data
Don't enable blocking in production without testing. False positives will break workflows.
**Action:** Create test files with fake sensitive data:
* Fake SSN: `123-45-6789` (invalid SSN, but matches pattern)
* Test Visa card: `4111111111111111` (official test number, won't process)
* Keyword test: Text file with "CONFIDENTIAL - DO NOT SHARE"
**Upload to personal Gmail, Dropbox, etc. Verify:**
* ✅ SafeSquid blocks or logs the upload
* ✅ SIEM receives alert
* ✅ User sees policy violation message
**Tune patterns to reduce false positives** (e.g., exclude test credit card numbers).
Once tuning is complete, enable blocking for real data.
## ⚠️ Common Pitfalls
**1. Enabling DLP without SSL inspection**\
**What breaks:** 90% of uploads are HTTPS. DLP can't inspect encrypted traffic.\
**Solution:** [Enable SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) first, deploy Root CA to clients, then enable DLP.
**2. Blocking too aggressively on day one**\
**What breaks:** False positives block legitimate business workflows. Finance team can't email invoices (credit card-like numbers in invoice IDs).\
**Solution:** Start with **log-only mode** for 2 weeks. Review SIEM alerts, tune regex patterns, whitelist false positives. Then enable blocking.
**3. Forgetting compressed files**\
**What breaks:** User uploads `customer_data.zip` with 10,000 SSNs inside. DLP sees a ZIP file, not the contents.\
**Solution:** Enable [archive decompression](/use_cases/content_modifier/content_modifier) in Content Modifier. SafeSquid will extract and scan ZIP/RAR contents before allowing upload.
**4. Not whitelisting approved data channels**\
**What breaks:** You block all credit card uploads. But your payment team needs to upload transaction files to Stripe. Legitimate business stops.\
**Solution:** Create exception rules in Access Restrictions: "Allow credit card uploads to stripe.com API endpoint only."
**5. Ignoring image-based data leaks**\
**What breaks:** User screenshots customer data from CRM, uploads image to personal cloud. Text-only controls miss the image path.\
**Solution:** Enable [Image Analyser (AI-powered)](/use_cases/data_leakage_prevention/image_analyser_ai) so image-based egress is not a blind spot.
## Related Topics
**Prerequisites:**
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) — Required to inspect encrypted uploads (90% of traffic)
* [Authentication](/use_cases/authentication/authentication) — User identity needed for per-user DLP policies
**Next Steps:**
* [Text Analyser Configuration](/use_cases/data_leakage_prevention/text_analyser) — Fine-tune regex patterns
* [Image Analyser (AI-powered)](/use_cases/data_leakage_prevention/image_analyser_ai) — OCR for screenshots
* [Access Restrictions](/use_cases/access_restriction/access_restriction) — Link DLP detections to block/log actions
* [SIEM Integration](/use_cases/integrations/integrations) — Forward DLP alerts to Splunk, QRadar, etc.
**Troubleshooting:**
* [DLP False Positives](/troubleshooting/troubleshooting) — How to tune regex patterns, whitelist test data
**Use Cases:**
* [Block Personal Gmail, Allow Corporate](/use_cases/header_rewrite/block_personal_gmail_allow_google_corporate_accounts) — Prevent data leaks via personal email
* [Block Keywords in Uploads](/use_cases/data_leakage_prevention/block_emails_or_files_including_archives_or_social_posts_using_keywords) — Detect "confidential" in social posts
Uncontrolled data exfiltration drives regulatory fines (e.g. GDPR up to €20M, PCI-DSS loss of card processing), breach costs (average \$4.45M), and reputational damage. SafeSquid DLP detects and blocks sensitive data (PII, PHI, payment card data) in real time at the network perimeter. DLP logs export to SIEM; violation reports are auditor-ready. Every block or alert includes timestamp, user, detected pattern, action taken, and file hash. Plan 1–2 weeks for deployment and tuning; then quarterly pattern review and SIEM alert monitoring.
# Elevated Privacy
Source: https://docs.safesquid.com/use_cases/data_leakage_prevention/elevated_privacy
Use SafeSquid Elevated Privacy to block third-party cookies, suppress referrer data, and reduce user-agent exposure with profile-aware deployment.
# Reduce tracking without breaking everything
## Problem statement
Many websites and third-party services track user behavior through cookies, referrer headers, and user-agent details. That exposure can weaken privacy posture and increase unnecessary data disclosure. But aggressive privacy controls can also break federated login, embedded services, and browser-specific web behavior if rolled out carelessly.
## Client scenario
Use Elevated Privacy when you need to:
* block third-party cookies
* reduce referral leakage to external sites
* reduce browser fingerprint exposure
* apply stronger privacy controls to selected users or traffic profiles
## Key benefits
Elevated Privacy gives SafeSquid a graduated privacy model instead of a single all-or-nothing switch. That lets administrators tighten privacy where it matters while still allowing business exceptions where SSO, third-party identity providers, or application compatibility require them.
## Prerequisites
### Client-side preparations
* Identify the user groups, applications, and websites that depend on third-party sign-in or third-party cookies.
* Choose pilot users first before broad rollout.
### SafeSquid-side setup
* Confirm the Elevated Privacy section is available and enabled only when you are ready to test it.
* Decide which profiles need strict privacy and which need a bypass.
## Setup instructions
### Enable the global section
Set the Elevated Privacy global **Enabled** field to `TRUE`.
![Elevated Privacy restriction profile or configuration]()
Without the global switch, policy entries do not take effect.
### Create privacy policies in top-down order
Elevated Privacy entries are evaluated from top to bottom, so place narrow exceptions above broad privacy rules when a business workflow must stay functional.
![Elevated Privacy policy or profile options]()
### Choose the privacy level deliberately
Available privacy levels are:
* `NOT_REQUIRED`: disable Elevated Privacy for matching traffic
* `LOW`: block third-party cookies only
* `STANDARD`: block third-party cookies and hide HTTP and HTTPS referrer information
* `PARANOID`: block third-party cookies, hide referrer information, and hide different user agents
Use `PARANOID` carefully. Some websites and applications depend on user-agent behavior and can malfunction when that signal is suppressed or normalized.
### Build a strict privacy rule where it is appropriate
For high-privacy use cases, create a rule that applies a stronger privacy level to a dedicated profile.
The existing example remains useful:
* remove third-party cookies
* hide referrer data
* modify user-agent exposure
That helps reduce online tracking but can also break sign-in paths that depend on third-party cookies.
![Elevated Privacy rule or entry configuration]()
### Create a bypass for known business exceptions
Some sites require third-party identity providers for login. In those cases, create a bypass profile rather than weakening privacy globally.
The existing example remains valid: connections tagged with a bypass profile can skip Elevated Privacy where third-party authentication is required.
![Elevated Privacy save or apply configuration]()
## Verification and validation
### Positive tests
Test a site where privacy controls should apply.
Expected result:
* third-party cookies are blocked at the selected privacy level
* referrer exposure is reduced when using `STANDARD` or `PARANOID`
* the privacy policy applies only to the intended users or profiles
### Negative tests
Test a site that relies on federated or third-party login.
Expected result:
* the site fails when strong privacy is enforced, if it genuinely depends on third-party cookies
* the site works again when the intended bypass profile is applied
That negative test is important because it proves both the restriction and the exception path.
## Troubleshooting guide
### Users cannot sign in to sites that use external identity providers
Likely causes:
* third-party cookies are being blocked
* the wrong privacy level is applied
* the bypass profile is missing or placed too low in rule order
Isolation steps:
* identify whether the site uses third-party SSO
* inspect which privacy rule actually applied
* test the same site with and without the bypass profile
Remediation:
* add or correct the bypass profile
* move the exception above the broad rule
* retest the login flow
### Websites behave differently or render incorrectly
Likely causes:
* `PARANOID` mode is suppressing user-agent behavior needed by the site
* referrer suppression changes the application flow
Isolation steps:
* compare behavior under `STANDARD` and `PARANOID`
* identify whether user-agent-dependent content is involved
Remediation:
* reduce the privacy level for that workflow
* scope `PARANOID` mode to only the users or sites that truly need it
## Related controls / next steps
* Use [Access Restriction](/use_cases/access_restriction/access_restriction) and [Request Profiles](/use_cases/profiling_engine/request_profiles) to scope privacy controls more precisely.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) and privacy-related records to validate that the right policy path applied.
# Image Analyzer
Source: https://docs.safesquid.com/use_cases/data_leakage_prevention/image_analyser_ai
Use SafeSquid Image Analyzer to inspect images in real time and control risky or policy-violating visual content with profile-aware enforcement.
# Inspect visual content in real time
## Problem statement
Visual content can bypass text-based controls. Risky material, explicit imagery, and sensitive visual data can move through allowed websites unless the proxy evaluates the image itself.
## Client scenario
Use Image Analyzer when you need to:
* restrict inappropriate image content
* apply stricter controls to selected user groups
* create exceptions for teams with legitimate media-review duties
* test visual-content controls before moving to full enforcement
Image Analyzer should be treated as a content-risk control, not as a standalone compliance guarantee.
## Key benefits
Image Analyzer gives SafeSquid a way to inspect pictures directly instead of relying only on domain categories. That helps when risky images appear on otherwise allowed sites, user-generated platforms, or uncategorized pages.
## Prerequisites
### Client-side preparations
* Ensure client traffic is routed through SafeSquid.
* If images are delivered over HTTPS, deploy the Root CA and enable HTTPS inspection first.
### SafeSquid-side setup
* Confirm the image-analysis section is available in **Configure → Real Time Content Security → Image Analyzer**.
* Decide which user groups need stricter enforcement and which need exceptions.
* Plan a tuning phase before broad rollout because aggressive thresholds can block legitimate business content.
## Setup instructions
### Enable the global section
In **Configure → Real Time Content Security → Image Analyzer**, set **Enabled** to `TRUE`.
If the global section stays disabled, policy entries will not enforce image scanning.
### Select the default response behavior
Set **Default template** to control how blocked images are replaced.
This matters because operators and users need a visible distinction between image-policy enforcement and an image that simply failed to load.
### Configure filtering policies
Under **Filtering Policies**, create or update policy entries.
For each policy:
* set **Enabled** to `TRUE`
* use **Comment** to describe the business purpose
* use **Profiles** to scope the rule to the right traffic
* set **Threshold** based on how strict the image review should be
* set **Template** when a rule needs a specific replacement behavior
* use **Debug** carefully when you need testing without full blocking
### Use bypass rules carefully
If a team must access high-volume image platforms for legitimate business reasons, scope exceptions with **Profiles** instead of weakening the global threshold for everyone.
That keeps the risk decision explicit and auditable.
## Verification and validation
### Positive test
Use a controlled test set of images that should trigger the configured rule.
Expected result:
* SafeSquid blocks or alters the image presentation according to policy
* the event is visible in logs or reports tied to the test request
* the affected user profile matches the intended rule scope
### Negative test
Use benign business images and traffic from a profile that should be exempt.
Expected result:
* allowed users can view permitted images normally
* exempt profiles do not inherit stricter image rules by mistake
* the debug or bypass logic behaves exactly as configured
### What to watch during rollout
Verify:
* false positives on marketing, design, and e-commerce workflows
* whether HTTPS inspection is actually exposing image traffic to the proxy
* whether debug mode is still enabled after testing
## Troubleshooting guide
### Images are not being inspected
Likely causes:
* HTTPS inspection is not active
* the global section is disabled
* the request does not match the intended profile
Isolation steps:
* confirm the site is being decrypted
* confirm **Enabled** is `TRUE` globally and in the rule
* inspect the request profile assignment
Remediation:
* enable HTTPS inspection where appropriate
* enable the correct policy objects
* correct the profile mapping and retest
### Legitimate business images are being blocked
Likely causes:
* the threshold is too aggressive
* a broad policy applies to everyone
* testing rules remained enabled in production
Isolation steps:
* identify the rule that triggered
* compare the affected user group against intended scope
* review whether **Debug** or special test profiles are still active
Remediation:
* raise the threshold
* narrow the policy to the intended profiles
* create explicit exceptions for approved teams
* retest with both business and high-risk image samples
### Users report blurred or replaced images unexpectedly
Likely causes:
* a debug or enforcement template is active
* the wrong template is assigned to the rule
Isolation steps:
* inspect the rule template setting
* compare observed behavior with the configured replacement mode
Remediation:
* assign the correct template
* disable debug mode when testing is complete
## Related controls / next steps
* Use [Content Moderation](/use_cases/data_leakage_prevention/content_analyser) to combine image, text, and categorization controls.
* Use [Text Analyzer](/use_cases/data_leakage_prevention/text_analyser) for body-content scoring that complements visual inspection.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) and [Reporting Module](/use_cases/audit_and_forensics/reporting_module) to validate image-policy behavior and investigate false positives.
# Text Analyzer
Source: https://docs.safesquid.com/use_cases/data_leakage_prevention/text_analyser
Use SafeSquid Text Analyzer to score and control web content based on keywords, patterns, and MIME-aware inspection for DLP and content policy enforcement.
# Score text before it leaves control
## Problem statement
URL category decisions alone do not tell you what a page or payload actually contains. Sensitive terms, policy-violating language, and uncategorized harmful content can pass through allowed sites unless the body content is inspected directly.
## Client scenario
Use Text Analyzer when you need to:
* score page or payload content by keywords or regular expressions
* detect uncategorized inappropriate content
* identify likely data leakage indicators in web traffic
* apply different text-inspection policies to different user groups or profiles
Text Analyzer is strongest when paired with HTTPS inspection, access restriction policies, and reporting.
## Key benefits
Text Analyzer lets you inspect content instead of trusting domain reputation alone. It helps administrators build detection logic for pornography, sensitive business terms, regulatory data patterns, and custom policy markers without relying only on third-party category databases.
## Prerequisites
### Client-side preparations
* Ensure client traffic is actually passing through SafeSquid.
* If the content is encrypted, deploy the SafeSquid Root CA and enable HTTPS inspection first.
### SafeSquid-side setup
* Confirm HTTPS inspection is enabled for traffic you want to inspect.
* Identify which MIME types should be scanned. Broad scanning increases coverage but can raise false positives and processing load.
* Decide whether the first rollout should log and tune, or block immediately.
## Setup instructions
### Enable the global section
In **Configure → Real Time Content Security → Text Analyzer**, set **Enabled** to `TRUE`.
This turns on the feature globally. If the section remains disabled, none of the policy entries will take effect.
### Set the threshold deliberately
Configure **Threshold** to define when cumulative matches cause a block.
Use a lower threshold when a single match should be decisive. Use a higher threshold when you want multiple indicators before SafeSquid blocks the content.
### Choose a user-facing template
Set **Template** if you want a specific response page when the threshold is reached.
This matters in production because users and help desks need a clear signal that a policy decision, not a network fault, caused the block.
### Create filtering policies
Add policy entries under **Filtering Policies**.
For each policy:
* set **Enabled** to `TRUE`
* use **Comment** to describe the business purpose
* scope with **Profiles** when the rule should apply only to selected users or traffic classes
* restrict **Mime type** where possible, such as `text/html` or `application/json`
* define **Keyword(s)** as the regular expression or terms to match
* set **Score** to reflect how strongly one match should contribute to the block threshold
### Keep rules specific
Use targeted patterns instead of broad keywords where possible. A generic word can trigger on harmless pages and create false confidence about DLP quality.
## Verification and validation
### Positive test
Create or access a test page that contains the configured keywords often enough to exceed the threshold.
Expected result:
* SafeSquid blocks the page or payload
* the configured template appears
* the relevant log entry shows the text-analysis outcome or associated filter action
### Negative test
Access a page that contains similar but non-matching text, or a MIME type outside the rule scope.
Expected result:
* SafeSquid allows the request
* the score does not exceed threshold
* no misleading block event appears for the rule
### What to verify in logs
Verify the request shows:
* the correct user or client identity
* the expected profile set
* the correct MIME type
* the expected filter or policy outcome
## Troubleshooting guide
### Content is not being blocked
Likely causes:
* HTTPS inspection is not active for encrypted pages
* the MIME type does not match the policy
* the keyword expression does not match the actual content
* the score does not reach the threshold
Isolation steps:
* confirm the page is decrypted and visible to SafeSquid
* inspect the actual MIME type in logs
* test the expression with known matching content
* compare total score against the configured threshold
Remediation:
* enable HTTPS inspection where appropriate
* correct the MIME scope
* refine the pattern
* adjust score or threshold, then retest
### Too many false positives occur
Likely causes:
* keywords are too broad
* threshold is too low
* the rule applies to all users instead of a high-risk profile
Isolation steps:
* review blocked samples
* identify which term or pattern triggered repeatedly
* compare affected traffic against intended policy scope
Remediation:
* narrow the regex
* increase the threshold
* limit the rule with profiles or MIME types
* retest with both positive and negative examples
### Logs show requests, but not useful policy evidence
Likely causes:
* the wrong log family is being reviewed
* the request is allowed and only appears in request-level logs
* operators are checking only UI summaries and not underlying log records
Isolation steps:
* review extended and native logs together
* search by username, URL, and time window
* confirm the transaction reached the proxy path you expected
Remediation:
* use request-level logs for evidence collection
* preserve the test case details so the event can be traced again
## Related controls / next steps
* Use [Compliance Templates](/use_cases/access_restriction/compliance_templates) for pattern-based detection starting points.
* Use [Content Moderation](/use_cases/data_leakage_prevention/content_analyser) to combine categorization, text, and image controls.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) and [Reporting Module](/use_cases/audit_and_forensics/reporting_module) to validate policy outcomes and retain evidence.
# Content Fingerprints
Source: https://docs.safesquid.com/use_cases/data_leakage_prevention/true_mime_fingerprints
Use SafeSquid content fingerprinting and true MIME detection to identify disguised files, reduce spoofing risk, and improve content-control accuracy.
# Trust file content, not file names
## Problem statement
Attackers and careless users can disguise files by changing extensions, headers, or upload context. If policy decisions rely only on visible names or claimed MIME types, malware and unauthorized data transfers can slip through controls that appear correct on paper.
## Client scenario
Use content fingerprinting when you need to:
* identify the real file type instead of trusting the extension
* detect uploads or downloads that do not match their declared content type
* strengthen malware, DLP, and upload-control policies
* reduce false trust in renamed or disguised files
## Key benefits
True MIME detection improves the quality of downstream policy decisions. It helps SafeSquid distinguish between what a file claims to be and what it actually contains, which matters for malware prevention, upload governance, and sensitive-data controls.
## Prerequisites
### Client-side preparations
* Ensure the traffic path passes file uploads and downloads through SafeSquid.
* If the transfer is encrypted, enable HTTPS inspection so SafeSquid can inspect the payload.
### SafeSquid-side setup
* Identify which upload and download channels matter most, such as email, webmail, file sharing, and SaaS storage.
* Review related controls that will consume this signal, including DLP, malware, and access-restriction policies.
## Setup instructions
### Use true MIME signals in policy design
Build file-handling policies on the actual detected content type, not only on filename extensions or user-declared metadata.
This matters because extension-only controls are easy to bypass.
### Pair content fingerprinting with upload and response policies
Use true MIME awareness alongside:
* upload controls
* DLP inspection
* malware and threat-prevention controls
* request and response profiles
This turns MIME detection into an enforcement decision instead of a passive observation.
### Validate high-risk channels first
Start with traffic paths where disguised files create the most risk:
* browser uploads to SaaS platforms
* downloads from unknown or uncategorized sources
* email and webmail attachments
## Verification and validation
### Positive test
Use a controlled file whose extension or declared type does not match its real content.
Expected result:
* SafeSquid identifies the transaction based on the real content type
* the related policy decision follows the true MIME result
* logs and reports reflect the transaction in a way operators can investigate
### Negative test
Transfer a legitimate file whose extension and content type match.
Expected result:
* SafeSquid allows or handles the file according to normal policy
* no spoofing-specific control triggers by mistake
### Evidence to review
Verify:
* request and response logs for the transaction
* policy outcomes tied to upload or download handling
* whether the detected content type aligns with the actual test file
## Troubleshooting guide
### File-type controls do not trigger
Likely causes:
* HTTPS inspection is missing for encrypted transfers
* the related enforcement policy does not consume the MIME signal
* the test transaction bypassed the expected proxy path
Isolation steps:
* confirm the transfer passed through SafeSquid
* confirm decryption for HTTPS traffic
* inspect the request and response policy path
Remediation:
* enable the correct inspection path
* attach the MIME-aware signal to a blocking or logging rule
* retest with a controlled spoofed file
### Legitimate files are blocked unexpectedly
Likely causes:
* an enforcement rule is too broad
* the policy treats all uncommon file types as suspicious
Isolation steps:
* review the exact content type detected
* compare the rule scope with the business use case
Remediation:
* narrow the rule
* add approved exceptions for legitimate business formats
* retest with both approved and disguised files
## Related controls / next steps
* Use [Content Moderation](/use_cases/data_leakage_prevention/content_analyser) for broader content-risk controls.
* Use [Adaptable External Parser](/use_cases/data_leakage_prevention/adaptable_external_parser) when custom downstream inspection logic is required.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) for evidence collection during spoofing and malware investigations.
# DNS Security
Source: https://docs.safesquid.com/use_cases/dns_security/dns_security
SafeSquid's DNS-level security features including DNSBL, GeoIP filtering, and homograph attack detection.
# Apply DNS-Level Security Controls
## Problems addressed
Unrestricted DNS resolution reaches malicious, geo-noncompliant, or lookalike domains before HTTP policy runs. That wastes bandwidth, weakens compliance narratives, and feeds phishing risk.
## Outcomes operators expect
* Block or flag domains via DNSBL before TCP connections complete ([DNS Blacklisting](/use_cases/dns_security/dnsbl)).
* Apply geography- and ASN-aware context for policy and reporting ([Server Geo-Location](/use_cases/dns_security/geoip)).
* Reduce IDN homograph impersonation at resolution time ([Homograph Detection](/getting_started/core_features/homograph_detection)).
## Advantages vs “HTTP-only” policy
DNS-layer controls fail closed earlier in the chain than URL filtering alone for many threats. Combine with [Access Restriction](/use_cases/access_restriction/access_restriction) and [Profiling Engine](/use_cases/profiling_engine/profiling_engine) for full coverage.
**Product-level comparative claims** (for example vs other SWG vendors): **Not SSOT-backed in this doc set**—see [What is SafeSquid SWG?](/architecture/what_is_safesquid_swg).
## Acquire, deploy, use
Configure DNS security features in the SafeSquid administration UI per each linked guide. Verify blocks and log lines as described in those pages.
SafeSquid provides DNS-level security at the domain resolution layer: DNS-based blacklisting, geographic IP filtering, and internationalized domain name (IDN) homograph detection. For architecture placement inside SWG, see [Integrated DNS Security](/architecture/overview/integrated_dns_security).
```mermaid theme={null}
flowchart TB
Client[Client Request] --> SafeSquid[SafeSquid Proxy]
SafeSquid --> DNS[DNS Resolution]
DNS --> DNSBL[DNSBL Check]
DNSBL --> GeoIP[GeoIP Check]
GeoIP --> Homograph[Homograph Check]
Homograph --> Allow[Allow]
Homograph --> Block[Block]
```
**Why DNS-level security matters:** Blocking threats at DNS resolution (before connection) is faster and more efficient than content inspection. DNS security provides early threat mitigation, reduces bandwidth waste, and creates audit evidence before users reach malicious sites.
## DNS security controls and configuration
### [DNS Blacklisting](/use_cases/dns_security/dnsbl)
Unrestricted DNS resolution allows access to known-malicious domains and increases malware, phishing, and compliance risk. DNSBL blocks dangerous sites before connection by querying DNS-based blacklist services. Blocking at resolution reduces exposure and supports audit evidence in logs and reports. Configure DNSBL in Real-time content security and verify blocks in Security Logs.
### [Server Geo-Location](/use_cases/dns_security/geoip)
Organizations face regional compliance gaps and threat exposure when destination geography is unknown. Server Geo-Location classifies destinations by country and ASN for location-aware policies. Country-based access control and reporting support data residency and geo-restriction requirements. Enable geo profiles in Profiling Engine and reference them in Access Restriction and Reporting.
### [Homograph Detection](/getting_started/core_features/homograph_detection)
IDN homograph attacks use visually similar characters to impersonate legitimate domains and enable phishing. Homograph detection identifies and blocks these impersonation attempts at DNS resolution. The control reduces lookalike-domain risk and supports evidence in DNS security logs. Configure allowed or blocked IDN patterns in DNS Security when the feature is available.
## Source register
| Topic | Status | Source |
| - | - | - |
| DNSBL integration and policy flow | **Confirmed** | [DNS Blacklisting](/use_cases/dns_security/dnsbl), [Integrated DNS Security](/architecture/overview/integrated_dns_security) |
| GeoIP / `server_country` style fields | **Confirmed** | [Server Geo-Location](/use_cases/dns_security/geoip) |
| Homograph UI availability by version | **Confirmed** | [Homograph Detection](/getting_started/core_features/homograph_detection) (version checks) |
## Next steps
Use DNS security together with [Access Restriction](/use_cases/access_restriction/access_restriction) and [Profiling Engine](/use_cases/profiling_engine/profiling_engine) for URL and application policy. See [Integrated DNS Security](/architecture/overview/integrated_dns_security) for architecture context.
# DNS Blacklisting
Source: https://docs.safesquid.com/use_cases/dns_security/dnsbl
Configure SafeSquid DNSBL to block access to dangerous sites using DNS-based blacklist services.
## Problems addressed
Unrestricted DNS resolution reaches malicious or abused domains before HTTP policy applies. SOC teams need an early, loggable block at resolution when threat feeds supply DNS-style indicators.
## Outcomes operators expect
* Block or template-block domains that return configured DNSBL codes before TCP to origin.
* Evidence in Security Logs and reports for audit—see **Verify** below.
## Advantages vs URL-only filtering
DNSBL fails closed earlier in the chain for **list-based** domain risk. URL and content rules still apply for paths, categories, and payloads.
## Acquire, deploy, use
Complete **Prerequisites**, configure **Real-time content security → DNS Blacklist** as below, then run block tests and log checks.
## Why use DNS Blacklisting?
Unrestricted DNS resolution allows clients to reach domains listed as malicious in threat feeds. DNSBL blocks these connections at the resolution layer-before any traffic is exchanged-reducing exposure to malware, phishing, and botnet callbacks.
| Use DNSBL When | Use Access Restrictions Instead |
| - | - |
| Blocking known-malicious infrastructure | Blocking specific URL categories (Adult, Social) |
| Early threat mitigation is required | Policy requires deep content analysis |
| Using SOC-provided threat feeds | Blocking individual sites/FQDNs |
| Reducing bandwidth waste from botnets | Enforcing user-specific access rules |
## Prerequisites
* SafeSquid SWG installed and operational.
* SafeSquid configured as the primary DNS resolver (see [Supporting Services: BIND](/architecture/interface/bind)).
* A valid DNSBL service domain (e.g., `in.dnsbl.org` or a private threat intel list).
* Outbound network access to the DNSBL service.
## Configure DNSBL in Real-time content security
1. [Access the SafeSquid User Interface](/architecture/interface/configuration_portal).
2. Open the Configure page.
3. Go to Real-time content security.
![Go to Real time content security]()
![Configure page and Real-time content security]()
4. Open the DNS Blacklist section.
![DNS blacklist section]()
![DNS blacklist configuration options]()
![DNS blacklist domain and blocked IPs]()
![DNS blacklist global settings]()
5. Set Global options:
* **Enabled**: TRUE to enable DNSBL; FALSE to skip querying blacklist services.
* **Template**: Name of the block template displayed when a domain is blocked. Leave blank for default "blocked" message.
* **Domain**: DNSBL service domain for queries (e.g., `in.dnsbl.org`). SafeSquid appends this to queried domains: `example.com.in.dnsbl.org`.
* **Blocked IP addresses**: Comma-separated IP ranges that trigger a block when returned by the DNSBL (e.g., `127.0.0.1-127.0.0.6` for in.dnsbl.org).
:::tip
**DNSBL Service Compatibility**
Administrators can use any DNS-based blacklist service (e.g., Spamhaus, local threat feed). Configure the **Domain** and **Blocked IP addresses** fields to match your service's return codes.
:::
***
### Understanding Return IP Codes (in.dnsbl.org)
When SafeSquid queries `in.dnsbl.org`, the service returns specific IP addresses indicating threat categories:
| Return IP | Category | Description |
| - | - | - |
| 127.0.0.2 | UCE | Unsolicited commercial email |
| 127.0.0.3 | Fraud | Financial fraud, phishing |
| 127.0.0.4 | Spam Promo | Promotional spam |
| 127.0.0.5 | Illegal Content | Illegal or harmful content |
| 127.0.0.6 | Pre-emptive | Pre-emptive blocking |
| 127.0.0.7 | List Practices | Improper list practices |
| 127.0.0.8 | Botnet/Malware | Botnet C\&C, malware delivery |
**Configuration:** To block all categories, set **Blocked IP addresses** to `127.0.0.1-127.0.0.8`.
***
6. Save. SafeSquid caches DNSBL query results for efficiency.
### Example: block sites via DNSBL server
Use blacklisting domain in.dnsbl.org and blocked IP addresses 127.0.0.1-127.0.0.6. SafeSquid blocks all matching domains and displays the blocked template. Use DNSBL when a SOC provides the list or when many domains must be blocked.
![DNSBL example configuration]()
## Verify configuration and blocked requests
* **Interface**: Confirm DNS Blacklist is enabled, Domain and Blocked IP addresses are set, and Template is correct.
* **Block test**: Request a domain known to be listed; expect block page and no connection to origin.
* **Logs**: In [Security Logs](/use_cases/audit_and_forensics/security_logs), confirm entries for blocked requests (action/result indicating DNSBL block).
* **Audit**: Run a report filtered by block reason or DNSBL. Export for evidence that the control is active and blocking malicious domains.
## Troubleshooting
| Issue | Symptom | Resolution |
| - | - | - |
| **DNSBL service unreachable** | Blocks not applied; DNS timeouts | **Check:** Network connectivity to DNSBL service. **Verify:** Firewall allows outbound DNS (UDP/TCP 53) to DNSBL domain. **Test:** `nslookup example.com.in.dnsbl.org` from SafeSquid server. |
| **Wrong blocked-IP range** | No blocks or incorrect blocks | **Fix:** Align **Blocked IP addresses** with your DNSBL provider's return codes. Example: `127.0.0.1-127.0.0.8` for in.dnsbl.org. **Verify:** Query a known-bad domain and check what IP the DNSBL returns. |
| **Cache causing stale results** | Site unblocked after DNSBL update | **Cause:** SafeSquid caches DNSBL responses for performance. **Fix:** Wait for cache expiry (TTL-based) or restart SafeSquid: `systemctl restart safesquid`. |
| **False positive blocks** | Legitimate site blocked | **Identify:** Check DNSBL query logs to confirm it's a list issue. **Fix:** Add domain to bypass/allow-list in Access Restrictions. **Alternative:** Switch to a different DNSBL provider with lower false-positive rates. |
| **DNSBL enabled but no blocks** | Malicious sites still accessible | **Check:** 1) **Enabled** is TRUE. 2) **Domain** field is correct. 3) **Blocked IP addresses** includes the range returned by your DNSBL. **Test:** Query a known-malicious domain (use a test entry from your DNSBL provider). |
| **Direct IP access bypasses DNSBL** | Users access sites by IP instead of hostname | **Limitation:** DNSBL only works on DNS queries, not direct IP connections. **Mitigation:** Use [Access Restriction](/use_cases/access_restriction/access_restriction) to block by IP range or category. |
**Still having issues?** Contact SafeSquid support with:
* DNSBL service domain you're using
* Sample blocked domain query results
* Contents of `/var/log/safesquid/native/safesquid.log` showing DNS resolution attempts
## Source register
| Topic | Status | Source |
| - | - | - |
| DNSBL UI path (Real-time content security) | **Confirmed** | This page |
| Example DNSBL domain `in.dnsbl.org` | **Draft** | Third-party list; confirm contract and return codes before production |
| Log evidence via [Security Logs](/use_cases/audit_and_forensics/security_logs) | **Confirmed** | Linked doc |
| Direct-IP bypass limitation | **Confirmed** | This page, [Access Restriction](/use_cases/access_restriction/access_restriction) |
## Next steps
* Return to [DNS Security](/use_cases/dns_security/dns_security).
* Align resolver placement: [BIND](/architecture/interface/bind).
# Server Geo-Location
Source: https://docs.safesquid.com/use_cases/dns_security/geoip
Configure SafeSquid SWG server geo-location profiles to enforce location-aware policies for access control, compliance, and routing optimization.
# Apply Location-Aware Policy With Server Geo-Location on SafeSquid SWG
Classify destination servers by country, region, and ASN (Autonomous System Number) to enforce location-aware access policies, meet data residency requirements, and block high-risk regions.
## Why use Server Geo-Location?
Without destination geography visibility, organizations cannot enforce regional restrictions or identify threat patterns by location. Server Geo-Location enables:
* **Data residency compliance:** Block traffic to non-compliant regions (GDPR, data sovereignty laws)
* **Threat mitigation:** Block high-risk countries or ASNs known for malicious activity
* **Audit evidence:** Logs show `server_country`, `server_region`, and `server_asn` for every connection
* **Usage analytics:** Report bandwidth consumption by destination geography
| Use Geo-Location When | Use Application Signatures Instead |
| - | - |
| Enforcing regional data flow policies | Blocking specific apps (Facebook, TikTok) |
| Blocking high-risk countries (SOC directive) | Categorizing traffic by application type |
| Meeting compliance requirements (GDPR, export control) | Enforcing SaaS vs on-prem routing |
| Generating geo-based usage reports | Identifying zero-day apps by behavior |
## Prerequisites
* SafeSquid installed and operational (see [Getting Started](/getting_started/welcome))
* Profiling Engine enabled (see [Profiling Engine](/use_cases/profiling_engine/profiling_engine))
* Up-to-date GeoIP database (SafeSquid includes MaxMind GeoLite2 by default)
* Admin access to [Configuration Portal](/architecture/interface/configuration_portal)
* Consistent DNS resolution (see [Supporting Services: BIND](/architecture/interface/bind))
## Configuration Steps
1. **Verify GeoIP database**\
Navigate to **Profiling Engine** → **Server Geo-Location**
* Check that database status shows a recent update date
* If outdated, update the database (see GeoIP database update instructions)
2. **Create geo-location profile**\
Click **Add New** to create a profile:
* **Name:** Descriptive identifier (e.g., `Block-High-Risk-Countries`, `EU-Only-Access`)
* **Criteria:** Select countries, regions, or ASNs to match
* **Action:** Specify whether to allow or block
3. **Save and verify**\
Save the profile and confirm it appears in the profile list.\
If multiple profiles overlap, check rule precedence (first-match-wins).
4. **Apply to policies**\
Reference the geo-location profile in:
* **Access Control:** Block/allow by destination country (see [Access Restriction](/use_cases/access_restriction/access_restriction))
* **Bandwidth Management:** Prioritize local regions (see [Manage Bandwidth](/use_cases/performance_acceleration/manage_bandwidth))
* **Reporting:** Build dashboards by destination geography (see [Reporting Module](/use_cases/audit_and_forensics/reporting_module))
5. **Test with regional destinations**\
Validate by accessing known sites hosted in target countries.
## Verification
* **Interface**: Profile visible, enabled, and referenced in policies.
* **Logs**: Confirm `server_country`, `server_region`, and `server_asn` in [Security Logs](/use_cases/audit_and_forensics/security_logs).
* **Demonstrate control to auditor**: Export logs or run a report filtered by `server_country`. Show policy configuration that denies or allows by geography. Provide a country-based dashboard from the [Reporting Module](/use_cases/audit_and_forensics/reporting_module) as evidence of active enforcement.
* **Curl test**:
```bash theme={null}
# Test access to a site hosted in a specific country
curl -I https://example-regional-site.tld --proxy http://your-safesquid-proxy:8080
```
* Expected indicators in logs:
```text theme={null}
timestamp=2025-11-10 action=deny module=access_restriction
server_ip=203.0.113.45 server_country=RU server_region=EU server_asn=AS12345
profile=Block-High-Risk-Countries rule=deny-non-compliant-regions user=jdoe
```
* Create a country-based dashboard and filter by `server_country` to validate reporting.
## Troubleshooting
* GeoIP database outdated
* Symptom: `server_country` missing or incorrect
* Fix: update GeoIP database; restart profiling service if required
* CDN or anycast endpoints
* Symptom: destination resolves to global POP; country differs from brand site location.
* Fix: allow-list CDNs by ASN where appropriate; use the [Architecture hub](/architecture/overview/safesquid_swg).
* Private or RFC1918 destinations
* Symptom: no geo data for non-routable IPs
* Fix: add explicit policy exceptions; rely on identity or application profiles. See [User Identities](/use_cases/authentication/user_identities).
* DNS-based variance
* Symptom: different resolver returns regionally distinct IPs.
* Fix: standardize resolvers; verify [Integrated DNS Security](/architecture/overview/integrated_dns_security).
* IPv6 classification gaps
* Symptom: missing geo for v6-only hosts
* Fix: ensure IPv6 ranges in GeoIP; confirm dual-stack handling
* HTTPS SNI/IP mismatch
* Symptom: SNI points to geo X, IP maps to geo Y
* Fix: prefer IP-based geo for enforcement; validate SNI with server verification. See [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection).
* Performance impact from complex geo sets
* Symptom: latency on policy evaluation
* Fix: consolidate countries into regions; push heavy rules higher in precedence; cache outcomes
External references:
* MaxMind GeoIP2 database: `https://dev.maxmind.com/geoip`
* Regional compliance baselines (example): `https://www.iso.org/standard/77312.html`
## Source register
| Topic | Status | Source |
| - | - | - |
| `server_country`, `server_region`, `server_asn` log fields | **Confirmed** | This page (example log snippet) |
| Profiling Engine / geo profile wiring | **Confirmed** | This page, [Profiling Engine](/use_cases/profiling_engine/profiling_engine) |
| GDPR / export-control sentence-level mapping | **Draft** | Legal/compliance review outside this KB |
| MaxMind as upstream | **Draft** | Confirm shipped database vendor per deployment |
## Next steps
* [DNS Security](/use_cases/dns_security/dns_security) hub.
* [Access Restriction](/use_cases/access_restriction/access_restriction) for enforcement rules.
# Homograph Detection
Source: https://docs.safesquid.com/use_cases/dns_security/homograph_detection
Detect and block IDN homograph attacks that use visually similar characters to impersonate legitimate domains.
Detect and block Internationalized Domain Name (IDN) homograph attacks where attackers use visually similar characters from different scripts (Cyrillic, Greek, etc.) to impersonate legitimate domains and enable phishing attacks.
## Why Homograph Detection Matters
**The threat:** Attackers register domains that look identical to legitimate sites by using Unicode characters from different alphabets. For example:
* `apple.com` (legitimate) vs `аpple.com` (Cyrillic 'а')
* `paypal.com` (legitimate) vs `pаypаl.com` (Cyrillic characters)
**Business impact:**
* Credential theft (users enter passwords on fake login pages)
* Financial fraud (fake banking/payment sites)
* Brand impersonation (trust exploitation)
* Phishing campaigns bypass traditional URL filters
**How it works:** Browsers display internationalized domain names (IDN) using Unicode, making it nearly impossible for users to distinguish malicious lookalikes from legitimate domains.
## When to Use Homograph Detection
| Use Homograph Detection When | Use Other Controls Instead |
| - | - |
| Protecting against phishing campaigns | Blocking known-malicious domains (use DNSBL) |
| Users access international sites legitimately | Enforcing URL category restrictions |
| Brand impersonation risk is high | Application-specific blocking (use App Signatures) |
| Compliance requires IDN attack mitigation | Blocking specific FQDNs (use Access Restriction) |
:::tip
**Combine with Other Defenses**
Homograph detection works best alongside [DNSBL](/use_cases/dns_security/dnsbl) (block known-bad domains), [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) (detect fake certificates), and user security awareness training.
:::
## Prerequisites
* SafeSquid installed and operational (see [Getting Started](/getting_started/welcome))
* Admin access to [Configuration Portal](/architecture/interface/configuration_portal)
* DNS resolution handled by SafeSquid (see [Supporting Services: BIND](/architecture/interface/bind))
## Configuration Steps
1. **Access Configuration Portal**\
Navigate to **Real Time Content Security** → **DNS Blacklist**
![Homograph Configuration]()
2. **Enable Homograph Detection**
* **Enabled:** Set to **TRUE**
* **Save** the configuration
3. **Apply Changes**\
Click **Apply** to activate the new policy.
:::note
**Feature Location**
Homograph Detection is configured in the **DNS Blacklist** section because it operates at the DNS resolution layer, intercepting suspicious domain patterns before connection.
:::
## Verification
Test that Homograph Detection is blocking IDN attack attempts:
### Method 1: Command-Line Test (cURL)
```bash theme={null}
# Test with a homograph attack domain (Cyrillic 'а' in apple)
curl -v -x http://YOUR-SAFESQUID-IP:8080 http://аpple.com
```
**Expected result:** SafeSquid blocks the request and displays a block page.
**Note:** The URL `http://аpple.com` uses a Cyrillic 'а' (U+0430) instead of the Latin 'a' (U+0061).
![cURL Verification Output]()
***
### Method 2: Browser Test
1. Configure your browser to use SafeSquid as proxy (see [Connect Your Client](/getting_started/client_configuration/connect_your_client))
2. Navigate to `http://аpple.com`
3. **Expected result:** SafeSquid displays a block page
![Browser Verification Output]()
***
### Method 3: Log Verification
Check SafeSquid logs for blocked homograph attempts:
```bash theme={null}
tail -f /var/log/safesquid/security.log | grep -i homograph
```
**Expected entries:** Logs should show blocked requests with `reason=homograph` or similar indicators.
## Troubleshooting
| Issue | Symptom | Resolution |
| - | - | - |
| **Homograph attacks not blocked** | IDN lookalike domains load successfully | **Check:** 1) Homograph Detection is **Enabled** = TRUE. 2) Changes were applied. 3) Browser is using SafeSquid as proxy. **Test:** Access `http://аpple.com` (with Cyrillic 'а'). |
| **Legitimate IDN sites blocked** | International domains (e.g., Chinese, Arabic) blocked incorrectly | **Cause:** Overly aggressive detection. **Fix:** Add legitimate IDN domains to bypass/allow-list in Access Restrictions. **Alternative:** Adjust detection sensitivity if the feature supports it. |
| **No log entries** | Can't confirm blocks in logs | **Check:** 1) Security logging is enabled. 2) Verify log path `/var/log/safesquid/security.log` exists. 3) Check disk space (logs may stop if disk is full). |
| **Feature not available** | Homograph Detection option not visible | **Check:** SafeSquid version supports this feature. **Update:** If missing, update to latest SafeSquid release. **Verify:** Run `safesquid -v` to check version. |
**Still having issues?** Contact SafeSquid support with:
* Screenshot of Homograph Detection configuration
* Sample blocked domain attempts
* Contents of `/var/log/safesquid/native/safesquid.log` and `/var/log/safesquid/security.log`
## How Homograph Detection Works
SafeSquid analyzes domain names during DNS resolution and checks for:
1. **Mixed scripts:** Domains using characters from multiple alphabets (e.g., Latin + Cyrillic)
2. **Lookalike patterns:** Visual similarity to known legitimate domains
3. **Suspicious Unicode:** Non-ASCII characters in domain names
When detected, SafeSquid blocks the request and logs the attempt for audit trails.
## Source register
| Topic | Status | Source |
| - | - | - |
| Homograph control + version gate | **Confirmed** | This page (`safesquid -v`), configuration steps |
| `reason=homograph` style log indicators | **Draft** | **CTO:** confirm exact field strings in shipping logs |
| Algorithm detail (mixed scripts, lookalikes) | **Draft** | High-level description; engineering SSOT if customers ask |
## Next Steps
* **Layer defenses:** Combine with [DNSBL](/use_cases/dns_security/dnsbl) to block known-malicious domains
* **Inspect certificates:** Enable [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) to detect fake TLS certificates on lookalike domains
* **Monitor attempts:** Use [Security Logs](/use_cases/audit_and_forensics/security_logs) and [Reporting](/use_cases/audit_and_forensics/reporting_module) to track homograph attack patterns
* **User training:** Educate users about IDN attacks and visual domain verification
# Block Personal Gmail, Allow Google Corporate Accounts
Source: https://docs.safesquid.com/use_cases/header_rewrite/block_personal_gmail_allow_google_corporate_accounts
Block personal Gmail and allow only Google Workspace accounts in SafeSquid for productivity and data security.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Block Personal Gmail and Allow Only Corporate Google Accounts
## Problem: Personal webmail increases data and productivity risk
Organizations that use Google Workspace need to allow corporate Google accounts while blocking personal Gmail. Personal email on the office network consumes productive time and can create a path for leakage of confidential information. Many organizations use Google Corporate domains for mail; Gmail cannot be blocked entirely. SafeSquid SWG allows only configured corporate domains for Google sign-in and blocks personal Gmail.
## Key benefits
Corporate Google accounts continue to work for mail and Google services. Personal Gmail sign-in is blocked so users cannot use non-corporate accounts. Policy is enforced via header manipulation so only allowed domains are accepted by Google. Administrators list allowed domains (e.g. `corp.example.com`) in one place.
## Prerequisites
* [HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection) enabled so SafeSquid can inspect and modify HTTPS traffic to Google.
* Access to SafeSquid Configuration Portal (Configure page).
* List of allowed Google Workspace domains (e.g. `corp.example.com`). Multiple domains are separated by comma with no space.
## Call to action
### Enable policy from Policies and Profiles section
Match requests to the Google Application policy first.
1. From SafeSquid Dashboard open **Configure** (top right).
2. Open **Policies and profiles** section.
3. Search for the default profile named **GOOGLE APPLICATION**.
![Search for the default policy GOOGLE APPLICATION]()
4. Edit and enable this policy.
![Edit and enable this policy]()
:::note
Administrators can add User Groups to restrict the policy to specific groups.
:::
### Enable policy from Header Filter section
Insert a header so only allowed domains are accepted by Google.
1. Open **Restriction Policies** (left panel).
2. Open **Privacy Control** submenu.
3. Open [Header Filter](/use_cases/header_rewrite/header_obfuscation) section. Ensure **Global** is **Enabled** **True**.
![Header filter under Restriction Policies]()
4. Open **Insert** tab.
5. Search for default profile **GOOGLE APPLICATION** (first rule).
![Insert tab and GOOGLE APPLICATION default profile]()
6. Edit and enable this rule. Add allowed domains in the value field (comma-separated, no space). Save the policy.
![Edit and enable rule; add allowed domains in value field and save]()
:::note
Multiple domains: separate each with a comma, no space.
:::
## Verification and Evidence
* **Block test:** Sign in to Google (e.g. mail.google.com) with a **personal** Gmail account through the proxy. Google returns an error template or message listing the allowed domains; sign-in is blocked.
* **Allow test:** Sign in with a **corporate** Google Workspace account (allowed domain). Sign-in succeeds and mail works.
* **Interface:** **Configure** → **Restriction Policies** → **Privacy Control** → **Header Filter** shows the GOOGLE APPLICATION Insert rule with the correct domain list. **Policies and profiles** shows GOOGLE APPLICATION enabled.
* **Audit:** Access logs and restriction logs show traffic to Google; export from the [Reporting Module](/use_cases/audit_and_forensics/reporting_module) for evidence of policy enforcement.
## Troubleshooting
| Symptom | Likely cause | Resolution | Verification |
| - | - | - | - |
| Personal Gmail still works | HTTPS inspection off or Header Filter rule disabled/wrong | Enable HTTPS Inspection; enable Header Filter Insert rule; set value to allowed domains only (comma, no space) | Retry personal sign-in; confirm block |
| Corporate account blocked | Domain missing or typo in rule value | Add corporate domain to Insert rule value; check TLD and spelling | Sign in with corporate account |
| Google shows generic error | Expected when personal is blocked | None; message may list allowed domains | Confirm rule and profile applied to traffic |
## Next steps
* [Header Re-Write](/use_cases/header_rewrite/header_obfuscation) for header filtering and privacy controls.
* [Access Restriction](/use_cases/access_restriction/access_restriction) for URL and category-based policies.
* [SSL Inspection](/use_cases/ssl_inspection/configure_https_inspection) for HTTPS visibility and bypass rules.
# Header Filter Configuration and Reference
Source: https://docs.safesquid.com/use_cases/header_rewrite/header_filter_configuration
Configure SafeSquid header filter: Global, Allow, Deny, Insert rules, and solution verification.
# Review Header Filter Configuration Options
## Global
The Global section controls how SafeSquid edits HTTP header messages between the browser and the Internet. Use it to increase privacy, control client requests and server responses, and add, delete, or modify request and response headers. The Insert sub-section adds new headers or modifies existing ones in addition to Allow/Deny.
The following subsections cover:
1. Request header patterns that are passed from browsers to webservers.
2. Response header patterns that are coming from webservers to clients.
![Header Filter section in Restriction Profiles]()
### Enabled
Enable or Disable the header filter section.
**TRUE:** Enable header filter section.
**FALSE:** Disable header filter section.
### Policy
Select the default action to take, when no matching entry for a requested header is found.
**ALLOW:** Allow everything Except rules defined under Deny subsection.
**DENY:** Deny everything Except rules defined under Allow subsection.
## Allow
When the Policy is Deny, rules defined under this sub-section, are exclusively allowed access.
Add a new allow entry to explicitly permit the header for all connections or a specific set of conditions.
![Header Filter Allow sub-section]()
### Enabled
Enable or Disable this entry.
**TRUE:** Enable this entry.
**FALSE:** Disable this entry.
### Comment
For documentation and future references, explain the relevance of this entry with your policies.
### Profiles
Specify the Profiles applicable for this entry.
This entry will be applicable only if the connection has any one of the specified profiles.
Leave it Blank, to apply for all connections irrespective of any applied profile.
To avoid application to a connection that has a profile, use a negated profile (! profile).
### Type
A regular expression matching the header type to which this entry applies.
Headers are in the form of type and value.
Leave blank to Match everything.
Example: X-GoogApps-Allowed-Domains.
### Value
A regular expression matching the header values.
Leave blank to Match everything.
**Example:** text/html.
### Applies to
This option is to select whether this entry applies to the server header, client header, or both.
**CLIENT:** This entry will be applied only for request headers, sent by the client.
**SERVER:** This entry will be applied only for response headers, sent by the server.
### Example
#### Rule#1
Allow WebSockets for connections with profile "ALLOW WEBSOCKET". Use this when all users' WebSocket connections are denied by default. The Allow rule permits WebSocket connections for a defined application or service and user group.
![Allow WebSocket rule for ALLOW WEBSOCKET profile]()
## Deny
When the Policy is Allow, rules defined under this sub-section, are denied access exclusively.
Add a deny entry to explicitly block the header for all connections or a specific set of conditions.
![Header Filter Deny sub-section]()
### Enabled
Enable or Disable this entry.
**TRUE:** Enable this entry.
**FALSE:** Disable this entry.
### Comment
For documentation and future references, explain the relevance of this entry with your policies.
### Profiles
Specify the Profiles applicable for this entry.
This entry will be applicable only if the connection has any one of the specified profiles.
Leave it Blank, to apply for all connections irrespective of any applied profile.
To avoid application to a connection that has a profile, use a negated profile (! profile).
### Type
A regular expression matching the header type to which this entry applies.
Headers are in the form of type and value.
Leave blank to Match everything.
Example: X-GoogApps-Allowed-Domains.
### Value
A regular expression matching the header value.
Leave blank to Match everything.
Example: text/html.
### Applies to
This option is to select whether this entry applies to the server header, client header, or both.
**CLIENT:** This entry will be applied only for request headers, sent by the client.
**SERVER:** This entry will be applied only for response headers, sent by the server.
### Example
#### Rule#1
Deny all WebSocket connections by matching request headers containing "WebSocket"
For connections with the profile "REMOVE WEBSOCKETS" "websocket: upgrade" header will be removed from request headers, which will result in a WebSocket connection never being established.
![Deny WebSocket rule REMOVE WEBSOCKETS]()
### Insert
In this sub-section add rules to modify request and response headers. Insert additional information into the headers sent by the client browser.
![Header Filter Insert sub-section]()
### Enabled
Enable or Disable this entry.
**TRUE:** Enable this entry.
**FALSE:** Disable this entry.
### Comment
For documentation and future references, explain the relevance of this entry with your policies.
### Profiles
Specify the Profiles applicable for this entry.
This entry will be applicable only if the connection has any one of the specified profiles.
Leave it Blank, to apply for all connections irrespective of any applied profile.
To avoid application to a connection that has a profile, use a negated profile (! profile).
### Type
A regular expression matching the header type to which this entry applies.
Headers are in the form of type and value.
Leave blank to Match everything.
Example: X-GoogApps-Allowed-Domains.
### Value
A regular expression matching the header value.
Leave blank to Match everything.
Example: text/html.
### Applies to
This option is to select whether this entry applies to the server header, client header, or both.
**CLIENT:** This entry will be applied only for request headers, sent by the client.
**SERVER:** This entry will be applied only for response headers, sent by the server.
### Example
#### Rule#1
Restrict access to the corporate Google account only. When users try to log in with a personal Google account, login is blocked. Use the custom request header X-GoogApps-Allowed-Domains to specify allowed domains. Include the domain registered with Google Workspace in the list.
![X-GoogApps-Allowed-Domains header insert for corporate Google]()
#### Rule#2
Allow YouTube during lunch hours while blocking inappropriate content. Enforce YouTube strict mode for all users. Use header insert to add the custom header YouTube-Restrict for strict restricted access. Per Google, YouTube strict mode does not filter 100% of inappropriate content.
![YouTube-Restrict header insert for strict mode]()
## View headers
In this sub-section, you can find the example headers with type and values.
![View headers sub-section with example headers]()
## Verification and Evidence
* **Interface Checks**: In [Configuration Portal](/architecture/interface/configuration_portal), Restriction Profiles → Header Filter: Global enabled, Allow/Deny/Insert rules match intent. Type, Value, and Applies to are set correctly.
* **Log Analysis**: Requests and responses show modified or stripped headers per policy; WebSocket or target-site behavior matches expected allow/deny/insert.
* **Performance Validation**: Test with profile (e.g. ALLOW WEBSOCKET, REMOVE WEBSOCKETS, X-GoogApps-Allowed-Domains); expected sites work and restricted behavior is enforced.
**Related**: [Cookie Inspection](/use_cases/cookie_inspection/cookie_inspection), [Access Restriction](/use_cases/access_restriction/access_restriction), [URL Redirection SafeSearch](/use_cases/access_restriction/safesearch), [Troubleshooting](/troubleshooting/troubleshooting)
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
* **[Cookie Inspection](/use_cases/cookie_inspection/cookie_inspection)** - configure SafeSquid cookie filter to manage, allow, or block cookies for user privacy and policy enforcement.
* **[Access Restriction](/use_cases/access_restriction/access_restriction)** - build SafeSquid access policies that make web decisions by identity, destination, time, application, and content so enforcement stays precise and auditable.
# Header Re-Write
Source: https://docs.safesquid.com/use_cases/header_rewrite/header_obfuscation
Configure SafeSquid header filter to allow, deny, or insert HTTP headers for client-server communication control.
## Problem
HTTP headers carry authentication tokens, tracking identifiers, and client fingerprints. Uncontrolled headers break login flows, leak internal paths, or weaken privacy controls. Administrators need allow, deny, and insert rules before downstream content rewriting runs.
## Benefits
SafeSquid header filter adds, deletes, or modifies request and response headers by policy. Global default (allow-all vs deny-all) plus Allow, Deny, and Insert lists give predictable ordering; Insert runs after Allow and Deny.
## Advantages
**Confirmed:** Header processing runs before the Content Re-Write header stage, so header policy applies first in the pipeline described in SafeSquid documentation.
**Draft (CTO confirmation):** Whether header rewriting depth matches a specific competing SWG depends on vendor feature matrices—do not claim parity without a source register entry.
## Call to action
Open the [Configuration Portal](/architecture/interface/configuration_portal) → Real-time content security → Header filter. Set Global policy, then tune Allow, Deny, and Insert. Follow [Header Filter Configuration and Reference](/use_cases/header_rewrite/header_filter_configuration) for field-level steps and verification.
## Header filter behavior and scope
SafeSquid modifies HTTP header messages exchanged between clients (e.g. web browsers) and the requested web service. Administrators can add, delete, or modify header directives.
The request and response headers are processed by this section before they are processed by the facility to rewrite headers in the Content Re-Write section.
Header filter has 4 sub-sections: Global, Allow, Deny, and Insert.
The processing of a request or a response, by this section is bypassed if the Global sub-section is set to False. The policies in Allow / Deny / Insert thus become muted.
The policies in the Insert section are processed after the policies in the Allow / Deny lists.
Setting the Default Policy to Allow in the Global Sub-Section, permits all HTTP headers to be exchanged unless there is a policy directive in the Deny List to prevent a header from being exchanged.
Similarly setting the Default policy to Deny shall block all non-mandatory HTTP headers from being exchanged, unless a policy in the Allow list, explicitly permits.
## Header filter configuration guides
### [Header Filter Configuration and Reference](/use_cases/header_rewrite/header_filter_configuration)
Header allow/deny/insert behavior requires correct Global policy and rule configuration. The document covers the Global section, Allow and Deny rule parameters (Type, Value, Applies to, Profiles), and Insert rules for adding or modifying headers. Solution verification confirms policies apply as intended. Use the document to configure and validate header filtering.
## Next steps
Combine header filter with [Access Restriction](/use_cases/access_restriction/access_restriction) and [Cookie Inspection](/use_cases/cookie_inspection/cookie_inspection) for full request/response control.
# Rewriting Policies Reference
Source: https://docs.safesquid.com/use_cases/header_rewrite/rewriting_policies_reference
Field-by-field reference for SafeSquid Content Modifier rewriting policies including pattern matching, replacement, MIME types, and applies-to targets.
# Rewriting policies control what SafeSquid modifies
Content Modifier uses regex-based rewriting policies to modify web page body content, client request headers, server response headers, and POST data in real time. Each policy defines a match pattern, a replacement, a MIME scope. A target (body, client header, server header, or POST data). Policies are ordered; SafeSquid evaluates them top-to-bottom and applies all matching rules to each connection.
## Global section enables or disables all rewriting
Access the Content Modifier section in the SafeSquid interface under **Configure → Real time content security → Content modifier**.
### Enabled
Enable or disable the entire Content Modifier section.
* **TRUE**: SafeSquid applies rewriting policies to matching connections.
* **FALSE**: SafeSquid skips all content modification. No policies are evaluated.
## Policy fields define match conditions and actions
Each rewriting policy contains the following fields.
### Enabled
Enable or disable this specific policy entry.
* **TRUE**: SafeSquid evaluates this policy.
* **FALSE**: SafeSquid skips this entry.
### Comment
Document the purpose of this policy entry. A future administrator reading the policies should understand the intent of each entry from the comment alone.
### Profiles
Specify the profiles applicable for this entry. SafeSquid applies the policy only if the connection has any one of the specified profiles. Leave blank to apply to all connections regardless of profile. Negate a profile with `!` (e.g. `!bypass`) to exclude connections with that profile.
### Mime type
Specify a regular expression matching the MIME types for which this entry applies. According to their nature and format, MIME type identifies files on the Internet.
Set this field to limit the scope. If left blank, SafeSquid checks all file types — a significant performance cost.
**Examples:**
* `text/html` — HTML pages only
* `^image/` — all image types
* `^application/` — all application types
* `application/x-shockwave-flash` — Flash content only
### Pattern
A regular expression matching the area of text inside the file to modify. SafeSquid uses Perl-compatible regular expressions (PCRE). The pattern may include a trailing `/` followed by flag characters (e.g. `/i` for case-insensitive). If a `/` appears anywhere else in the pattern, flags must be specified explicitly.
Use parenthesized capture groups to extract portions of the match for use in the replacement.
### Replace
Specify the replacement text to substitute in place of the matched text. The replacement may contain back-references to strings captured using parentheses in the Pattern field (e.g. `\1`, `\2`).
### Applies to
Select what the rewrite entry targets:
| Value | Target | Notes |
| - | - | - |
| **BODY** | Response body (HTML, JavaScript, CSS, etc.) | Modifies web page content before delivery to the client. |
| **CLIENT** | Client request header | Rewrites the client HTTP header before SafeSquid parses it. Take care not to remove headers required for request handling. |
| **SERVER** | Server response header | Rewrites the response header from the remote web server. Same caution as CLIENT applies. |
| **POST** | POST/PUT request body | Rewrites POST or PUT data sent when submitting a form or uploading a file. |
## Examples demonstrate common rewriting scenarios
### Mark inspected pages with a modified title tag
**Goal:** Modify the `` tag of web pages to indicate SafeSquid inspected the content.
* **Applies to:** BODY
* **Mime type:** `text/html`
* **Profiles:** (blank — applies to all)
* **Pattern:** `<title>(.*?)`
* **Replace:** `Inspected by SafeSquid - \1`
SafeSquid buffers chunked responses to ensure the complete title tag is matched and replaced.
### Request PNG/JPG images instead of AVIF/WEBP
**Goal:** Modify the `Accept` header sent from the client so the remote server returns PNG or JPG images instead of AVIF or WEBP. AVIF images bypass SafeSquid's Image Analyser.
* **Applies to:** CLIENT
* **Mime type:** (blank — header rewriting, not body)
* **Pattern:** `(Accept:.*?)image/avif,?|image/webp,?`
* **Replace:** `\1`
SafeSquid strips the AVIF and WEBP entries from the Accept header, causing the server to fall back to PNG or JPG formats that the Image Analyser can inspect.
## Verification and evidence
* **Interface Checks**: In the [Configuration Portal](/architecture/interface/configuration_portal), confirm Content Modifier → Global is enabled. Verify each policy shows the correct Pattern, Replace, Mime type, and Applies to values.
* **Log Analysis**: Access logs should show connections matching the configured profiles and MIME types. Enable extended logging to confirm rewriting occurred on the expected connections.
* **Performance Validation**: Load a target page in the browser and inspect the page source (or response headers) to verify the expected modification. For body rewrites, view source to confirm substituted text. For header rewrites, use browser developer tools or SafeSquid logs.
**Next steps:** [Content Modifier overview](/use_cases/content_modifier/content_modifier) for prerequisites, implementation actions, and troubleshooting. [Header Obfuscation](/use_cases/header_rewrite/header_obfuscation) for header-specific filtering. [Cookie Inspection](/use_cases/cookie_inspection/cookie_inspection) for cookie-level policies.
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
* **[Content Modifier](/use_cases/content_modifier/content_modifier)** - configure SafeSquid's Content Modifier to dynamically alter HTML, headers, and data in real-time for security and custom web policies.
* **[Header Re-Write](/use_cases/header_rewrite/header_obfuscation)** - configure SafeSquid header filter to allow, deny, or insert HTTP headers for client-server communication control.
# ICAP Integration
Source: https://docs.safesquid.com/use_cases/integrations/icap
Configure ICAP protocol integration in SafeSquid for offloading content scanning to dedicated antivirus and DLP servers for enhanced threat detection.
# Offload Scanning Through ICAP Integration
## What is the advantage of using ICAP?
ICAP is a protocol designed to off-load specific Internet-based content to dedicated servers, thereby freeing up resources and standardizing the way in which features are implemented.
For example, a server that handles only language translation is inherently more efficient than any standard Web server performing many additional tasks.
ICAP concentrates on leveraging edge-based devices (proxies and caches) to help deliver value-added services. At the core of this process is a cache that will proxy all client transactions and will process them through ICAP Web servers.
These ICAP servers are focused on a specific function, for example, add insertion, virus scanning, content translation, language translation, or content filtering.
Off-loading value-added services from Web servers to ICAP servers allows those same web servers to be scaled according to raw HTTP throughput versus having to handle these extra tasks.
ICAP in its most basic form is a "lightweight" HTTP based remote procedure call protocol.
In other words, ICAP allows its clients to pass HTTP based (HTML) messages (Content) to ICAP servers for adaptation.
Adaptation refers to performing the value-added service (content manipulation) for the associated client request/response.
## How does ICAP work in SafeSquid?
The ICAP feature enables the proxy server to use an ICAP server to perform request modification, request satisfaction, or response modification to any request or response.
When enabled, what basically happens is this:
For request modification:
* client sends request to proxy server
* proxy server forwards request to the ICAP server, ICAP server will respond with a possibly modified request header
* proxy server will use that modified request header to process the request
This allows the ICAP server to do things like redirection, header filtering, etc.
For request satisfaction:
* client sends request to proxy server
* proxy server forwards request to ICAP server, ICAP server will respond with a *response* header and possibly a response body
* proxy server will pass that response header and body onto the client; the request will not be further processed
This allows the ICAP server to do things like URL blocking, etc.
For response modification:
* client sends request to proxy server
* proxy requests file from web server (or uses cached response). - proxy server forwards response header and body to ICAP server, ICAP server will respond with a possibly modified response header and body.
* proxy server will then send the possibly modified response header and body to the client
This allows the ICAP server to do things like virus scanning, content modification, block inappropriate content, etc.
When an ICAP server is installed with a caching system, every transaction is piped through the ICAP server, allowing the server to modify or redirect Web requests or responses.
When an ICAP server is installed in an FTP system, every transaction is piped through the ICAP server, allowing virus and content filtering
software to operate on the content.
## Enabling ICAP section on SafeSquid User Interface
## [Access the SafeSquid interface](/architecture/interface/configuration_portal)
Go to Configure Page
![Configure page in SafeSquid interface]()
Go to Real time content security
![Real-time content security section in sidebar]()
Go to ICAP Section
![ICAP section in Real-time content security]()
## Global
### Enabled
Enable or Disable this section.
TRUE: Enable ICAP interaction.
FALSE: Disable ICAP interaction.
![ICAP Global section]()
![ICAP Enabled toggle]()
![ICAP Global policy options]()
![ICAP configuration save]()
ICAP
![ICAP policies list with ADD icon]()
Create the ICAP policies here. Click on ADD icon to create a new policy.
### Enabled
Enable or Disable this Policy.
TRUE: Enable this entry.
FALSE: Disable this entry.
![ICAP policy form with Enabled, Comment, Profiles, Host, Port]()
### Comment
For documentation, and future references, explain the relevance of this entry with your policies.
That is, by reading the policies, a future user can understand the purpose of that entry.
### Profiles
Specify the Profiles applicable for this entry.
This entry will be applicable only if the connection has any one of the specified profiles.
Leave it Blank, to apply for all connections irrespective of any applied profile.
To avoid application to a connection that has a profile, use negated profile (!profile).
### ICAP Timeout
SafeSquid will timeout if the ICAP server does not respond within the specified ICAP Timeout.
### Host
The ICAP server hostname.
### File
The file to request from the ICAP server.
### Port
The ICAP server port.
### Applies to
REQUESTS: The ICAP server will be used to modify or satisfy requests.
RESPONSES: The ICAP server will be used to modify responses.
### Threat ID Header
ICAP server's response header that contains the loggable identification of the Detected Threat.
You can specify a comma-separated list of possible headers.
SafeSquid will use the first that is found in the response headers.
Example: X-Infection-Found, X-VIRUS-ID
### Quarantine
Preserve a local copy of the content sent to ICAP for processing.
ENABLED: Enable Quarantining.
DISABLED: Disable Quarantining.
### Include Request Headers in Response Quarantine
The Quarantined Response, will include the Request Headers, for co-relating responses with requests.
YES: Yes, Include the Request Headers, in the quarantined Responses.
NO: No, Do Not include the Request Headers, in the quarantined Responses.
### Quarantine Clean Data
Specify if Quarantine should be done for only when malware is detected.
YES: Quarantine Clean Files AND Infected Files.
NO: Quarantine Infected Files but DO NOT Quarantine Clean Files.
### Quarantine Root Folder
The folder that must be used to save the Quarantined Data.
Make sure that the Folder exists, and SafeSquid has Read / Write Permissions.
### Default Policies
SafeSquid comes with some default Inspection policies as follows.
Enable or Disable above policies as per the requirement or add new policy for new
requirement.
![ICAP default inspection policies list]()
## Verification and Evidence
* **Interface Checks**: In [Configuration Portal](/architecture/interface/configuration_portal), Real-time content security → ICAP: Global enabled, policy entries show correct ICAP server Host, Port, and File. Applies to (Requests/Responses) matches intent.
* **Log Analysis**: SafeSquid logs show ICAP request/response activity; timeouts or connection errors indicate unreachable ICAP server or wrong port/file.
* **Performance Validation**: Trigger a request that matches the ICAP policy. Verify the ICAP server receives the request and returns a valid response; content is modified or blocked per policy.
**Related**: [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection), [Malware Scanners](/use_cases/malware_scanning/malware_scanners), [Troubleshooting](/troubleshooting/troubleshooting)
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
* **[Malware Scanners](/use_cases/malware_scanning/malware_scanners)** - multi-layer malware detection in SafeSquid using SqScan, ClamAV, ICAP, and adaptable external parsers for threat prevention.
# Integrations
Source: https://docs.safesquid.com/use_cases/integrations/integrations
Enterprise integration with VPN for policy enforcement and secure remote access through SafeSquid SWG.
# Integrate SafeSquid with VPN for secure remote access
SafeSquid integrates with VPN infrastructure so policy enforcement extends to remote users and branch offices. For identity and authentication integration (Active Directory, OpenLDAP, SSO), see [Authentication](/use_cases/authentication/authentication) and [Directory Services](/use_cases/authentication/directory_services).
## Integration guides
### [VPN Integration](/use_cases/scaling_and_high_availability/vpn)
Remote users and branch offices need consistent web security policy enforcement across distributed infrastructure. VPN Integration enables SafeSquid to use WireGuard for encrypted tunnels and centralized policy enforcement. Secure remote access and consistent security posture result from this integration. Configure VPN integration through SafeSquid network settings using this document.
## Next steps
Combine with [Authentication](/use_cases/authentication/authentication) and [Access Restriction](/use_cases/access_restriction/access_restriction) for identity-based policy over VPN traffic.
# Clam Antivirus
Source: https://docs.safesquid.com/use_cases/malware_scanning/clamav_malware_scanning
Configure ClamAV in SafeSquid to detect and block viruses and malware at the gateway with profile-based policies.
# Scan content with ClamAV daemon at the gateway
ClamAV is an open-source antivirus toolkit. SafeSquid includes a client that sends content to a ClamAV daemon for scanning. Incoming content is scanned for viruses, worms, Trojans, and other malware before delivery; infected files are blocked at the gateway.
## Global
With this antivirus feature you can detect and block files containing viruses known to the ClamAV daemon scanner.
![Clamv.jpg]()
### Enabled
Enable or Disable ClamAV.
**TRUE:** Enable clamav section.
**FALS**E: Disable the clamav section.
### ClamAV hostname or Socket path
Specify the host on which the ClamAV daemon is running or the path to its local socket.
### ClamAV port
Specify the Port of ClamAV daemon.
Leave it blank if you are using a local socket. The default port will be 3310.
### Default template
You can send the name of the Template when this entry is matched.
Leave it blank for the Default template.
## ClamAV
![Clamv-policy.jpg]()
### Enabled
Enable or Disable this entry
**TRUE**: Enable this entry.
**FALSE**: Disable this entry.
### Comment
For documentation and future references, explain the relevance of this entry with your policies.
That is, by reading the policies, a future user can understand the purpose of that entry.
### Profiles
Specify the Profiles applicable for this entry.
This entry will be applicable only if the connection has any one of the specified profiles.
Leave it Blank, to apply for all connections irrespective of any applied profile.
To avoid application to a connection that has a profile, use a negated profile (!profile).
### Template
Specify the name of the template to send when this entry is matched.
## Next steps
* **[Malware Scanners](/use_cases/malware_scanning/malware_scanners)** - multi-layer malware detection in SafeSquid using SqScan, ClamAV, ICAP, and adaptable external parsers for threat prevention.
* **[SqScan](/use_cases/malware_scanning/sqscan)** - configure SqScan in SafeSquid for in-memory virus and malware scanning with granular policy levels.
# Malware Scanners
Source: https://docs.safesquid.com/use_cases/malware_scanning/malware_scanners
Multi-layer malware detection in SafeSquid using SqScan, ClamAV, ICAP, and adaptable external parsers for threat prevention.
# Multi-layer malware detection for web traffic
## Problem
Malware reaches endpoints through downloads and web content. Encrypted traffic hides payloads from passive inspection. Organizations need one or more scanning layers on the proxy with a clear integration path for external engines.
## Benefits
SafeSquid offers SqScan (built-in), ClamAV integration, ICAP to third-party scanners, and an Adaptable External Parser for custom logic. Administrators pick layers that match operational maturity and vendor standards. **Confirmed:** HTTPS payloads require [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) for scanning to apply to encrypted web traffic.
## Advantages
**Confirmed:** Multiple scanner integrations (SqScan, ClamAV, ICAP, external parser) ship in the documented module set. Administrators can stack engines rather than rely on a single signature source.
**Draft (CTO confirmation):** Detection rates versus cloud-only SWG sandboxes vary by threat type and update cadence—avoid numeric superiority claims without lab evidence in the source register.
## Call to action
Enable [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection). Configure at least one scanner using the guides below. Validate with known-safe and test-malware samples per organizational policy, then monitor logs and alerts.
## Malware scanner configuration and reference guides
### [SqScan](/use_cases/malware_scanning/sqscan)
Built-in scanning alone may not cover all threat signatures or formats. SqScan is SafeSquid's built-in module for scanning HTTP and HTTPS traffic for viruses, Trojans, and malware. It provides a first layer of protection without external daemons. Configure and use SqScan for HTTP and HTTPS scanning using this document.
### [ClamAV Malware Scanning](/use_cases/malware_scanning/clamav_malware_scanning)
Enterprises need an extra layer of detection using a widely updated signature engine. ClamAV integration allows SafeSquid to send content to a ClamAV daemon for scanning. Multiple file formats and archives are supported. Integrate a dedicated ClamAV server with SafeSquid using this document.
### [ICAP](/use_cases/integrations/icap)
Organizations use third-party ICAP antivirus or content adaptation services for policy. ICAP integration lets SafeSquid send HTTP/HTTPS content to ICAP servers for virus scanning and content modification. Dr. Web, Kaspersky, Symantec, and Trend Micro are examples of ICAP-based solutions. Configure ICAP server connections using this document.
### [Adaptable External Parser](/use_cases/data_leakage_prevention/adaptable_external_parser)
Custom or proprietary scanners may require a flexible integration pattern. The Adaptable External Parser allows SafeSquid to invoke external scanning or parsing logic for content. This supports integration with non-ICAP or custom antivirus and DLP tools. Use this document to configure and integrate external parsers.
## Next steps
Enable [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) so HTTPS traffic is scanned; combine with [Data Leakage Prevention](/use_cases/data_leakage_prevention/data_leakage_prevention) for upload/download inspection.
# Malware Signatures via Self-Service Portal
Source: https://docs.safesquid.com/use_cases/malware_scanning/malware_signatures
Manage malware signatures via SafeSquid Self-Service Portal to enhance threat intelligence.
# Manage Malware Signatures in the Self-Service Portal
You can manage malware signatures using the SafeSquid Self-Service Portal. This allows you to add custom signatures to block specific threats.
You need an active SafeSquid account with at least one activation key. Register at [https://key.safesquid.com/](https://key.safesquid.com/) if needed. Log in to the Self-Service Portal at [https://key.safesquid.com/](https://key.safesquid.com/).
![Select manage signatures option to Manage Malware Signatures using Self Service portal (https://key.safesquid.com/)]()
![Click on Add to add New signature using Self Service portal]()
![Fill up signature name and keywords to manage malware signatures using self service portal]()
![Click on submit to save the signature to manage malware signatures using self service portal]()
![Newly added signature can be view after click on submit to save the signature]()
To know more about this feature follow link [Block Emails or Files including archives or Social Posts using Keywords](/use_cases/data_leakage_prevention/block_emails_or_files_including_archives_or_social_posts_using_keywords)
## Next steps
* **[Block Emails or Files including Archives or Social Posts using Keywords](/use_cases/data_leakage_prevention/block_emails_or_files_including_archives_or_social_posts_using_keywords)** - block emails, files, archives, and social posts by keyword in SafeSquid for data leakage protection.
# Native Sandboxing
Source: https://docs.safesquid.com/use_cases/malware_scanning/native_sandboxing
Use SafeSquid's native sandboxing capabilities to isolate and inspect suspicious web content.
## Problem
Security teams need predictable control over app and web usage to reduce policy bypass and data-risk exposure.
## Benefits
You can enforce policy decisions consistently with SafeSquid while preserving legitimate business workflows.
## Advantages
You keep actionable policy control close to operations, with verifiable outcomes in logs and policy behavior.
## Call to action
Use the steps in this guide to implement the control, then validate behavior with a real user-flow test.
# Isolate Suspicious Content With Native Sandboxing
> 🚧 **This page is under construction.** Content coming soon.
## Isolate and inspect suspicious content before delivery
SafeSquid's native sandboxing provides built-in isolation for inspecting suspicious web content before it reaches end users. This page will cover enabling the feature, configuring sandbox boundaries, and verifying isolated execution.
## Next steps
* **[Malware Scanners](/use_cases/malware_scanning/malware_scanners)** - multi-layer malware detection in SafeSquid using SqScan, ClamAV, ICAP, and adaptable external parsers for threat prevention.
* **[Threat Intelligence Feeds](/use_cases/malware_scanning/threat_intelligence_feeds)** - real-time cloud-integrated threat intelligence for web categorization, application identification, SSL security, and malware scanning in SafeSquid SWG.
# SqScan
Source: https://docs.safesquid.com/use_cases/malware_scanning/sqscan
Configure SqScan in SafeSquid for in-memory virus and malware scanning with granular policy levels.
# Built-in malware and virus scanning with SqScan
SqScan is SafeSquid's built-in module for scanning traffic for viruses and malware. Browsing certain sites can expose users to malware and reduce performance. SqScan scans requested content and blocks access and downloads from infected or malicious sources.
## Virus scanning policies
## Enabling SqScan section on SafeSquid User Interface
## [Access the SafeSquid interface](/architecture/interface/configuration_portal)
## Go to Configure Page
![Goto configure.webp]()
## Go to Real-time content security
![Go to real time content security.webp]()
## Go to SqScan Section
![SvScanconfigureSlide1 (1).webp]()
## Global
### Enabled
Enable or Disable this section.
* **TRUE**: Enable in-memory virus scanning
* **FALSE**: Disable in-memory virus scanning
![SvScanconfigureSlide1 (2).webp]()
![SvScanconfigureSlide1 (3).webp]()
![SvScanconfigureSlide1 (4).webp]()
## Virus Scanning Policies
Create the entries for SqScan.
Define the Security level and Malware type in each entry.
ALL the Following Entries will be tested from top to bottom.
![SvScanconfigureSlide1 (5).webp]()
Create the entries for SqScan.
Define the Security level and Malware type in each entry.
![Svscan-policy.jpg]()
### Enabled
Enable or Disable the SqScan Policy.
**TRUE:** Enable this entry.
**FALSE**: Disable this entry.
### Comment
For documentation and future references, explain the relevance of this entry with your policies.
That is, by reading the policies, a future user can understand the purpose of that entry.
### Profiles
Specify the Profiles applicable for this entry.
This entry will be applicable only if the connection has any one of the specified profiles.
Leave it Blank, to apply for all connections irrespective of any applied profile.
To avoid application to a connection that has a profile, use a negated profile (!profile).
### Malware Security Level
Select a security level depending on your requirements.
Set security level as per your safety measures: standard or High or Paranoid.
Set the scan level to bypass or disable the scanning.
* **BYPASS**: Disable Virus Scanning for the matching Profiles
* **STANDARD**: Block if a threat is detected, but not on mere suspicion
* **HIGH**: Block if a threat is detected, even if the content is suspicious
* **PARANOID**: Block everything that SqScan cannot ensure is clean. Warning! This can cause all content to be blocked even in the event of any systemic failures of this functionality.
### Malware Types
Select Virus/Malware type(s) to be blocked, if received content has their signature(s).
SafeSquid will block all such requests if a threat is detected or if the content is suspicious.
* **VIRUS**: Enable Security Against VIRUS threats
* **SPYWARE**: Enable Security Against SPYWARE threats
* **ADWARE**: Enable Security Against ADWARE threats
* **SPAM:** Enable Security Against SPAM threats
* **ROOTKIT**: Enable Security Against ROOTKIT threats
* **DIALER**: Enable Security Against DIALER threats
* **MALICIOUS\_APP:** Enable Security Against MALICIOUS\_APP threats
* **ARCHBOMB**: Enable Security Against ARCHBOMB threats
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Threat Intelligence Feeds
Source: https://docs.safesquid.com/use_cases/malware_scanning/threat_intelligence_feeds
Real-time cloud-integrated threat intelligence for web categorization, application identification, SSL security, and malware scanning in SafeSquid SWG.
# Cloud threat intelligence keeps enforcement current
Static blocklists and outdated signatures create blind spots that attackers exploit within hours of a new campaign. SafeSquid's cloud-integrated threat intelligence delivers real-time updates to web categorization, application signatures, SSL security, image analysis, malware scanning, and geo-location databases. Feed refresh timestamps and category versions appear in the SafeSquid interface and logs; audit reports confirm current threat posture.
## Outdated threat data creates exploitable gaps
Threat actors register and rotate domains, change hosting infrastructure, and modify payloads faster than manual updates can track. Enterprises relying on static blocklists or weekly feed refreshes face a window of exposure measured in hours. Compliance frameworks (NIST SP 800-53 SI-5, ISO 27001 A.12.2.1) require timely threat intelligence to maintain control effectiveness.
SafeSquid addresses this with automatic, cloud-backed feed updates that keep enforcement aligned with the latest threat landscape.
## Feeds cover categorization, signatures, and reputation
SafeSquid cloud services deliver real-time updates across eight named intelligence feeds:
| Feed | Purpose | Used by |
| - | - | - |
| **Threat Intelligence** | Known malicious servers and exploit-serving destinations | [Access Restriction](/use_cases/access_restriction/access_restriction), [DNS\_Security](/use_cases/dns_security/dns_security) |
| **URL Classification** | URL and domain classification into categories | [Web Categorization](/getting_started/core_features/web_categorization), [Access Restriction](/use_cases/access_restriction/access_restriction) |
| **Application Identification** | Application and SaaS recognition by traffic characteristics | [Architecture](/architecture/overview/safesquid_swg) |
| **Image Analysis AI** | Visual-content and image-based risk classification | [Image\_Analyser\_AI](/use_cases/data_leakage_prevention/image_analyser_ai) |
| **Content Fingerprints** | MiMe and content-nature detection for data classification | [True-Mime\_Fingerprints](/use_cases/data_leakage_prevention/true_mime_fingerprints) |
| **Malware Signatures** | Malware signature and heuristic updates | [Malware\_Scanners](/use_cases/malware_scanning/malware_scanners) |
| **Geo-Location** | Geographic location of web-server hosts | [GeoIP](/use_cases/dns_security/geoip) |
| **SSL Updates** | Trusted Root CA, algorithm, and fingerprint updates for SSL trust evaluation | [SSL\_Inspection](/use_cases/ssl_inspection/ssl_inspection) |
Feed delivery and refresh schedules are managed by the SafeSquid cloud service. SafeSquid instances pull updates automatically when connected to the cloud. Custom categorization overrides (managed via the [Self-Service Portal](/architecture/interface/self_service_portal)) merge with cloud feeds on each refresh.
Internal product knowledge describes the feed-consumption mechanism as **Zero Threat Window**, where updated intelligence is injected directly into the processing pipeline so policy decisions use current data without waiting for a slower manual refresh cycle.
## Prerequisites
* **SafeSquid activation**: A valid product activation key from [key.safesquid.com](https://key.safesquid.com). The activation key links the instance to the cloud feed service.
* **Internet connectivity**: SafeSquid must reach the SafeSquid cloud endpoints for feed updates. Restricted environments should explicitly allowlist the required update and categorisation endpoints.
* **Subscription**: Some feed categories (e.g. DLP signatures, advanced application signatures) require a premium subscription. Check the [Self-Service Portal](/architecture/interface/self_service_portal) for active subscriptions.
## Verification and evidence
* **Interface Checks**: In the [Configuration Portal](/architecture/interface/configuration_portal), check the Support page for feed version numbers and last-update timestamps. Web Categorization, Application Signatures, and malware databases each show their current version.
* **Log Analysis**: SafeSquid logs feed update events including success, failure, and version changes. Search logs for feed-related entries to confirm refresh frequency.
* **Custom Categorization**: Verify custom categories created in the Self-Service Portal appear in SafeSquid's categorization engine after the next feed sync. Test by browsing a custom-categorized URL and checking the access log for the expected category.
## Troubleshooting
**Symptom:** Categorization or application detection becomes stale.\
**Likely cause:** Feed update path is blocked or the instance is not correctly linked to the cloud service.\
**Isolation:** Check update timestamps, feed-related logs, and activation status.\
**Remediation:** Restore connectivity to the required endpoints and confirm licensing state.\
**Retest:** Wait for refresh and verify the version updates.
**Symptom:** Custom categorization never appears on the proxy.\
**Likely cause:** The portal-side change is not linked to the active deployment context or sync path.\
**Isolation:** Compare the activation key and portal configuration with the running instance.\
**Remediation:** Correct the activation and synchronization state.\
**Retest:** Reapply the custom category and confirm it appears after sync.
## Next steps
* [Web Categorization](/getting_started/core_features/web_categorization) to configure category-based policies.
* [DNS Security](/use_cases/dns_security/dns_security) for DNSBL, GeoIP, and homograph detection.
* [Malware Scanners](/use_cases/malware_scanning/malware_scanners) for ClamAV, ICAP, and SqScan configuration.
* [Self-Service Portal](/architecture/interface/self_service_portal) to manage custom categorization and subscriptions.
# Caching and Prefetching
Source: https://docs.safesquid.com/use_cases/performance_acceleration/caching
Configure SafeSquid content caching and prefetching to cut bandwidth and latency, and verify objects are actually being served from the local store.
# Serve Repeated Requests Locally
Every request that reaches the origin costs bandwidth and latency the user feels. Caching stores local copies of requested content and serves later requests from disk. Prefetching goes further and retrieves resources referenced in an HTML page before the user asks for them.
They are complementary, and they are configured separately. Caching is the store; prefetching is what fills it ahead of demand.
## Choose which to enable
| | Content caching | Prefetching |
| - | - | - |
| What it stores | Pages and files that were requested | Resources referenced in HTML, before they are requested |
| Best for | Repeated access to the same content across users | Pages with many embedded assets |
| Main cost | Disk on the write path | Origin requests for resources nobody opens |
| Depends on | A store policy and a matching access profile | Caching being configured first |
Enable caching first and confirm objects land in the store. Prefetching without a working cache generates origin traffic and discards it.
Cache and prefetch policy interacts with inspection and privacy scope. Do not cache content from destinations excluded from inspection, or from categories where a shared local copy would expose one user's content to another. Confirm the scope with the policy owner before enabling either.
## Configure content caching
### Create the access policy
1. Access the [SafeSquid User Interface](/architecture/interface/configuration_portal) and click **Configure**.
![Configure page]()
2. Navigate to **Access Profiles** under Restriction Policies.
![Access Profiles section]()
3. Click **Add New** to create a new policy.
![Add new policy]()
4. Enter a descriptive comment for reference.
![Policy comment]()
5. Select the desired categories from the **Categories** dropdown.
![Select categories]()
6. Set **Action** to **Allow**.
![Set action]()
7. Assign a unique name in **Added Profiles**.
![Added Profiles]()
8. Click **Save Policy**.
![Save policy]()
### Configure the caching store
9. Navigate to **Caching**, under **Accelerators** in Application Setup.
![Caching section]()
10. On the **Global** tab, confirm **Enabled** is set to `TRUE` — Caching, like Prefetching, only
takes effect once its own Global switch is on, separate from any individual Store entry's own
Enabled field.
11. Click the **Store** tab.
![Store tab]()
12. Click **Clone it** to duplicate an existing policy.
![Clone policy]()
![Duplicated policy]()
13. Click **Edit Policies** on the cloned entry.
![Edit policy]()
14. Set **Enabled** to **True**.
![Enable policy]()
15. Add an appropriate comment for future reference.
![Policy comment]()
16. Select the profile created earlier from the **Profiles** dropdown.
![Select profile]()
17. Click **Save Policy**.
![Save caching policy]()
18. Click **Save Config** to apply the configuration globally.
![Global save]()
## Configure prefetching
Prefetching fetches and caches files referenced in HTML before the user requests them. It applies to a wider set of resources than caching alone.
1. Access the [SafeSquid User Interface](/architecture/interface/configuration_portal) and click **Configure**.
![Configure page]()
2. Navigate to **Prefetching**, under **Accelerators** in Application Setup.
![Prefetching section]()
3. Ensure the **Global** section has **Enabled** set to **True**.
![Global enabled]()
4. Click the **Prefetch** tab.
![Prefetch tab]()
5. Click **Add New** to create a new policy.
![Add new policy]()
6. Enter an appropriate comment for future reference.
![Policy comment]()
7. Specify the HTML tag to analyze for prefetchable URLs.
![HTML tag specification]()
8. Specify the attribute of the HTML tag holding the URL to prefetch.
![Tag attribute]()
9. Specify the regular expression to evaluate discovered URLs in the tag attribute.
![URL regex]()
10. Click **Save Policy**.
![Save policy]()
11. Click **Save Config** to apply the configuration.
![Save config]()
![Prefetch queue debug log]()
Keep the regular expression narrow. A broad pattern prefetches every URL the tag attribute can hold, which turns a latency optimisation into an origin-traffic multiplier.
## Verify objects are cached
1. Navigate to **Manage cached objects** in the Caching section.
![Manage cached objects]()
2. Verify cached websites appear under disk cache.
![Disk cache contents]()
Expected result: content from the categories in the access profile appears in the disk cache after a client requests it.
An empty store after browsing means the access profile is not matching, or the store policy is not enabled. Check the profile name in both places before adjusting cache size.
## Capture caching evidence
Store these artifacts with the change record:
* The access profile name and the categories it matches.
* Confirmation that the store policy references that same profile.
* A **Manage cached objects** listing showing entries after a test browse.
* The prefetch tag, attribute, and regular expression used.
* Confirmation from the policy owner that cached categories are appropriate to share.
## Troubleshoot caching and prefetching
| Symptom | Likely cause | Fix |
| - | - | - |
| Disk cache stays empty | Store policy is not enabled, or references the wrong profile | Confirm **Enabled** is `True` and the profile name matches the access policy exactly |
| Cache fills but hit rate stays low | Categories cached do not match what users request | Re-scope the access profile to the categories actually in demand |
| Origin traffic rises after enabling prefetch | Regular expression is too broad | Narrow the pattern; prefetching every matched URL costs more than it saves |
| Users see another user's content | Cached content from a personalised or authenticated destination | Exclude those categories from the store policy immediately |
| Disk I/O wait rises sharply | Cache on a SATA-attached volume | Move the cache path to NVMe; see [Hardware Sizing](/deployment/hardware_sizing) |
## Next steps
* [Manage Bandwidth](/use_cases/performance_acceleration/manage_bandwidth) - shape traffic once caching is in place.
* [Performance Plot](/use_cases/performance_acceleration/performance_plot) - measure the effect on latency.
* [Hardware Sizing](/deployment/hardware_sizing) - confirm the cache volume is on the right storage.
# Bandwidth Management
Source: https://docs.safesquid.com/use_cases/performance_acceleration/manage_bandwidth
Control download speed, max download size, and upload size per user with SafeSquid Limits for bandwidth and data-handling policies.
# Control download speed and size per user with Limits
Use SafeSquid Limits to set download speed and maximum download or upload size per user. Configure limits in **Configure → Restriction Policies → Speed Limits** and attach to profiles.
## Prerequisites
When downloading files from HTTPS websites, ensure that [HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection) in SafeSquid is enabled
### Setup Download Rate
![clicking on edit policies and editing the first entry in speed limits section]()
![selecting true from the drop down menu]()
![setting the download rate as 10kb as an example in download rate field]()
### Testing Download Rate
![testing the download rate by downloading a file]()
## Setup Maximum limit on the Download size
This can be achieved using SafeSquid limits feature, the interface provides an option to set up the limit on the Download size for users.
### Prerequisites
When downloading files from HTTPS websites, ensure that [HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection) in SafeSquid is enabled
### Setup Maximum Download Size
![Edit second entry in policy under Configuration Section to Setup Maximum limit on the Download size]()
![Enabled second entry as True in policy under Configuration Section to Setup Maximum limit on the Download size]()
![Save policy under Configuration Section to Setup Maximum limit on the Download size]()
### Testing Maximum Download Limit
![Testing of policy that set maximum limit on Download size]()
## Setup Maximum limit on the Upload size
This can be achieved using SafeSquid limits feature, the interface provides an option to set up the limit on the Download size for users.
### Prerequisites
When downloading files from HTTPS websites, ensure that [HTTPS Inspection](/use_cases/ssl_inspection/ssl_inspection) in SafeSquid is enabled
### Setup Maximum Upload Size
![Setup Maximum limit on the Upload size in Speed Limits section]()
### Testing Upload Limit
Here I am selecting the file to Upload
![Select the file to Upload to check Maximum limit on the Upload size]()
![Select the file to Upload to check Maximum limit on the Upload size]()
When I click on upload, I will get the below error, Because I am uploading 4MB file. But I have maximum upload limit of 2MB
![Error template of Maximum limit on the Upload size]()
## Next steps
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
# Performance Accelerators
Source: https://docs.safesquid.com/use_cases/performance_acceleration/performance_accelerators
Use SafeSquid performance accelerators such as caching, prefetching, bandwidth management, speed limits, and WCCP with deployment-aware expectations.
# Improve performance without losing control
## Problem statement
Enterprises need better web performance, but acceleration features can create risk when they are deployed without clear intent. A cache that serves the wrong content, a prefetch rule that creates unnecessary traffic, or a transparent-routing feature that is misunderstood can turn performance tuning into an operations problem.
## Client scenario
Use these guides when you need to:
* reduce repeated bandwidth consumption
* improve perceived user response time
* control upload or download pressure
* deploy transparent traffic steering with router integration
## Key benefits
SafeSquid performance accelerators help operators improve efficiency while keeping the proxy in the control path. They are most effective when used deliberately and validated with performance plots, logs, and production-safe rollout steps.
## Prerequisites
### Client-side preparations
* Identify whether the problem is latency, bandwidth contention, repeated downloads, or transparent-redirection design.
* Gather a baseline before changing acceleration features.
### SafeSquid-side setup
* Confirm the deployment topology can support the accelerator you plan to enable.
* Validate each feature separately instead of enabling several acceleration paths at once.
## Performance accelerator guides
### [Caching](/use_cases/performance_acceleration/caching)
Use caching when repeated requests for the same web objects waste bandwidth and increase user wait time. Caching can reduce origin fetches and improve response times. But it should be validated against content freshness requirements and application behavior.
### [Pre Fetching](/configuration/application_setup/accelerators/prefetching)
Use prefetching when perceived latency is driven by predictable follow-on requests. Prefetching can improve browsing responsiveness. But it must be monitored carefully so the proxy does not fetch unnecessary content that provides little operational value.
### [Manage Bandwidth](/use_cases/performance_acceleration/manage_bandwidth)
Use bandwidth management when a few users, services, or content types consume disproportionate capacity. This is the right control for policy-driven allocation, not just raw speed optimization.
### [Speed Limits](/configuration/restriction_policies/speed_limits)
Use speed limits when you need per-user, per-group, or per-content caps to protect shared capacity. This is especially useful when fairness and congestion control matter more than maximum download speed.
### [WCCP](/use_cases/scaling_and_high_availability/wccp)
Use WCCP when the deployment requires router-driven traffic redirection and transparent proxy integration. WCCP is an architecture-sensitive feature and should be validated carefully with topology, failover, and traffic-path testing.
## Verification and validation
### Positive tests
For each accelerator you enable:
* record a before state
* enable one feature at a time
* test the target workflow again
Expected result:
* the intended metric improves
* unrelated traffic behavior remains stable
* logs and performance plots reflect the change window clearly
### Negative tests
Check a workflow that should not be affected by the accelerator.
Expected result:
* the optimization does not create a new application failure
* the feature remains scoped to the problem it was meant to solve
## Troubleshooting guide
### Performance improves for some users but breaks specific workflows
Likely causes:
* the accelerator is too broad
* the application is sensitive to caching, prefetching, or redirection behavior
Isolation steps:
* identify which exact feature changed
* compare the affected workflow against the intended scope
Remediation:
* narrow the feature scope
* disable the last change if needed
* retest with the affected application
### Capacity data remains unclear after tuning
Likely causes:
* too many changes were made at once
* no baseline was captured
Isolation steps:
* correlate the change window with performance plots and logs
* separate the effects of each accelerator
Remediation:
* roll forward one change at a time
* capture a fresh baseline and compare again
## Related controls / next steps
* Use [Performance Plot](/use_cases/performance_acceleration/performance_plot) to validate whether an accelerator actually improved the right metric.
* Use [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) when the problem is scale-out resilience rather than optimization on one node.
* Use [Transparent Proxy](/use_cases/scaling_and_high_availability/transparent_proxy) and [WCCP](/use_cases/scaling_and_high_availability/wccp) for topology-sensitive transparent deployment design.
# Performance Plot
Source: https://docs.safesquid.com/use_cases/performance_acceleration/performance_plot
Generate SafeSquid performance plots to investigate load, capacity, and timing issues with evidence that supports troubleshooting and operations review.
# Turn performance data into operating evidence
## Problem statement
When a team reports slowness, instability, or unexplained capacity pressure, screenshots of the dashboard are not enough. Operators need a time-bounded view of performance behavior so they can correlate complaints with actual load and investigate the correct incident window.
## Client scenario
Use Performance Plot when you need to:
* inspect SafeSquid load during a specific incident window
* compare current behavior with expected performance trends
* gather evidence for capacity review or escalation
* preserve a visual record of performance before and after a change
## Key benefits
Performance plots help operations teams move from vague complaints to measurable time-based evidence. They are especially useful during incident review, change validation, and capacity planning discussions.
## Prerequisites
### Client-side preparations
* Know the approximate time window of the event you are investigating.
* Confirm the issue really occurred through the SafeSquid path you want to analyze.
### SafeSquid-side setup
* Ensure the Support interface is accessible.
* Confirm the underlying performance logging path is active.
## Setup instructions
### Open the performance plot tool
Access the [Configuration Portal](/architecture/interface/configuration_portal), then open **Support** and select the **Performance Plot** tile.
### Select the right time range
Choose the time range that matches the incident or observation window. If the issue lasted only a short period, use a tight time range first.
This reduces noise and makes the plot easier to interpret.
### Generate the plot
Run the plot generation action from the interface after selecting the desired window.
![Select Support to Generate Performance Plot from SafeSquid User Interface]()
![Select Time Range to Generate Performance Plot from SafeSquid User Interface]()
![Select Date Range for Custom Time to Generate Performance Plot from SafeSquid User Interface]()
![Select Generate to Create a Performance Plot from SafeSquid User Interface]()
![Generated Performance Plot in SafeSquid User Interface]()
### Save the generated evidence
Save the plot when it captures a useful incident or baseline window.
![Save Generated Performance Plot from SafeSquid User Interface]()
This helps with later comparison, escalation, and post-incident review.
## Verification and validation
### Positive test
Generate a plot for a known busy period.
Expected result:
* the plot renders successfully
* the chosen time window matches the requested period
* the output is usable for operational review
### Negative test
Generate a plot for a quiet period or a very narrow window with little traffic.
Expected result:
* the plot still renders
* low activity is visible as low activity, not as a tool failure
### Evidence to retain
* the selected time range
* the saved plot file
* any related incident ticket or change reference
## Troubleshooting guide
### The plot does not generate
Likely causes:
* the plotting dependency or script path is broken
* the selected range has a tooling or data issue
Isolation steps:
* compare the behavior against the dedicated troubleshooting runbook
* verify whether other support functions work normally
Remediation:
* use [Troubleshooting](/troubleshooting/troubleshooting)
* retest with a known-good date range
### The plot generates but is not useful
Likely causes:
* the time range is too broad
* the incident window is wrong
* the operator is using the plot without corresponding log context
Isolation steps:
* rerun the plot for a tighter window
* compare the time window against user reports and logs
Remediation:
* narrow the range
* correlate with [Security Logs](/use_cases/audit_and_forensics/security_logs) and [Reporting Module](/use_cases/audit_and_forensics/reporting_module)
## Related controls / next steps
* Use [Troubleshooting](/troubleshooting/troubleshooting) if the plotting workflow fails.
* Use [Reporting Module](/use_cases/audit_and_forensics/reporting_module) for transaction-level evidence alongside the performance view.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) when you need exact event correlation rather than only trend visualization.
# Speed Limits
Source: https://docs.safesquid.com/use_cases/performance_acceleration/speed_limits
Configure connection speed limits in SafeSquid to control per-user or per-group bandwidth consumption.
# Control Bandwidth With Speed Limits
> 🚧 **This page is under construction.** Content coming soon.
## Control per-user or per-group download and upload speed
Speed Limits let administrators cap download and upload speeds for users, groups, or content types. Configure speed limit policies in the Configuration Portal and attach them to profiles. For related traffic control, see [Bandwidth Management](/use_cases/performance_acceleration/manage_bandwidth).
# Application Signatures
Source: https://docs.safesquid.com/use_cases/profiling_engine/application_signatures
Application Signatures reference and operational guidance for SafeSquid SWG administrators.
You need an active SafeSquid account with at least one activation key. Register at [https://key.safesquid.com/](https://key.safesquid.com/) if needed. Log in to the Self-Service Portal at [https://key.safesquid.com/](https://key.safesquid.com/).
![Select manage signatures option to Manage Keyword Signatures using Self Service portal (https://key.safesquid.com/)]()
![Click on Add to add New signature using Self Service portal]()
![Fill up signature name and keywords to manage keyword signatures using self service portal]()
![Click on submit to save the signature to manage keyword signatures using self service portal]()
![Newly added signature can be view after click on submit to save the signature]()
To know more about this feature follow link [Block Emails or Files including archives or Social Posts using Keywords](/use_cases/data_leakage_prevention/block_emails_or_files_including_archives_or_social_posts_using_keywords)
## Adding users using SafeSquid interface for authentication
When no Active Directory (AD) server is available for SafeSquid LDAP, administrators can authenticate users by assigning usernames and passwords via the SafeSquid interface.
![clicking on configure in SafeSquid interface]()
![click on search in access profiles]()
![Application Signatures or user list in SafeSquid interface]()
![Application Signatures add or edit entry]()
![Application Signatures policy form]()
![Application Signatures save or submit]()
![Application Signatures list with new entry]()
![Application Signatures configuration applied]()
## Next steps
* Use [Request Profiles](/use_cases/profiling_engine/request_profiles) to match application traffic.
* Use [Access Restriction](/use_cases/access_restriction/access_restriction) to enforce application policy.
# Profiling Engine
Source: https://docs.safesquid.com/use_cases/profiling_engine/profiling_engine
Stop guessing who's doing what — profile every HTTP request by identity, application, content, and time for Zero Trust web security.
# Stop Guessing Who's Doing What — Profile Every Request
Your proxy sees thousands of requests per second: `https://cdn47.cloudprovider.com/a8f3d2e1`. Is that:
* Your CEO downloading an M\&A contract? (Allow)
* A contractor uploading customer data to personal Dropbox? (Block + alert)
* Malware calling home, disguised as a CDN request? (Quarantine)
**Without profiling, every request is a mystery box.** You're forced to choose: block everything (users revolt) or allow everything (breaches happen).
**SafeSquid Profiling Engine solves this.** Every request is classified by:
* **Who:** User identity (LDAP, AD, SAML) + group membership
* **What:** Application signature (Zoom vs Tor vs ransomware C2)
* **When:** Time of day, day of week (lunch hour vs 2 AM)
* **Content:** MIME type, file extension, payload patterns (`.exe` pretending to be `.pdf`)
**Outcome:** Policies that match reality, not guesswork.
## Why Identity-Based Profiling Matters
**The anonymous insider problem:** When your proxy sees only IP addresses, a stolen laptop becomes indistinguishable from the CEO. A contractor on the guest network can exfiltrate the same data as a trusted admin. Without user identity, every security policy is a blunt instrument—block everyone or trust everyone.
**The encrypted application problem:** 90% of web traffic is HTTPS. TeamViewer, Tor Browser, Dropbox, and ransomware C2 servers all look the same to a firewall: encrypted TCP connections to cloud IPs. URL filtering fails because apps use CDN domains that rotate hourly.
**The timing problem:** Legitimate business use during work hours becomes data theft at 2 AM. Social media during lunch is acceptable; during client meetings, it's a distraction. Time-agnostic policies create false positives (blocking legitimate use) or false negatives (missing after-hours exfiltration).
**SafeSquid Profiling Engine solves all three:** Tie every HTTP request to a user and group. Detect applications by traffic fingerprints (TLS SNI, headers, payload patterns). Apply policies by time window. Inspect content for MIME type spoofing and payload threats.
**Result:** Granular Zero Trust policies like:
* **Finance team:** Full access to banking sites, block file upload to personal cloud storage
* **Contractors:** Block remote desktop apps (TeamViewer, AnyDesk), allow business SaaS
* **After-hours access:** Block all uploads >10MB, require manager approval for exceptions
* **Executives:** Bypass inspection for encrypted M\&A discussions (specific domains only)
## What You Can Do with Profiling
✅ **Enforce Zero Trust policies:** Contractors can't access finance systems, even on the corporate network\
✅ **Block shadow IT:** Detect Dropbox, Telegram, Tor — even over HTTPS\
✅ **Stop data leaks:** SSN, credit cards, PHI detected in uploads → blocked before leaving the network\
✅ **Time-based access:** Social media allowed during lunch, blocked during work hours\
✅ **Detect disguised threats:** Files claiming to be PDFs but actually executables → quarantined\
✅ **Application control:** Allow Zoom for meetings, block Discord for unapproved chat
## How to Configure Profiling
### 1. [User Identities](/use_cases/authentication/user_identities) — Connect LDAP/AD, Create Groups
**Your goal:** Tie every HTTP request to a user and group (Finance, IT, Contractors) so policies apply by identity, not just IP address.
**What you'll configure:**
* LDAP or Active Directory connection for user authentication
* User groups (e.g., Finance, IT, Contractors, Executives)
* Group membership rules (manual or LDAP attribute-based)
**When to use:** Required for any identity-based policy. If you only use IP-based rules, you can't distinguish between a CEO and a stolen laptop.
**⚠️ Common pitfall:** Don't rely on IP addresses for identity. Laptops roam, NAT pools rotate, VPNs mask IPs. Use user authentication (LDAP/SAML) or accept that your policies will break constantly.
→ [Configure User Identities](/use_cases/authentication/user_identities)
***
### 2. [Web Categorization](/getting_started/core_features/web_categorization) — Assign Sites to Categories
**Your goal:** Block or allow websites by category (Social Media, Productivity, Malware, Adult Content) rather than maintaining endless URL lists.
**What you'll configure:**
* Built-in category database (YouTube = "Streaming Media", Facebook = "Social Networking")
* Custom categories for your organization (e.g., "Approved SaaS", "Competitor Sites")
* Category overrides (add specific domains to categories)
**When to use:**
* ✅ Block broad categories (Social Media, Gaming, Adult Content) during work hours
* ✅ Allow only approved categories (Business, Productivity, Cloud Storage)
* ✅ Custom rules (allow LinkedIn for Sales team, block for everyone else)
**⚠️ Common pitfall:** Don't block "Cloud Storage" category without whitelisting your approved services (SharePoint, OneDrive). You'll break business workflows.
→ [Configure Web Categorization](/getting_started/core_features/web_categorization)
***
### 3. [Architecture](/architecture/overview/safesquid_swg) — Detect Apps by Traffic Fingerprints
**Your goal:** Block (or allow) specific apps even when they use HTTPS or non-standard ports: TeamViewer, Tor Browser, Dropbox, Discord, Zoom.
**What you'll configure:**
* Keyword signatures (TLS SNI, HTTP headers, payload patterns)
* Application detection rules (match app by traffic fingerprint)
* Per-app policies (block TeamViewer for contractors, allow for IT)
**When to use:**
* ✅ Block remote access tools (TeamViewer, AnyDesk) to prevent shadow IT
* ✅ Detect anonymization tools (Tor, Psiphon) to prevent policy bypass
* ✅ Allow Zoom/Teams, block Discord/Telegram (unapproved chat)
**Examples:**
* Block **TeamViewer** and **AnyDesk** for contractors, allow for IT staff
* Detect **Tor Browser** (anonymization) to prevent policy circumvention
* Allow **Zoom** and **Teams** but block **Discord** and **Telegram** (unapproved chat apps)
→ [Review the architecture guides](/architecture/overview/safesquid_swg)
***
### 4. [Content Analyser](/use_cases/data_leakage_prevention/content_analyser) — Inspect Files, Text, Images
**Your goal:** Detect malware, data leaks, and inappropriate content by inspecting actual file content, not just the extension or URL.
**What you'll configure:**
* **True MIME Fingerprinting:** Detect `.exe` files renamed to `.pdf`
* **Text Analyser:** Scan uploads/emails for SSN, credit cards, keywords ("confidential")
* **Image Analyser (AI):** Detect inappropriate images, OCR text extraction from screenshots
**When to use:**
* ✅ Block executable downloads (`.exe`, `.msi`) except from approved software repos
* ✅ Detect MIME type spoofing (file named `report.pdf` but actually `application/x-executable`)
* ✅ DLP: Scan uploads for sensitive data (SSN, credit cards) before leaving network
* ✅ Block inappropriate images (NSFW content in file uploads)
**⚠️ Common pitfall:** Content analysis requires SSL inspection to be enabled. If you're not decrypting HTTPS, the Content Analyser can't inspect encrypted uploads.
→ [Configure Content Analyser](/use_cases/data_leakage_prevention/content_analyser)
***
### 5. [Request Profiles](/use_cases/profiling_engine/request_profiles) — Control by HTTP Method, Protocol, User-Agent
**Your goal:** Enforce SafeSearch, block POST requests to unapproved sites, or restrict HTTP methods (DELETE, PUT) for read-only access.
**What you'll configure:**
* HTTP method filtering (GET, POST, PUT, DELETE)
* Protocol restrictions (HTTP vs HTTPS)
* User-agent detection (block automated scrapers, allow legitimate browsers)
* SafeSearch enforcement (rewrite Google/Bing queries to enable SafeSearch)
**When to use:**
* ✅ Enforce SafeSearch on Google, Bing, YouTube (prevent adult content in search results)
* ✅ Read-only mode for social media (allow GET, block POST to prevent comments/posts)
* ✅ Block non-browser user agents (scrapers, bots, automated tools)
→ [Configure Request Profiles](/use_cases/profiling_engine/request_profiles)
***
### 6. [Response Profiles](/use_cases/profiling_engine/response_profiles) — Filter by MIME Type, File Size
**Your goal:** Block executable downloads, enforce file size limits, or quarantine archives for malware scanning.
**What you'll configure:**
* MIME type filtering (block `application/x-executable`, allow `application/pdf`)
* File extension filtering (block `.exe`, `.msi`, `.bat`)
* File size limits (block downloads >100MB during business hours)
* Archive handling (quarantine `.zip`, `.rar` for ClamAV scanning)
**When to use:**
* ✅ Block executable downloads (`.exe`, `.msi`) except from approved software repos
* ✅ Enforce file size limits (block downloads >100MB during business hours)
* ✅ Quarantine archives for malware scanning (`.zip`, `.rar` → ClamAV before delivery)
**⚠️ When NOT to use:** Response Profiles fire after the download starts. For pre-emptive blocking (before bandwidth is consumed), use Request Profiles + URL filtering instead.
→ [Configure Response Profiles](/use_cases/profiling_engine/response_profiles)
***
### 7. [Time Profiles](/use_cases/profiling_engine/time_profiles) — Enforce Policies by Time Window
**Your goal:** Allow social media during lunch, block large downloads during business hours, or require manager approval for after-hours access.
**What you'll configure:**
* Time ranges (8:00-17:00 Mon-Fri, 12:00-13:00 daily)
* Time-based rules (block Social Media except lunch hours)
* Shift-based policies (different rules for day shift vs night shift)
**When to use:**
* ✅ Allow social media only during lunch (12:00-13:00)
* ✅ Block large downloads during business hours (to preserve bandwidth)
* ✅ Flag after-hours uploads as suspicious (potential data exfiltration)
**Example:** Allow Facebook/Twitter only during lunch hour (12:00-13:00), block rest of the day.
→ [Configure Time Profiles](/use_cases/profiling_engine/time_profiles)
## ⚠️ Common Pitfalls
**1. Relying on IP addresses for identity**\
**What breaks:** Laptops switch networks, VPNs mask IPs, NAT pools rotate. Your "Finance team = 192.168.10.0/24" rule breaks when someone works from home.\
**Solution:** Use LDAP or SAML authentication. Configure [User Identities](/use_cases/authentication/user_identities) before building IP-based rules.
**2. Blocking "Cloud Storage" without whitelisting approved services**\
**What breaks:** Your categorization rule blocks "Cloud Storage" — but that includes SharePoint, OneDrive, and Box (approved). Users can't access business files.\
**Solution:** Create custom categories: "Approved Cloud Storage" (SharePoint, OneDrive) and "Personal Cloud Storage" (Dropbox, Google Drive). Block the latter.
**3. Enabling Content Analyser without SSL Inspection**\
**What breaks:** 90% of uploads are over HTTPS. If SSL inspection is disabled, Content Analyser can't see the payload — it's encrypted.\
**Solution:** Enable [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) before relying on Content Analyser for DLP or malware detection.
**4. Over-blocking with application signatures**\
**What breaks:** You block "Remote Access" signatures, which includes TeamViewer, AnyDesk, Chrome Remote Desktop — but also your approved VPN client. IT can't work remotely.\
**Solution:** Use fine-grained application rules: block TeamViewer for contractors, allow for IT group. Test with a pilot group before rolling out.
**5. Time-based policies without testing time zones**\
**What breaks:** Your "lunch hour" rule is 12:00-13:00 in IST, but your US office is in PST. US users get social media blocked during their work hours.\
**Solution:** Use UTC for time profiles and calculate offsets for each office, or create separate time profiles per region.
## Related Topics
**Prerequisites:**
* [Authentication Setup](/use_cases/authentication/authentication) — User identities require LDAP, AD, or SAML authentication
**Next Steps:**
* [Access Restrictions](/use_cases/access_restriction/access_restriction) — Use profiles to build allow/block policies
* [Data Leakage Prevention](/use_cases/data_leakage_prevention/data_leakage_prevention) — Combine Content Analyser with DLP templates
**Troubleshooting:**
* [User Not Identified](/troubleshooting/troubleshooting) — LDAP bind failures, group membership issues
* [Application Not Detected](/troubleshooting/troubleshooting) — Signature tuning, false positives
# Request Profiles
Source: https://docs.safesquid.com/use_cases/profiling_engine/request_profiles
Use SafeSquid Request Profiles to classify traffic by method, protocol, host, headers, user agent, and request behavior before applying enforcement policies.
# Classify traffic before you enforce it
## Problem statement
Many web controls fail because enforcement is attempted before traffic is classified correctly. If SafeSquid cannot distinguish uploads from downloads, browser traffic from desktop apps, or sanctioned SaaS use from general browsing, access rules become brittle and hard to tune.
## Client scenario
Use Request Profiles when you need to:
* identify requests by host, method, protocol, referrer, user agent, or header patterns
* separate upload paths from read-only browsing paths
* detect application-specific traffic such as desktop clients or SaaS services
* build precise exceptions for SSL bypass, authentication behavior, or access restriction
## Key benefits
Request Profiles create reusable classification signals. Instead of repeating complex matching logic in multiple policies, you define the request behavior once and then consume that profile throughout SafeSquid.
## Prerequisites
### Client-side preparations
* Ensure the target traffic reaches SafeSquid.
* Gather representative request samples before writing production rules.
### SafeSquid-side setup
* Decide which business behaviors you want to classify first, such as uploads, webmail, Teams desktop traffic, or read-only social-media use.
* Plan naming carefully so profiles remain understandable months later.
## Setup instructions
### Enable the Request Profiles section
In **Configure → Custom Settings → Request Types**, set the global **Enabled** field to `TRUE`.
If the section is disabled, none of the profile entries will classify traffic.
### Build rules from specific to broad
Request profile entries are tested in top-down order. Put highly specific application or workflow matches above general host or protocol matches.
This matters because the first matching logic can influence which profiles are added or removed.
### Use tracing when validating
Enable **Trace Entry** during testing for the rule you are tuning.
That gives you a way to verify whether the entry actually matched instead of guessing based on user outcome alone.
### Match only the attributes that matter
Use the minimum set of fields needed for reliable classification:
* **Method** for read, upload, or tunnel behavior
* **Protocol** for HTTP, HTTPS, or FTP context
* **Host Name** and **Smart TLD** for service targeting
* **User Agent** for application-specific traffic
* **Referrer** or header patterns when workflow context matters
Avoid overloading one rule with many weak conditions if one strong condition identifies the traffic more reliably.
### Add and remove profiles intentionally
Use **Added Request profiles** to tag traffic for later enforcement. Use **Removed Request profiles** only when you need to override or clean up an earlier broad match.
## Verification and validation
### Positive tests
Test realistic traffic that should match the rule, such as:
* a desktop app with a known user agent
* a SaaS upload using `POST` or `PUT`
* a specific host that should receive a special profile
Expected result:
* the intended request profile is added
* downstream access or inspection policy consumes that profile correctly
* logs show the expected request classification path
### Negative tests
Test nearby traffic that should not match, such as:
* a different app with a similar host
* normal browsing traffic on the same domain
* GET requests when the profile is intended only for uploads
Expected result:
* SafeSquid does not over-classify unrelated traffic
* exception profiles stay narrow
## Troubleshooting guide
### The expected request profile is never applied
Likely causes:
* the global section is disabled
* a higher rule matches first
* the selected fields do not reflect the actual traffic
Isolation steps:
* confirm the section is enabled
* enable **Trace Entry**
* compare live request headers against the rule conditions
Remediation:
* fix rule order
* refine the matching fields
* retest with captured request samples
### Too many requests receive the same profile
Likely causes:
* the hostname regex is too broad
* Smart TLD is enabled when a strict FQDN match is needed
* a generic user-agent pattern matches many clients
Isolation steps:
* inspect actual matched requests
* compare intended scope with the regex used
Remediation:
* narrow the regex
* disable Smart TLD where precise matching matters
* add another distinguishing field
### Downstream policy still does not behave correctly
Likely causes:
* the request profile is added correctly but never consumed
* another policy removes or overrides the profile later
Isolation steps:
* confirm the profile appears in logs
* inspect later profile-removal logic and downstream access rules
Remediation:
* attach the correct enforcement policy to the profile
* remove the unintended override
## Related controls / next steps
* Use [Access Restriction](/use_cases/access_restriction/access_restriction) to enforce decisions based on these profiles.
* Use [Response Profiles](/use_cases/profiling_engine/response_profiles) when the decision depends on server response content rather than request intent.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) to verify trace behavior and final profile assignment.
# Response Profiles
Source: https://docs.safesquid.com/use_cases/profiling_engine/response_profiles
Use SafeSquid Response Profiles to classify downloads and server responses by MIME type, file extension, size, and headers before applying controls.
# Classify downloads by what they return
## Problem statement
Many important web-control decisions depend on the response, not the request. A harmless-looking URL can return a macro-enabled document, a large archive, a WebSocket upgrade, or a suspicious MIME type. If SafeSquid does not classify the response correctly, downstream controls miss the real risk.
## Client scenario
Use Response Profiles when you need to:
* classify files by MIME type or extension
* detect high-risk downloads such as macro-enabled documents or archives
* separate WebSocket or special header-driven traffic
* trigger downstream blocking, logging, or handling based on returned content
## Key benefits
Response Profiles let you turn content-return characteristics into reusable enforcement signals. That improves file-control precision and makes download governance easier to tune than repeating MIME logic inside many separate rules.
## Prerequisites
### Client-side preparations
* Ensure the relevant download traffic reaches SafeSquid.
* If the response is encrypted, enable HTTPS inspection so SafeSquid can see the returned content.
### SafeSquid-side setup
* Decide which response conditions matter most first: MIME type, file extension, size, header patterns, or streaming behavior.
* Align response-profile names with the enforcement policy they support.
## Setup instructions
### Enable the Response Profiles section
In **Configure → Custom Settings → Response Types**, set **Enabled** to `TRUE`.
If the section is disabled, no response classification occurs.
### Order entries from precise to broad
Response profile logic is evaluated top-down. Put precise high-risk matches above generic content-type rules.
This reduces accidental over-classification.
### Match the right response attributes
Use the fields that best reflect the risk you care about:
* **Content type** for MIME-aware controls
* **File Extension** when the returned file name is meaningful
* **Minimum Content Size** and **Maximum Content Size** for large-download governance
* **Response Header Pattern** for protocol upgrades or specialized handling
### Use added and removed profiles carefully
Use **Added Response Types** to label the response for later enforcement. Use **Removed Response Types** only when a later rule must override an earlier broad classification.
## Verification and validation
### Positive tests
Use controlled downloads that should match the rule, such as:
* a macro-enabled Office document
* an `.epub` or `.azw` file
* a response with `Upgrade: websocket`
Expected result:
* the intended response profile is added
* downstream access or security policy acts on that profile
* logs show the response attributes you expected
### Negative tests
Download a nearby but benign file that should stay outside the rule.
Expected result:
* SafeSquid does not misclassify ordinary business traffic
* downstream controls do not over-block
## Troubleshooting guide
### The response profile does not appear
Likely causes:
* the section is disabled
* the content type or header does not match the real response
* HTTPS inspection is missing
Isolation steps:
* confirm the section is enabled
* inspect the actual MIME type and headers in logs
* confirm decryption for HTTPS traffic
Remediation:
* correct the matching criteria
* enable the required visibility path
* retest with a known sample
### Legitimate downloads are blocked too often
Likely causes:
* a generic MIME pattern is too broad
* file extension matching is catching approved formats
* a broad response profile is being consumed by an aggressive access rule
Isolation steps:
* identify the exact response profile applied
* compare the affected files against intended scope
Remediation:
* narrow the pattern
* add approved exceptions
* tune the downstream enforcement policy
### WebSocket or special response traffic is missed
Likely causes:
* the response header pattern is incorrect
* the relevant header never reaches the expected inspection point
Isolation steps:
* inspect the actual returned headers
* verify the rule pattern against the live header value
Remediation:
* correct the header regex
* retest using a known WebSocket-enabled destination
## Related controls / next steps
* Use [Access Restriction](/use_cases/access_restriction/access_restriction) to block or allow content based on response classification.
* Use [Content Fingerprints](/use_cases/data_leakage_prevention/true_mime_fingerprints) when true MIME validation must support the final decision.
* Use [Security Logs](/use_cases/audit_and_forensics/security_logs) to confirm MIME, headers, and final profile application.
# Time Profiles
Source: https://docs.safesquid.com/use_cases/profiling_engine/time_profiles
Configure SafeSquid Time Profiler to implement time-based internet access control using customizable time ranges including month, day, weekday, hour, and minute.
# Enforce access by time range
Time Profiler enforces time-based internet access using configurable ranges: month, day, weekday, hour, and minute. Create Time Profile entries as combinations of these ranges. SafeSquid allows or blocks categories and websites according to the active profile.
## Enable Time Profiler
1. Access the [SafeSquid interface](/architecture/interface/configuration_portal).
2. Navigate to **Configure** page.
![Configure page]()
3. Click **Custom Settings** in the sidebar.
![Custom Settings]()
4. Select **Time Profiler**.
![Time Profiler section]()
## Configuration Options
### Global Settings
| Setting | Description |
| - | - |
| **Enabled** | TRUE: Enable time profiles. FALSE: Disable time profiles. |
![Global section]()
### Time Profiles Tab
SafeSquid evaluates entries from top to bottom. All entries within the time range are applicable.
![Add new policy]()
![Time profiles tab]()
### Entry Settings
| Field | Description |
| - | - |
| **Enabled** | TRUE/FALSE - Enable or disable this entry |
| **Comment** | Documentation explaining the entry's purpose |
| **Trace Entry** | TRUE/FALSE - Enable debugging in SafeSquid logs |
| **Time Profiles** | List of Time Profiles for applicability. Leave blank to ignore. Use negation (! Weekday) to exclude profiles |
| **Month Range** | Active months (default: all months). Example: January to March |
| **Day Range** | Active days (default: all days). Example: 5 to 15 |
| **Weekday Range** | Active weekdays (default: all). Example: Monday to Thursday |
| **Hour Range** | Active hours (default: all). Example: 9 to 12 (9 AM to 12 PM) |
| **Minute Range** | Active minutes in conjunction with Hour Range. Example: 15 to 30 |
| **Time Match Mode** | ABSOLUTETIME or ALLRANGES. See the **Time Match Modes** section below for details on each mode |
| **Added Time Profiles** | Profiles to append when entry matches |
| **Removed Time Profiles** | Profiles to remove when entry matches |
### Time Match Modes
**ABSOLUTETIME:** Matches any time between starting and ending time only.
* Example: Weekday Monday-Friday, Hour 9-17
* Active from Monday 9 AM to Friday 5 PM continuously
**ALLRANGES:** Matches time within all specified ranges.
* Example: Weekday Monday-Friday, Hour 10-17
* Active every day Monday-Friday between 10 AM and 5 PM
## Examples
### Example 1: Standard Office Hours
Office hours: 10 AM to 9 PM, Monday to Friday.
| Field | Value |
| - | - |
| Hour Range | 10 to 21 |
| Weekday Range | Monday to Friday |
| Added Time Profiles | STANDARD OFFICE HOURS |
![Office hours rule]()
### Example 2: Lunch Hours
Lunch hours: 2 PM to 2:30 PM, Monday to Friday. Allow Social Media during lunch.
| Field | Value |
| - | - |
| Hour Range | 14 to 14 |
| Minute Range | 0 to 30 |
| Weekday Range | Monday to Friday |
| Added Time Profiles | STANDARD LUNCH HOURS |
![Lunch hours rule]()
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Backup Strategy
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/disaster_recovery
Decide what SafeSquid backs up, what it does not, and what the disaster-recovery plan must cover separately before the deployment depends on Cloud Restore.
# Know What the Backup Does Not Cover
Cloud Restore recovers SafeSquid policy state tied to the activation key. It does not rebuild the host, restore networking, or recover third-party integration secrets — and a DR plan that assumes otherwise discovers the gap during the rebuild, with the outage clock running.
Plan the backup around what it actually covers, and cover the rest separately.
## Understand the backup scope
**Included in cloud backup**
* All policy configuration (`config.xml`).
* SSL root certificate and private key.
* User groups, identity rules, access policies.
* Extended policies such as DLP and anti-virus.
**Not included — plan these separately**
* System logs.
* Network interface settings, including IP and hostname.
* Operating system configuration.
* Third-party integration secrets, such as LDAP credentials and external database connections.
The broader SafeSquid architecture treats backup and restore as a cloud-backed ecosystem service. Restricted or sovereignty-sensitive deployments should account for that cloud dependency explicitly during DR planning.
## Match the scenario to the recovery
| Scenario | Recovery | Result |
| - | - | - |
| Hardware failure destroys the proxy server | Restore from cloud to a new appliance | Operations resume without policy recreation |
| Accidental policy deletion or misconfiguration | Restore the previous version from cloud | Rollback to the last known-good state |
| Deploying clustered proxies | Restore master config to new slaves | Policy replicated across nodes |
| Migrating the proxy to new hardware | Restore to a new appliance with the same key | Zero policy recreation effort |
## Set the backup cadence
* **Automatic backup** — triggered when you select **Restart SafeSquid** after making configuration changes.
* **Manual backup** — **Support → Restart SafeSquid**, selecting **Yes** for cloud backup.
* **Retention** — the latest backup overwrites the previous one. A single version is stored per activation key.
Single-version retention is the constraint most DR plans miss. There is no point-in-time history to roll back through. So a bad configuration that gets backed up replaces the good one. Take a manual backup before a major change, and keep an exported copy outside the cloud store where the change is significant.
Before declaring production readiness, confirm:
* Activation key storage is recoverable without exposing the key contents.
* Configuration backup and restore are tested.
* Root CA material, if used, is backed up according to certificate-handling policy.
* Rebuild steps exist for appliance, cloud, or Linux deployment.
* DNS, PAC, GPO, MDM, firewall, and route rollback owners are named.
* A second node or restore target can use the same activation context when cluster or DR behavior requires it.
A DR stack keeps web security enforced during a regional outage. Without one, a site failure removes the control rather than degrading it, and users either lose internet access or get it unfiltered.
**Site requirements**
* **Geography** — a different city, data centre, and power grid than primary. Co-locating the DR stack with production negates continuity.
* **Capacity** — mirror production sizing across CPU, RAM, NICs, and disk. The DR site carries full load during failover, not a fraction of it.
* **Configuration** — replicate policy through [Configuration Sync](/use_cases/customisation/configuration_sync) or a documented manual procedure.
**Recovery objectives**
* **RTO (Recovery Time Objective)** — how long it may take to redirect traffic to the DR site.
* **RPO (Recovery Point Objective)** — how much policy and configuration lag is acceptable. Real-time sync approaches zero; manual replication does not.
**Failover methods**
| Method | How it works |
| - | - |
| DNS-based | Repoint A records at the DR address; recovery time is bounded by record TTL |
| BGP Anycast | Advertise the same address from the DR site |
| Load-balancer health check | Balancer withdraws the failed site and redirects automatically |
Set the RTO and RPO targets with the business, then test failover on a schedule and keep the result as audit evidence. Quarterly is a common cadence.
## Validate DR readiness
Validate on a non-production restore target, not on the production appliance:
* The same activation key finds the expected backup.
* Policy state matches the intended version.
* SSL material restores correctly.
* Host-specific settings are re-applied where needed.
* Client traffic passes through the rebuilt system.
## Capture backup evidence
Store these artifacts with the deployment record:
* The date of the last tested restore, and the named owner of the next test.
* The activation key storage location and its access control.
* The list of items covered separately because the cloud backup excludes them.
* The agreed RTO and RPO, and who set them with the business.
## Troubleshoot backup gaps
| Symptom | Likely cause | Fix |
| - | - | - |
| Restore succeeds but the host is unreachable | Network settings are outside the backup scope | Re-apply interface, hostname, and routing from the build record |
| Directory authentication fails after restore | LDAP credentials are not backed up | Restore integration secrets from their own approved store |
| A bad configuration cannot be rolled back | Single-version retention overwrote the good backup | Take a manual backup before major changes and keep an exported copy |
| Restore finds no backup | Different activation key on the restore target | Use the same activation key; the backup is bound to it |
| DR plan cannot be signed off | RTO and RPO were never agreed with the business | Set both targets before relying on the DR stack |
## Next steps
* [Configure Cloud Restore](/use_cases/customisation/configure_cloud_restore) - set up the backup this page plans around.
* [Configuration Sync](/use_cases/customisation/configuration_sync) - keep DR-site policy aligned with production.
* [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) - add failover before relying on restore alone.
# Forward Proxy
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/forward_proxy
Configure web browsers to use SafeSquid proxy server, including detailed steps for Chrome and Firefox proxy settings to access the SafeSquid WebGUI.
# Forward proxy requires explicit client configuration
## Why explicit proxy is used
Uncontrolled direct internet access increases malware, data loss, and compliance risk. SafeSquid provides a browser-based WebGUI at `http://safesquid.cfg` (an embedded Rest UI interface built into SafeSquid; accessible via proxy, NOT resolved by DNS) for configuration and management. Clients must send traffic through SafeSquid by configuring the browser or system proxy. Forward (explicit) proxy gives administrators clear control over which applications use the proxy and supports per-browser or per-application rollout.
## Benefits of forward proxy mode
Explicit configuration ensures only intended traffic is inspected. Policy enforcement and logging apply to configured clients. No network-layer redirection is required; deployment fits environments where endpoint configuration is manageable. **Limitation:** Applications that do not use the configured proxy bypass SafeSquid unless system-wide or PAC-based proxy is used.
## Prerequisites
**Client-side:** Browser supporting manual proxy configuration (Chrome, Firefox, or equivalent). SafeSquid proxy IP and port (default 8080). **SafeSquid-side:** SafeSquid deployed and listening on the proxy port; WebGUI reachable via proxy at `http://safesquid.cfg` (embedded interface, NOT DNS-resolved).
## Configure proxy in Chrome (system settings)
1. Open Chrome browser settings from the toolbar.
![Chrome menu]()
![Settings option]()
2. Click the **System** tab in Settings, or search for "proxy" in the search bar.
![System tab]()
![Search proxy]()
3. Click **Open your computer's proxy settings**.
![Proxy settings link]()
4. Enable **Use a proxy server**.
![Enable proxy]()
![Proxy toggle]()
5. Enter the proxy server IP address and port **8080**.
![Proxy address and port]()
6. (Optional) Enter domains and IP addresses to bypass the proxy in the exclusion field:
* Example: `infatica.io`, `192.158.1.38`, addresses starting with `127.`
![Proxy bypass list]()
7. Click **Save**.
![Save settings]()
## Configure Proxy in Firefox
Firefox allows browser-specific proxy configuration without affecting system-wide settings.
1. Open Firefox and click the **menu button** (three horizontal lines) in the top right corner.
![Firefox menu]()
2. Click **Settings**.
![Firefox settings]()
3. Scroll down to **Network Settings** in the General section.
![Network Settings]()
4. Click the **Settings** button.
![Settings button]()
5. Select **Manual proxy configuration**.
![Manual proxy option]()
6. Enter the proxy server address and port number.
![Proxy details]()
7. Click **OK** to save changes.
![Save Firefox settings]()
## Verify configuration
Open `http://safesquid.cfg` through the proxy; the SafeSquid WebGUI loads. Browse an external site; traffic appears in SafeSquid access logs from the client IP. **Interface:** Confirm proxy IP and port in browser or system proxy settings. **Logs:** Check `access.log` or Reporting for requests from the client.
## Troubleshooting
| Symptom | Likely cause | Resolution |
| - | - | - |
| WebGUI or sites do not load | Wrong proxy IP/port or proxy down | Verify SafeSquid is listening on 8080; confirm IP and port in browser. |
| Some sites work, others fail | Bypass list or policy blocking | Review bypass list and access restriction rules. |
| Firefox works, Chrome does not | Chrome using system proxy vs manual | Ensure Chrome proxy settings match intended proxy (system or manual). |
**Escalation:** If connectivity fails after correct configuration, check firewall and SafeSquid service status; contact support with access log excerpts.
## Next steps
* [Transparent Proxy](/use_cases/scaling_and_high_availability/transparent_proxy) for interception without client proxy configuration.
* [Connect Your Client](/getting_started/client_configuration/connect_your_client) for PAC file, system-wide, and enterprise deployment.
* Verify your setup to confirm end-to-end connectivity.
# High Availability with Monit and Keepalived
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/ha_monit_keepalived
Build active-passive SafeSquid high availability using Keepalived for VIP failover and Monit for process supervision, with split-brain protection and tested failover.
# Survive a Proxy Node Failure
A single SafeSquid node is a single point of failure for every user behind it. When the proxy stops answering, browsing stops — and so does policy enforcement, logging. The audit trail that proves enforcement happened. Users escalate, and the fastest workaround an impatient administrator reaches for is disabling the proxy entirely.
Active-passive high availability removes that pressure. Clients connect to a virtual IP (VIP) that always points at a healthy node. Keepalived moves the VIP on failure in 2–3 seconds; Monit independently restarts a crashed SafeSquid process on either node.
## Split responsibilities between two tools
Keepalived and Monit solve different problems. They do not conflict — running only one leaves a gap.
| Layer | Keepalived | Monit |
| - | - | - |
| Purpose | VIP ownership via VRRP | Application health and process management |
| Failover trigger | Health-check script exits non-zero | PID file missing or port not responding |
| Failover speed | 2–3 seconds | 30–60 seconds |
| Split-brain protection | Prevented by VRRP priority election | Not provided; mitigated by priority weights |
| Restarts SafeSquid | No | Yes |
Keepalived runs the health-check script every 5 seconds. If SafeSquid is not serving traffic, Keepalived drops the Master's VRRP priority below the Backup's and the VIP moves. Monit restarts SafeSquid on the failed node and logs the event.
```mermaid theme={null}
flowchart TB
Clients[Clients] -->|proxy requests to VIP| VIP[Virtual IP]
VIP --> Master[Master node - priority 101]
VIP -.->|on failover| Backup[Backup node - priority 100]
Master -->|health check every 5s| KA1[Keepalived]
Backup -->|health check every 5s| KA2[Keepalived]
KA1 <-->|VRRP advertisements| KA2
Master --> M1[Monit restarts SafeSquid]
Backup --> M2[Monit restarts SafeSquid]
```
## Match the design to the failure
| Failure | What happens | Result for users |
| - | - | - |
| SafeSquid stops answering on the Master | Keepalived detects the failed check and moves the VIP | Clients reconnect within 2–3 seconds |
| SafeSquid process crashes | Monit finds no PID and restarts the service | No administrator action needed |
| Network partition between nodes | VRRP priority election keeps one owner | Split brain is prevented by design |
| Planned maintenance on the Master | Stop SafeSquid; the Backup takes the VIP | Zero-downtime maintenance window |
## Prerequisites
* Two SafeSquid instances installed and activated — one Master, one Backup.
* Both nodes on the same subnet, so VRRP advertisements reach both.
* One unused IP address for the VIP. It must not be assigned to any other host or DHCP pool.
* Root or sudo access on both nodes.
* Firewall rules permitting VRRP (IP protocol 112) between the two nodes.
* `keepalived`, `monit`, and `curl` available from the distribution repositories.
Record the environment before you start. The examples below use these values — substitute your own throughout.
| Component | Example value | Notes |
| - | - | - |
| Master node | `MASTER-IP` | Active node, VRRP priority 101 |
| Backup node | `BACKUP-IP` | Standby node, VRRP priority 100 |
| Virtual IP | `VIP-ADDRESS` | Clients always connect to this address |
| Network interface | `INTERFACE` | Confirm the name on both nodes with `ip a` |
| SafeSquid port | `8080` | Monitored by Keepalived and Monit |
Point clients at the VIP, not at either node address. A PAC file, GPO, or MDM profile that names the Master directly will not fail over.
## Install both packages on both nodes
Run this on the Master and the Backup:
```bash theme={null}
sudo apt update && sudo apt install keepalived monit curl -y
```
Expected result: both services install and are available to `systemctl`.
## Create the health-check script
Keepalived runs this script every 5 seconds. A non-zero exit drops the node's VRRP priority and triggers VIP handover.
Create `/etc/keepalived/check_safesquid.sh` on **both** nodes:
```bash theme={null}
#!/bin/bash
# Health check for SafeSquid, run by Keepalived.
# Exit 0 = healthy. Exit 1 = failed, triggers priority drop.
PORT=8080
TIMEOUT=3
# Check 1: is the SafeSquid service active?
if ! systemctl is-active --quiet safesquid; then
echo "$(date): SafeSquid service not active" >> /var/log/keepalived_check.log
exit 1
fi
# Check 2: is SafeSquid answering on the proxy port?
if ! curl -s --max-time $TIMEOUT -x 127.0.0.1:$PORT http://safesquid.cfg > /dev/null 2>&1; then
echo "$(date): SafeSquid port $PORT not responding" >> /var/log/keepalived_check.log
exit 1
fi
exit 0
```
Make it executable on both nodes:
```bash theme={null}
sudo chmod +x /etc/keepalived/check_safesquid.sh
```
The second check matters. A process that is running but not accepting connections still fails users. A PID check alone will not catch it.
## Configure Keepalived on both nodes
Only `state` and `priority` differ between the two files. Everything else must match exactly.
`virtual_router_id` must be identical on both nodes, and `auth_pass` must be identical and **8 characters or fewer** — Keepalived truncates longer values, which produces a silent mismatch and two Masters.
Write `/etc/keepalived/keepalived.conf`:
```conf theme={null}
global_defs {
router_id PROXY_HA
script_user root
enable_script_security
}
vrrp_script check_safesquid {
script "/etc/keepalived/check_safesquid.sh"
interval 5 # Run the check every 5 seconds
weight -101 # Drop priority by 101 on failure
fall 2 # Fail after 2 consecutive failures
rise 2 # Recover after 2 consecutive successes
}
vrrp_instance SAFESQUID_VIP {
state MASTER
interface INTERFACE
virtual_router_id 51
priority 101 # Higher than Backup, so it wins the election
advert_int 1 # Advertise every 1 second
nopreempt # VIP stays on the Backup after recovery
authentication {
auth_type PASS
auth_pass SafeSqid # Identical on both nodes, 8 characters maximum
}
virtual_ipaddress {
VIP-ADDRESS/32 dev INTERFACE
}
track_script {
check_safesquid
}
}
```
Write `/etc/keepalived/keepalived.conf`:
```conf theme={null}
global_defs {
router_id PROXY_HA
script_user root
enable_script_security
}
vrrp_script check_safesquid {
script "/etc/keepalived/check_safesquid.sh"
interval 5
weight -101
fall 2
rise 2
}
vrrp_instance SAFESQUID_VIP {
state BACKUP
interface INTERFACE
virtual_router_id 51
priority 100 # Lower than Master, so it yields
advert_int 1
nopreempt
authentication {
auth_type PASS
auth_pass SafeSqid # Must match the Master exactly
}
virtual_ipaddress {
VIP-ADDRESS/32 dev INTERFACE
}
track_script {
check_safesquid
}
}
```
### Why the weight is -101
The weight must push the Master's effective priority below the Backup's, not merely reduce it.
* The Master starts at priority 101.
* On check failure, `weight -101` makes the effective priority `101 - 101 = 0`.
* `0` is below the Backup's `100`. So the Backup wins the VRRP election, advertises the higher priority, and the Master releases the VIP.
A weight of `-60` yields `101 - 60 = 41`. That is still below 100, but it does not reliably drive the BACKUP state transition across Keepalived versions. Use `-101` so the outcome is unambiguous.
## Configure Monit on both nodes
Monit supervises the SafeSquid process and restarts it. It does not touch the VIP — that stays with Keepalived.
Write `/etc/monit/conf.d/safesquid.monit` on both nodes:
```conf theme={null}
check process safesquid_proxy_service with pidfile /var/run/safesquid/safesquid.pid
group root
start program = "/usr/bin/systemctl start safesquid.service" with timeout 60 seconds
stop program = "/usr/bin/systemctl stop safesquid.service" with timeout 60 seconds
if does not exist then restart
if 3 restarts within 5 cycles then alert
mode active
```
Keep `set daemon` and `set httpd` in `/etc/monit/monitrc` only. Repeating them here produces an `address option specified twice` error and Monit refuses to start.
## Start both services
Run on both nodes:
```bash theme={null}
sudo systemctl enable keepalived
sudo systemctl start keepalived
sudo systemctl enable monit
sudo systemctl restart monit
```
Confirm the VIP landed on the Master:
```bash theme={null}
ip a show INTERFACE | grep VIP-ADDRESS
```
Expected output on the Master only:
```text theme={null}
inet VIP-ADDRESS/32 scope global proto keepalived INTERFACE
```
The `proto keepalived` tag confirms Keepalived owns the address and will withdraw it automatically on failover. An address without that tag was assigned statically and will not move.
## Verify and evidence failover
Confirm the Master state and a passing health check:
```bash theme={null}
sudo systemctl status keepalived
sudo journalctl -u keepalived -n 30 --no-pager
```
Expected output on the Master includes:
```text theme={null}
(SAFESQUID_VIP) Entering MASTER STATE
VRRP_Script(check_safesquid) succeeded
```
### Test the failover
Open two terminals. Watch the log on the Backup while you stop SafeSquid on the Master.
```bash theme={null}
# Backup node: follow the Keepalived log
sudo journalctl -u keepalived -f
```
```bash theme={null}
# Master node: trigger the failure
sudo systemctl stop safesquid
```
Within 10–15 seconds the log shows the handover:
```text theme={null}
(SAFESQUID_VIP) Changing effective priority from 101 to 0
(SAFESQUID_VIP) Master received advert from BACKUP-IP with higher priority 100
(SAFESQUID_VIP) Entering BACKUP STATE
(SAFESQUID_VIP) Transition to MASTER STATE
Sending gratuitous ARP on INTERFACE for VIP-ADDRESS
```
Confirm the VIP moved:
```bash theme={null}
ip a show INTERFACE | grep VIP-ADDRESS
```
Restore SafeSquid on the Master after the test:
```bash theme={null}
sudo systemctl start safesquid
```
`nopreempt` keeps the VIP on the Backup after the Master recovers. This avoids a second interruption during business hours. To move the VIP back deliberately, restart Keepalived on the Master: `sudo systemctl restart keepalived`.
### Capture HA evidence
Store these artifacts with the change record:
* Both `keepalived.conf` files and the health-check script, with a checksum.
* `journalctl -u keepalived` extract covering the tested failover, showing the state transition and gratuitous ARP.
* `ip a` output before and after failover, showing VIP ownership on each node.
* `/var/log/keepalived_check.log` and `/var/log/monit.log` for the test window.
* Client-side proof that browsing resumed through the VIP, plus the SafeSquid access log entries from the surviving node.
* The date of the last tested failover and the named owner of the next test.
Untested failover is not high availability. Schedule a failover test on the same cadence as your disaster-recovery restore test and keep the evidence.
## Troubleshoot HA failures
| Symptom | Cause | Fix |
| - | - | - |
| Both nodes report MASTER | `virtual_router_id` or `auth_pass` mismatch | Set `virtual_router_id 51` and an identical `auth_pass` on both nodes |
| VIP not assigned at Master startup | Invalid VIP format in the config | Run `keepalived --config-test -f /etc/keepalived/keepalived.conf`; the VIP must be a valid IPv4 address |
| VIP not released after a failed check | `weight` does not drop priority below the Backup | Use `weight -101` so the effective priority reaches 0 |
| Keepalived does not start | Configuration syntax error | Run `keepalived --config-test -f /etc/keepalived/keepalived.conf` and correct the reported line |
| `auth_pass` truncation warning in the log | Password longer than 8 characters | Shorten to 8 characters or fewer and apply the same value on both nodes |
| VRRP advertisements never arrive | Firewall blocks IP protocol 112 | Allow protocol 112 between the nodes, for example `sudo ufw allow proto 112` |
| Monit reports `address option specified twice` | Global settings duplicated in `safesquid.monit` | Remove `set daemon` and `set httpd`; keep them in `/etc/monit/monitrc` |
| VIP stays on the Backup after the Master recovers | `nopreempt` is set, which is intended | Restart Keepalived on the Master to move the VIP back |
## File reference
| Path | Purpose |
| - | - |
| `/etc/keepalived/keepalived.conf` | VRRP state, priority, VIP, and health-check binding |
| `/etc/keepalived/check_safesquid.sh` | Health check run every 5 seconds |
| `/etc/monit/monitrc` | Monit global configuration |
| `/etc/monit/conf.d/safesquid.monit` | SafeSquid process supervision and alerting |
| `/var/log/keepalived_check.log` | Health-check failure log |
| `/var/log/monit.log` | Monit activity log |
### Master and Backup differences
| Setting | Master | Backup |
| - | - | - |
| `state` | `MASTER` | `BACKUP` |
| `priority` | `101` | `100` |
| `weight` | `-101` | `-101` |
| `nopreempt` | Set | Set |
| `virtual_router_id` | `51` | `51` (must match) |
| `auth_pass` | Identical on both nodes | Identical on both nodes |
| `virtual_ipaddress` | Same VIP | Same VIP |
| `check_safesquid.sh` | Identical on both nodes | Identical on both nodes |
## Next steps
* [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) - scale enforcement across more than two nodes.
* [Configuration Sync](/use_cases/customisation/configuration_sync) - keep policy identical on both HA nodes.
* [Disaster Recovery](/use_cases/scaling_and_high_availability/disaster_recovery) - plan rebuild and restore beyond node failover.
# Master-Slave
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/master_slave
Configure SafeSquid master-slave architecture for centralized policy sync and reporting across slave instances.
# Plan Master-Slave Configuration for Central Policy
## How master-slave works
In a master-slave configuration, one SafeSquid instance (the master) manages policy and reporting for multiple slave instances. Slaves enforce policy and process traffic; master provides centralized control.
**Data flow:**
* **Master → Slaves**: Policies, configuration, tasks
* **Slaves → Master**: Reporting data, logs, statistics
Control and policy flow from master to slaves; reporting data flows from slaves to master:
```mermaid theme={null}
flowchart TB
Master[Master SafeSquid]
Slave1[Slave 1]
Slave2[Slave 2]
Master -->|policies and tasks| Slave1
Master -->|policies and tasks| Slave2
Slave1 -->|reporting data| Master
Slave2 -->|reporting data| Master
```
**Slave behavior:**
* Processes client traffic and enforces policy synced from master
* Forwards reporting data to master for centralized analysis
* Operates independently if master is temporarily unavailable (uses last synced policy)
**Master behavior:**
* Does not process client traffic directly
* Aggregates reporting data from all slaves into unified reports
* Pushes policy updates to slaves automatically
## Prerequisites
* SafeSquid installed on all nodes (master and slaves)
* Same activation key on all nodes
- Network access from slaves to master's configured proxy port (the same LISTEN\_PORT the master serves its Configuration Portal on — 8080 in this page's own screenshots; verify the actual port on your master under Support → Startup params before connecting a slave)
- If authentication is enabled on master, slaves must be allowed in Access restrictions → Allow list
## Configure master-slave relationship
Follow these steps to connect a slave instance to a master. Perform slave configuration first, then (if authentication is enabled) configure the master to allow the slave.
## Step 1: Configure slave server
### [Access the SafeSquid User Interface](/architecture/interface/configuration_portal) on the slave server
## Go to Support
![clicking on support in SafeSquid interface in top right corner]()
## Go to Startup params
![clicking on start up params]()
![clicking on edit button]()
![entering the master IP address]()
![entering the port of master server]()
![clicking on submit button]()
![clicking on restart button]()
![clicking on yes for backup current configuration to cloud]()
## Step 2: Configure master server (if authentication is enabled)
If your master requires authentication, add the slave IP to the Allow list so the slave can access the Configuration Portal and sync policies.
### Go to Access restrictions under Application Setup
![Going to Access restrictions under Application Setup]()
## Go to Allow list
![going to allow list tab in access restrictions]()
![enabling the policy as true]()
![enabling the policy as true for giving access to slave server]()
![clicking on save to save the policy]()
![policy saved]()
## Step 3: Verify synchronization
### Check slave configuration sync
![Verifying the synchronization of defined sections on Slave server]()
On the slave Configuration Portal, confirm that sections synced from the master appear with the same settings. Make a test policy change on the master and verify it appears on the slave within a few minutes.
### Verify reporting flow
On the master, open [Reporting Service](/architecture/interface/reporting_service) and confirm logs from slave nodes appear in unified reports. Slave traffic should be visible on the master.
## Verification checklist
* [ ] Slave Configuration Portal → Support → Startup params shows correct master IP and port
* [ ] Master Configuration Portal → Access restrictions → Allow list includes slave IP (if authentication enabled)
* [ ] Test policy change on master propagates to slave within 5 minutes
* [ ] Slave traffic appears in master Reporting Service
* [ ] Slave logs show successful sync events (check `/var/log/safesquid/extended/extended.log`)
## Troubleshooting
**Slave not syncing policies:**
* Verify network connectivity from slave to the master's configured LISTEN\_PORT (8080 in this page's verified screenshots; confirm the actual value on the master under Support → Startup params): `telnet `
* Check master firewall allows incoming connections on that port
* If authentication enabled, verify slave IP in master Access restrictions → Allow list
* Check slave logs: `tail -f /var/log/safesquid/extended/extended.log` (look for sync errors)
**Slave traffic not appearing in master reports:**
* Verify reporting data path is not blocked by firewall
* Check slave Configuration Portal → Support → Startup params has correct master IP
* Restart slave: Configuration Portal → Support → Restart SafeSquid
**Policies syncing but not applying:**
* After policy changes on master, restart slave to apply: Configuration Portal → Support → Restart SafeSquid
* Verify slave activation key matches master (same license)
**Related**: [Configuration Sync](/use_cases/customisation/configuration_sync), [Configuration Portal](/architecture/interface/configuration_portal), [Reporting Service](/architecture/interface/reporting_service), [Troubleshooting](/troubleshooting/troubleshooting)
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
* **[Reporting & Forensics](/architecture/interface/reporting_service)** - reporting and forensics in SafeSquid — centralized visibility, SIEM-ready logging, audit evidence, and operational investigation workflows for proxy deployments.
* **[Configuration Sync](/use_cases/customisation/configuration_sync)** - discover how to enable configuration synchronization across a SafeSquid proxy cluster to ensure consistent policy deployment, reduce administrative overhead, and improve system reliability and security.
# Proxy Chain
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/proxy_chain
Deploy SafeSquid behind a parent proxy with proxy chaining, HTTPS inspection, and request forwarding for enterprise integration.
# Forward client traffic through a parent proxy
Use SafeSquid as a child proxy in front of a corporate (parent) proxy. A simple configuration in SafeSquid forwards all client requests to the parent proxy. SafeSquid can still perform HTTPS inspection and policy enforcement before forwarding; the parent handles upstream connectivity and any corporate policy.
Traffic flows from the client through the child SafeSquid to the parent proxy, then to the internet:
```mermaid theme={null}
flowchart TB
Client[Client browser]
Child[Child SafeSquid]
Parent[Parent proxy]
Internet[Internet]
Client --> Child
Child --> Parent
Parent --> Internet
```
Example scenarios:
![Proxy chain scenario: client, child proxy, and parent proxy network layout]()
Here am using two proxy servers as SafeSquid only
My client (Browser)## 's network IP - 192.168.0.27
My Child Proxy## 's network IP - 192.168.27.50 (with no direct internet Access)
My Parent Proxy## 's network IP - 192.168.27.100
**Configuration on child proxy:**
1. Deploy SafeSquid proxy
2. Enabling SSL inspection in SafeSquid
3. Downloading ROOT CA certificate from SafeSquid
4. Deploy certificate in client browsers.
5. Enable forwarding to parent proxy using forwarding section
**Configuration on Parent proxy:**
Deploy SafeSquid, it is up and running, no extra configuration required in parent proxy
## Prerequisites
Enable HTTPS inspection on child proxy (optionally on parent proxy also). To configure HTTPS inspection on SafeSquid, see [How to configure HTTPS inspection](/use_cases/ssl_inspection/ssl_inspection)
Import SafeSquid child proxy ROOT CA in client browser
Note: No configuration required on Parent Proxy server. Just deploy the parent proxy and make sure that it is up and running.
## Configure proxy chain in SafeSquid
Access the [SafeSquid Configuration Portal](/architecture/interface/configuration_portal).
### Open Configure page
![Configure page in SafeSquid interface]()
### Open Application Setup → Proxy chain
![Application Setup section in sidebar]()
![Proxy chain section in Application Setup]()
### Enable Global section
![Enable Global section for proxy chain]()
![Global proxy chain toggle and options]()
![Saving Global proxy chain configuration]()
### Open Forwarding proxies and add an entry
![Forwarding proxies section]()
![Edit the default forwarding proxy entry]()
![Enable the forwarding proxy entry]()
![Add a reference comment for the forwarding proxy entry]()
![Entering parent proxy host or IP (192.168.27.100)]()
In the example: my upstream proxy ip: 192.168.27.100
![If the upstream proxy requires authentication, enter user name, password, and domain]()
![Entering parent proxy port]()
In example: my upstream proxy listening on port 8080
![Leave ICP peer type and ICP port at their defaults]()
![Selecting CONNECT as the forwarding proxy Type]()
![Selecting CONNECT and HTTP requests under Applies to]()
![Click Save Policy to save the forwarding proxy entry]()
![Forwarding proxy entry after saving]()
### Test proxy chain connectivity
![Open Reports to verify proxy chain connectivity]()
![Open Native logs under Reports]()
![Verifying traffic through parent proxy]()
### Save configuration
![Save configuration to apply proxy chain settings]()
When the administrator clicks Save Config, a prompt asks for confirmation to store the configuration in the cloud.
Select Yes only in below cases:
to reuse this configuration in other SafeSquid instances.
if the total configuration in all sections is completed and validated.
Otherwise select No and click on submit.
## Verification and Evidence
* **Interface Checks**: In [Configuration Portal](/architecture/interface/configuration_portal), open Application Setup → Proxy chain. Confirm Global is enabled and the forwarding proxy entry shows the correct parent IP and port.
* **Log Analysis**: Check SafeSquid access logs for requests showing the parent proxy as upstream. Connection failures to the parent appear in logs with connect errors.
* **Performance Validation**: From a client behind the child proxy, browse an external site. Traffic should succeed and appear in both child and parent proxy logs.
## Next steps
* [Forward Proxy](/use_cases/scaling_and_high_availability/forward_proxy) for explicit proxy without chaining.
* [SSL Inspection](/use_cases/ssl_inspection/configure_https_inspection) for HTTPS inspection on the child proxy.
* [Troubleshooting](/troubleshooting/troubleshooting) if connectivity or parent proxy errors occur.
# Proxy Clustering
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/proxy_clustering
Scale SafeSquid with master-slave clustering, configuration sync, and load balancer integration for high availability and horizontal scaling.
# Master-slave clustering for high availability
SafeSquid supports clustered deployments for high availability, failover, and horizontal scaling. A master node holds policy and reporting; slave nodes enforce policy and forward data. Use a load balancer in front of slaves for distribution and failover.
## Problem statement
Single-node deployments create both scale risk and availability risk. Clustering is the documented way to reduce that risk while keeping policy consistent across enforcement nodes.
## When to use clustering
| Scenario | Solution | Benefit |
| - | - | - |
| Single proxy is overwhelmed by traffic | Add slave nodes behind load balancer | Distribute load horizontally |
| Proxy downtime causes network outage | Master-slave with failover | High availability |
| Managing policies on multiple proxies | Configuration sync from master | Consistent enforcement across nodes |
| Compliance requires centralized reporting | Master aggregates slave data | Unified audit trail |
## Prerequisites
* Same SafeSquid version on all nodes
* Same activation key on master and slaves
- Network connectivity: slaves can reach the master's configured proxy port (the same LISTEN\_PORT the master serves its Configuration Portal on — 8080 in verified evidence; confirm the actual value on your master under Support → Startup params)
- Load balancer configured to distribute traffic to slave nodes (not to master)
- Time synchronization (NTP) across all nodes
- A reporting plan so evidence from all active nodes remains visible
## Architecture overview
**Master node:**
* Hosts Configuration Portal for policy management
* Aggregates reporting data from slaves
* Does NOT process client traffic directly
**Slave nodes:**
* Enforce policies synced from master
* Process client traffic
* Forward reporting data to master
**Load balancer:**
* Distributes client requests across slave nodes
* Provides failover if a slave goes down
* Does NOT route to master (master is for management only)
Internal product knowledge confirms automatic policy replication across cluster nodes and no documented hard ceiling on total cluster node count. Treat single-instance capacity and cluster capacity as separate planning questions.
## Verification and validation
After clustering is configured, validate:
* policy changes replicate to every node
* the load balancer does not send client traffic to the master
* a failed slave is removed from active service
* reporting still captures traffic from each surviving node
* authentication and SSL inspection behavior remain consistent across nodes
The documents below cover master-slave setup and configuration sync.
## Clustering configuration guides
### [Master-Slave](/use_cases/scaling_and_high_availability/master_slave)
Single-node deployments lack failover and scale limits. Master-Slave describes how to configure a master node for policy and reporting and slave nodes for traffic enforcement. Centralized policy and unified reporting reduce administrative overhead. Follow this document to set up master-slave relationships.
### [Configuration Sync](/use_cases/customisation/configuration_sync)
Configuration drift across nodes causes inconsistent enforcement and troubleshooting difficulty. Configuration Sync enables automatic propagation of policy and configuration from master to slaves. All nodes stay aligned without manual copy. Configure sync using this document.
## Next steps
Place a load balancer in front of slave nodes. See [Disaster Recovery](/use_cases/scaling_and_high_availability/disaster_recovery) for backup and restore, and Verify your setup for post-cluster validation.
# Reverse Proxy
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/reverse_proxy
Configure SafeSquid as reverse proxy for performance, SSL termination, security, and caching without client proxy settings.
# Reverse proxy protects and accelerates backend servers
A reverse proxy sits in front of backend web servers and accepts client requests. It forwards requests to the appropriate backend and returns responses. Clients connect to the reverse proxy; they do not need proxy configuration. SafeSquid as reverse proxy provides a single point for SSL termination, authentication, caching, and load distribution while hiding backend server identities.
## Benefits of SafeSquid reverse proxy
**Web acceleration**
SafeSquid Reverse proxies can compress inbound and outbound data, as well as cache commonly requested content, both of which speed up the flow of traffic between clients and servers. They can also perform additional tasks such as SSL encryption to take load off the web servers, thereby boosting their performance.
**SSL Termination**
Here the reverse proxy handles incoming HTTPS connections, decrypting the requests and passing unencrypted requests on to the web servers. This has several benefits:
Removes the need to install certificates on many back-end web servers.
Provides a single point of configuration and management for SSL/TLS
Takes the processing load of encrypting/decrypting HTTPS traffic away from web servers.
Makes testing and intercepting HTTP requests to individual web servers easier.
**Security and anonymity**
By intercepting requests headed for the back-end servers, a reverse proxy server protects their identities and acts as an additional defense against security attacks. It also ensures that multiple servers can be accessed from a single record locator or URL regardless of the structure of the local area network.
**Authentication**
You can use SafeSquid reverse proxy to provide a single point of authentication for all HTTP and HTTPS requests.
**Caching**
The SafeSquid reverse proxy can also act as a cache. You can either have a dumb cache that simply expires after a set period, or better still a cache that respects Cache-Control and Expires headers. This can considerably reduce the load on the back-end servers.
Setup the SafeSquid in reverse proxy mode. A reverse proxy by itself appears to the client just like an ordinary website No special configuration on the client is necessary. Basically, a reverse proxy is on the website end which will be used to protect and reduce the load on the website
This example uses a website hosted on an Apache server and sets up the reverse proxy for that website.
**Website details:**
FQDN: test.safesquid.net
IP: 192.168.27.50
**SafeSquid proxy** runs on 192.168.27.10.
### Configuration on website
Create a DNS entry for the website pointing to the proxy IP. Traffic to that hostname then fetches content via the proxy server.
On the request of traffic proxy server will fetch content from original site, and response back to the request.
**In this example:**
192.168.27.10 is pointing to test.safesquid.net
### Configuration on proxy server
Make sure that port 80 is free in proxy server, because it should not be allocated by any other service in the proxy server
You can verify it by using below command:
```bash theme={null}
netstat -tulnp
```
![Check port 80 is free in proxy server by using netstat command]()
No service is allocated to port 80
Enable forwarding option in **/etc/sysctl.conf file**
Replace this line as\*\*: net.ipv4.ip\_forward=0 to net.ipv4.ip\_forward=1\*\*
```bash theme={null}
net.ipv4.ip_forward=1
```
Then add the Iptables rule to redirect the traffic from 80 to 8080:
```bash theme={null}
iptables -A PREROUTING -t nat -p tcp --dport 80 -j REDIRECT --to 8080
```
On the proxy, block all websites except the target website so the proxy does not act as an open proxy.
See how to allow single website
Create a DNS entry for the website pointing to the back-end server IP. In this example **192.168.27.50** is **test.safesquid.net**.
![Make DNS entry of website pointing to website IP]()
Access the website from a client machine without configuring proxy settings in the browser. Server logs show that the website was accessed via the proxy IP.
![In Server logs, view which the website is access with proxy IP]()
## Next steps
* [Forward Proxy](/use_cases/scaling_and_high_availability/forward_proxy) for client-facing explicit proxy.
* [SSL Inspection](/use_cases/ssl_inspection/configure_https_inspection) for HTTPS termination.
* [Proxy Clustering](/use_cases/scaling_and_high_availability/proxy_clustering) for high availability.
# TCP Proxy
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/tcp_proxy
Configure SafeSquid TCP Proxy mode to handle non-HTTP TCP connections, enabling secure proxying of various TCP-based protocols and applications.
# TCP proxy handles non-HTTP protocols
## When to use TCP proxy
HTTP/HTTPS traffic is handled by SafeSquid's HTTP proxy. Applications using other TCP-based protocols (e.g. custom ports, non-web services) need a way to route through the proxy. TCP Proxy mode enables SafeSquid to accept and forward non-HTTP TCP connections so all TCP traffic can be funneled through the gateway. Clients still configure the proxy (e.g. browser or system proxy); SafeSquid forwards the TCP stream to the destination.
## Configure TCP proxy in browser
### Chrome (System Settings)
1. Open Chrome browser settings from the toolbar.
![Chrome menu]()
![Settings option]()
2. Click the **System** tab or search for "proxy".
![System tab]()
![Search proxy]()
3. Click **Open your computer's proxy settings**.
![Proxy settings]()
4. Enable **Use a proxy server**.
![Enable proxy]()
![Proxy toggle]()
5. Enter the proxy server IP address and port **8080**.
![Proxy address]()
6. (Optional) Enter bypass addresses.
![Bypass list]()
7. Click **Save**.
![Save settings]()
### Firefox
1. Open Firefox menu and click **Settings**.
![Firefox menu]()
![Firefox settings]()
2. Navigate to **Network Settings** in General section.
![Network Settings]()
3. Click **Settings**.
![Settings button]()
4. Select **Manual proxy configuration** and enter proxy details.
![Manual proxy]()
5. Click **OK** to save.
![Save]()
## Next steps
* [Forward Proxy](/use_cases/scaling_and_high_availability/forward_proxy) for HTTP/HTTPS explicit proxy.
* [Transparent Proxy](/use_cases/scaling_and_high_availability/transparent_proxy) for interception without client config.
* [Proxy Chain](/use_cases/scaling_and_high_availability/proxy_chain) for forwarding to a parent proxy.
# Transparent Proxy
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/transparent_proxy
Deploy SafeSquid in transparent proxy mode to intercept HTTP/HTTPS without client config for policy enforcement and SSL inspection.
# Transparent proxy intercepts traffic without client configuration
## Why transparent proxy is used
Uncontrolled direct internet access increases malware, data loss, and compliance risk. A secure web gateway (SWG) intercepts and examines web traffic so the organization can enforce policy and block threats. Explicit proxy requires every browser or application to be configured. Transparent proxy uses network-level redirection so traffic is sent to the proxy without endpoint configuration. Applications believe they connect directly to the destination. In reality, a router or firewall redirects traffic to SafeSquid, which then forwards it. This reduces deployment effort and ensures all HTTP/HTTPS traffic from the segment is inspected.
## Client scenario
Stark Tech has 200 employees. Stark Tech wants to provide internet services to the employees through WIFI. When the employees open their web browser, they're connected to a proxy server that manages all the network's communication.
Since this is a new employee, the proxy displays a web page in the browser asking the employee to agree to certain terms and conditions. If the employee accepts, then the proxy routes its traffic to the actual destination using a transparent proxy.
## Transparent proxy intercepts without application awareness
A transparent proxy (inline, intercepting, or forced proxy) sits between the client and the internet and redirects requests and responses. The application is not configured to use a proxy; the user is unaware. SafeSquid supports HTTP and HTTPS in transparent mode (HTTPS is SSL transparent mode). Servers see traffic as coming from the proxy.
## How SafeSquid transparent proxy works
![Diagram how SafeSquid proxy works]()
Bob is using a laptop in Stark Tech and wants to access internet services via Stark Tech's WIFI network.
Bob enable WIFI on his laptop.
Identified Stark tech WIFI network and tried to connect to Stark tech WIFI.
Now admin of the Stark tech receives an IP address of Bob (say 192.168.24.20) to check filtering policies, and serve traffic.
The traffic will come to the router and the router will send traffic to SafeSquid Secure web gateway with ports 80 and 443 respectively.
The **redirection rules on the SafeSquid Secure web gateway** will redirect traffic to SafeSquid Proxy with port 8080 and 8443 (SSL transparent) respectively (By enabling IP forwarding).
When Bob sets SafeSquid Proxy IP address 192.168.221.222 as a gateway, Bob will get access to the WIFI network and he can access all HTTP as well as HTTPS websites transparently.
SafeSquid transparent proxies are extremely versatile.
The following list contains the usefulness of SafeSquid transparent proxy to Bob.
1. **Proxy caches** create copies of the data stored on a server and serve the cached content to Bob. This reduces the strain on the web service by having the proxy provide the content instead of the service itself.
2. **Filtering proxies** prevents access to certain websites or web services. These are commonly implemented by organizations to prevent users from accessing resources that are unrelated or disruptive to the organization.
3. **Gateway proxies modify or block network traffic** based on certain policies. Locations that offer public Wifi often implement gateways that require users to register or accept an agreement before they can use the service.
## Prerequisites
1. Deploy SafeSquid Secure web gateway (SAB).
2. Enable SafeSquid SSL transparent facility on two ports, one is port 8081 for HTTP traffic and the other one is port 8433 for HTTPS traffic. Also, Enable SSL Inspection to control SSL traffic. If not enabled, refer to the document - How to Enable HTTPS Inspection
3. Redirect traffic from ports 80 and 443 to 8081 and 8443 respectively. The redirection can take place on the router if the router supports redirection.
4. Make sure the IP tables-persistent package is installed (to save IP table rules)
5. If your router only supports traffic forwarding then you should redirect traffic on the SafeSquid server using IP tables.
There is no separate "Transparent proxy" toggle anywhere in the console (confirmed live,
2026-08-28, build `2026.0627.1344.3`, across Application Setup, Accelerators, and Real time
content security) — enabling the SSL transparent facility and redirecting ports 80/443 to
8081/8443 above is the entire mechanism, not a preliminary step before some other switch.
## Benefits
1. Transparent proxies are an **unobtrusive way** to add features and functionality to a user's browsing experience.
2. **Enterprises experience greater control** over how their customers interact with their services by routing and modifying requests as they come in.
3. **Users interact with web services more easily** since their connections are seamlessly and invisibly passed through the proxy, leaving configuration to the service providers.
## Next steps
* [Forward Proxy](/use_cases/scaling_and_high_availability/forward_proxy) for explicit browser configuration.
* [TCP Proxy](/use_cases/scaling_and_high_availability/tcp_proxy) for non-HTTP protocols.
* [Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection) for SSL transparent mode.
# VPN Integration
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/vpn
Configure and manage VPN settings for SafeSquid Web Security Clients via Self-Service Portal, including FQDN setup and verification.
# Secure proxy access with WireGuard VPN
Directly exposing a SafeSquid proxy in the cloud to office or remote users is insecure. A dedicated, encrypted [WireGuard](https://www.wireguard.com/) VPN tunnel enables secure transport from enterprise networks or remote endpoints to the cloud without public exposure. This isolates the proxy, limits attack surface, and supports zero-trust connectivity with SafeSquid inspection and access control.
The following diagram depicts the VPN tunnel:
![WireGuard VPN tunnel and SafeSquid proxy architecture]()
## Prerequisites
**Cloud VPS (WireGuard + SafeSquid Host)**
* Ubuntu 24.04 LTS
* Public IPv4 address (e.g., 203.0.113.10)
* UDP port 51820 open in the cloud firewall
* Root or sudo privileges
* curl utility installed
**Office LAN or Remote Endpoint (WireGuard Client)**
* WireGuard installed
* Root or sudo-level access
* Access to client configuration files
* Internet connectivity to initiate outbound VPN tunnel
## Example cloud and office network topology
| Element | Address | Description |
| - | - | - |
| Public IP | 203.0.113.10 | External IP of Cloud VPS |
| Private Subnet | 10.0.0.0/24 | Internal cloud network |
| WireGuard Server / SafeSquid Proxy IP | 10.0.0.100 | Internal IP of cloud VPS running WireGuard and SafeSquid |
| VPN Tunnel Subnet | 10.66.66.1/24 | IP pool for WireGuard interfaces |
| Element | Address | Description |
| - | - | - |
| Office Subnet | 10.200.2.0/24 | Internal network of office LAN |
| WireGuard Client1 IP | 10.200.2.100 | Office client behind NAT, initiates VPN tunnel to cloud |
| VPN Tunnel Subnet | 10.66.66.2/24 | IP pool for WireGuard interfaces |
## Setup Procedure
### 1. Deploy WireGuard on cloud VPS
#### Download Setup Script
Fetch the automated installation script provided by SafeSquid to simplify WireGuard server setup.
```bash theme={null}
curl -O https://raw.githubusercontent.com/SafeSquid-Github/wireguard/refs/heads/main/wireguard-setup.sh
```
#### Execute Script
Run the script to initiate the WireGuard server configuration.
```bash theme={null}
bash wireguard-setup.sh --install
```
**During execution, provide:**
* Public IP: 203.0.113.10
* Port: 51820
* VPN Subnet: 10.66.66.0/24
* Peer Name: Client1
**Outputs:**
* Server config: **/etc/wireguard/wg0.conf**
* Client config: **/etc/wireguard/wg0-client-client1.conf**
### 2. Install WireGuard on the office endpoint
Install WireGuard on the office client to enable VPN connectivity.
```bash theme={null}
apt update
```
```bash theme={null}
apt install wireguard -y
```
This provides the necessary tools: wg for tunnel management and wg-quick for service control.
### 3. Configure office endpoint
#### Retrieve Client Configuration from Server
Display the client configuration generated by the cloud-side script.
```bash theme={null}
cat /etc/wireguard/wg0-client-client1.conf
```
Copy the output.
#### Save Configuration Locally
Create the required directory and apply the configuration on the office client.
```bash theme={null}
mkdir -p /etc/wireguard
```
```bash theme={null}
vim /etc/wireguard/wg0.conf
```
Paste the copied output from the previous step and save the file.
### 4. Set peer routing rules
#### On Cloud VPS
Modify the peer section in wg0.conf to allow routing to the office subnet and the client's tunnel IP.
**AllowedIPs = 10.66.66.2/32,10.200.2.0/24**
* 10.66.66.2/32: IP assigned to Client1
* 10.200.2.0/24: Entire office LAN behind Client1
#### On Office Client
Ensure routing towards the server and internal cloud subnet.
**AllowedIPs = 10.66.66.1/32,10.0.0.0/24**
* 10.66.66.1/32: Server tunnel endpoint
* 10.0.0.0/24: Internal cloud LAN accessible via VPN
### 5. Restart and enable services
#### Cloud VPS
Restart the interface to apply changes and enable persistence at boot.
```bash theme={null}
systemctl restart wg-quick@wg0
```
```bash theme={null}
systemctl enable wg-quick@wg0
```
#### Office Client
Restart the VPN tunnel with updated config and ensure service autostarts.
```bash theme={null}
wg-quick down wg0 && wg-quick up wg0
```
```bash theme={null}
systemctl enable wg-quick@wg0
```
### 6. Enable IP Forwarding
Edit the system control file to enable IPv4 packet forwarding.
```bash theme={null}
vim /etc/sysctl.conf
```
Uncomment or append:
```bash theme={null}
net.ipv4.ip_forward = 1
```
Apply the new setting:
```bash theme={null}
sysctl -p
```
### 7. Configure Routing
#### Cloud VPS Route
Route traffic destined for the office LAN via the WireGuard server's internal IP.
```bash theme={null}
ip route add 10.200.2.0/24 via 10.0.0.100
```
This ensures cloud workloads can reach the office network securely via VPN.
#### Office Router Configuration
Direct cloud-bound traffic from office LAN through Client1 (WireGuard client).
```bash theme={null}
ip route add 10.0.0.0/24 via 10.200.2.100
```
Guarantees LAN devices access cloud services routed through the VPN tunnel.
### 8. Enforce One-Way Tunnel Security
#### Block Unsolicited Traffic from Cloud to Office
Insert a firewall rule to drop unsolicited packets targeting the office subnet from the tunnel.
```bash theme={null}
iptables -A FORWARD -i wg0 -d 10.200.2.0/24 -j DROP
```
#### Persist Firewall Rules Across Reboots
Install the persistence utility and save the current rule set.
```bash theme={null}
apt install iptables-persistent -y
```
```bash theme={null}
netfilter-persistent save
```
## Validate VPN Connectivity
Confirm tunnel and office endpoint reachability.
```bash theme={null}
ping 10.66.66.2
```
```bash theme={null}
ping 10.200.2.100
```
Ensure reverse reachability to server and cloud LAN.
```bash theme={null}
ping 10.66.66.1
```
```bash theme={null}
ping 10.0.0.100
```
Display active peers and session statistics.
```bash theme={null}
wg show
```
## Post-Deployment Considerations
### 1. Multi-Client Deployment (Office & Remote Users)
If you plan to support **remote employees**, not just a single office, you must:
#### On the WireGuard Server:
* Generate separate peer configurations for each user or location
* Assign **unique tunnel IPs** to each client (e.g., 10.66.66.3/32, 10.66.66.4/32, etc.)
* Use a separate AllowedIPs per peer
Example server config for two clients:
```bash theme={null}
[Peer]
Office LAN
PublicKey = OFFICE_PUBLIC_KEY
AllowedIPs = 10.66.66.2/32,10.200.2.0/24
[Peer]
Remote User1
PublicKey = REMOTE_USER1_KEY
AllowedIPs = 10.66.66.3/32
```
#### On the Remote User
* Use AllowedIPs = 0.0.0.0/0 if they want **all their traffic** routed through the VPN
* Or use 10.0.0.0/24 if they only need access to internal cloud resources
### 2. Directory Server Integration
SafeSquid requires directory services (e.g., Active Directory) for identity-based policy enforcement. Ensure:
* Proxy initiates LDAP/LDAPS requests from its WireGuard tunnel IP
* Directory server accepts and routes responses to VPN subnet (e.g., 10.66.66.1)
This guarantees seamless identity resolution and policy mapping inside the VPN-secured cloud perimeter.
### 3. Proxy Cluster with Centralized Load Balancer
When deploying multiple SafeSquid instances as a cluster:
* Place a central load balancer between the office VPN ingress and the proxy layer
* The load balancer handles all incoming WireGuard traffic
* Distributes requests to proxy nodes for inspection and filtering
* Routes sanitized output to the internet
The architecture shown in maintains performance, simplifies scale-out, and centralizes VPN and external access controls.
![WireGuard load balancer and proxy layer architecture]()
### 4. Key Pair Management
Each peer device must independently generate cryptographic keys:
```bash theme={null}
wg genkey | tee privatekey | wg pubkey > publickey
```
* Only the public key is shared with the server
* The private key is stored securely on the client system
* Key rotation is recommended for long-term deployments
## Verification and Evidence
* **Interface Checks**: Confirm [WireGuard](https://www.wireguard.com/) interface is up (`wg show`). SafeSquid listens on the expected ports and is reachable over the VPN tunnel from clients.
* **Log Analysis**: VPN peer handshakes and traffic appear in system logs. SafeSquid access logs show requests from VPN client IPs when traffic is routed through the proxy.
* **Performance Validation**: From a client connected via VPN, browse through SafeSquid; traffic is inspected and policies apply. Load balancer (if used) distributes connections correctly.
## Next steps
* **[Integrations](/use_cases/integrations/integrations)** - enterprise integration with VPN for policy enforcement and secure remote access through SafeSquid SWG.
* **[Connect Your Client](/getting_started/client_configuration/connect_your_client)** - choose the right client routing method and prove that pilot traffic reaches SafeSquid before production rollout.
# WCCP
Source: https://docs.safesquid.com/use_cases/scaling_and_high_availability/wccp
Configure SafeSquid with Cisco WCCP to enable seamless transparent redirection, ensuring proxy-free client setups, load balancing, high availability, and scalable web traffic management.
# Plan WCCP Configuration for Transparent Redirection
## GOAL
Are you looking for Transparent redirection of traffic?
So, no user needs to set proxy settings in browsers.
Load balance traffic & scaling up?
Add more proxies to serve traffic and distribute traffic across multiple proxies.
Service assurance and high availability?
If one proxy fails, then other proxies should serve client's traffic.
If you are here for any of above challenges then SafeSquid with WCCP is a solution for you.
## What is WCCP?
Web Cache Communication Protocol (WCCP) is a Cisco-developed content-routing protocol that provides a mechanism to redirect traffic flows in real-time. It has built-in load balancing, scaling, fault tolerance, and service-assurance (failsafe) mechanisms.
## How it works with SafeSquid?
1. Enable WCCP support in routers. This can be done only if your router supports WCCP.
Ex: CISCO ASA routers.
2. Configure SafeSquid to interact with WCCP enabled routers under **Configure → Application Setup → WCCP**.
3. Configure end users to use WCCP enabled router as gateway.
The story is over. Now all your client's traffic will be transparently redirected to SafeSquid proxy by router and SafeSquid serves traffic.
The below picture will tell you whole story.
![SafeSquid and WCCP - Describes the communication between WCCP enabled Router and SafeSquid Proxy]()
WCCP Describes the communication between WCCP enabled Router and SafeSquid Proxy (Web-cache) to implement transparent redirection with scaling and fail-safe benefits.
1. Enable WCCP and transparent redirection support in Routers (Gateway).
2. Configure SafeSquid Proxies (Web-Caches) with WCCP enabled router information to work in coordination to participate in transparent redirection. SafeSquid proxies will send HERE I AM messages to routers and routers acknowledge with I SEE YOUR messages. After then all together will be ready to serve client's traffic. One of the SafeSquid proxies will become master & implement redirection rules and inform to router using REDIRECT ASSIGNMENT. Routers are ready to forward traffic as told by SafeSquid proxy.
3. Users are configured to use WCCP enabled router as gateway and router denies direct access to the internet and redirects incoming packets(traffic) to the group of SafeSquid proxies which are interacted with router using WCCP Protocol. SafeSquid proxies will serve traffic.
## Benefits
1. End users does not need to configure proxy in their browsers.
2. Fail Safe - If a proxy fails remaining proxies will handle the traffic
3. Scale Up - Add any number of proxies without disturbing environment
4. Load balance- Traffic will be distributed across all proxies.
## Next steps
* **[Transparent Proxy](/use_cases/scaling_and_high_availability/transparent_proxy)** - deploy SafeSquid in transparent proxy mode to intercept HTTP/HTTPS without client config for policy enforcement and SSL inspection.
* **[Choose an Architecture](/deployment/choose_an_architecture)** - decide where SafeSquid intercepts traffic — forward, transparent, TCP, reverse, or chained — and what each choice costs you in client configuration, coverage, and bypass risk.
# Configure HTTPS Inspection
Source: https://docs.safesquid.com/use_cases/ssl_inspection/configure_https_inspection
Prerequisites, certificate generation, enabling SSL inspection, client certificate import, bypass rules, and verification for SafeSquid HTTPS inspection.
# Configure SSL Inspection for HTTPS Traffic
Complete HTTPS inspection setup means you generate or import a Root CA certificate, enable inspection in SafeSquid, deploy the certificate to clients, and configure bypass rules for sensitive domains.
**Time to complete (Draft):** Plan **30–60 minutes** including client trust rollout; duration varies by fleet size and MDM maturity.
## Prerequisites
:::note
**Before You Start**
**SafeSquid side:**
* SafeSquid installed and licensed
* Access to [Self-Service Portal](https://key.safesquid.com) (for certificate generation)
* Access to SafeSquid Configuration Portal (`http://safesquid.cfg/`—embedded Rest UI interface built into SafeSquid; accessible only when your client uses the proxy, but NOT resolved by SafeSquid's DNS resolver—or `https://SERVER-IP:8443/` for direct access)
**Client side:**
* List of domains to bypass (banking, healthcare, SSL-pinned apps)
* Method to deploy Root CA to all clients (GPO, MDM, or manual)
* Administrative access to client systems (for certificate import)
* Pilot scope for rollout testing before enterprise-wide enablement
:::
## Why this preparation matters
* Certificate generation is required because clients must trust SafeSquid during interception.
* Bypass planning is required because some applications and destinations are not inspection-safe.
* Client deployment planning is required because one missed trust store can create a widespread certificate-warning incident.
* A pilot scope is required because HTTPS inspection can break business-critical traffic if enabled too broadly.
***
## Step 1: Generate or Import Root CA Certificate
You have three options for the Root CA certificate:
| **Option** | **When to Use** | **Pros** | **Cons** |
| - | - | - | - |
| **Self-Signed** | Testing, small deployments | Quick, no external dependencies | Not trusted by default, harder to revoke |
| **Enterprise CA (with passphrase)** | Production with existing CA | Centralized trust, auditable | Requires CA infrastructure |
| **Enterprise CA (without passphrase)** | Production, new passphrase | Same as above | Need to set new passphrase |
**Recommended:** Use self-signed for testing/pilot. Use enterprise CA for production.
Treat the passphrase and certificate material as recovery assets, not only as setup files.
***
### Generate Certificate in Self-Service Portal
1. **Log in** to the [Self-Service Portal](https://key.safesquid.com/)
![Self-Service Portal login]()
2. **Navigate to Certificate Management**
In the dashboard → find your deployment → click **Manage Certificate**
![Manage Certificate button]()
***
### Option A: Self-Signed Certificate
3. **Click Generate** (appears if no certificate exists yet)
![Generate button]()
4. **Select "General self-signed"** → **Enter passphrase** → **Generate**
:::caution
**Save Your Passphrase**
The passphrase is **non-recoverable**. Save it securely—you'll need it to reuse the certificate with different activation keys.
:::
![Generate self-signed certificate]()
5. **Click Close** to continue
![Certificate generated]()
***
### Option B: Enterprise CA with Existing Passphrase
3. **Click Regenerate** → **Upload enterprise CA files** → **Select "has passphrase"**
![Upload enterprise CA with passphrase]()
4. **Select CA certificate files** (`.crt` and `.key`)
![Select CA files]()
5. **Enter passphrase** → **Click "Validate private key"**
![Enter passphrase]()
6. **Select "Retain password"** → **Upload**
![Retain password and upload]()
7. **Click Close**
![Upload complete]()
***
### Option C: Enterprise CA Without Passphrase (Set New One)
3. **Click Regenerate** → **Upload enterprise CA** → **Select "does not have passphrase"**
![Upload enterprise CA without passphrase]()
4. **Select CA certificate files**
![Select CA files]()
5. **Enter new passphrase** → **Upload**
:::caution
**Save Your Passphrase**
This new passphrase is **non-recoverable**. Save it securely.
:::
![Enter new passphrase]()
6. **Click Close**
![Upload complete]()
***
### Download Certificate
7. **Enter passphrase** (if prompted) → **Click Download**
![Download certificate]()
![Certificate download]()
**Save this file** — you'll deploy it to all client systems.
***
## Step 2: Enable HTTPS Inspection in SafeSquid
### Access Configuration Portal
1. **Open SafeSquid interface** → **Click "Configure"**
![Click Configure]()
2. **Expand "Real Time Content Security"** in the sidebar
![Real Time Content Security]()
3. **Click "HTTPS Inspection"**
![HTTPS Inspection]()
***
### Enable Global HTTPS Inspection
4. **Click the "Global" tab** → **Click Edit** (pencil icon)
:::note
**Version Change**
SafeSquid versions after June 2017 have three tabs: **Global**, **Inspection Policies**, and **Bypass Policies**.
:::
![Global tab]()
![Click Edit]()
5. **Set "Enabled" to "True"** → **Save Policy**
![Enable HTTPS Inspection]()
![Save Policy]()
***
### Enable Inspection Policies
6. **Click "Inspection Policies" tab**
![Inspection Policies tab]()
7. **Verify default policies are enabled**
![Default policies]()
8. **Find "Enforce SSL scanning for all websites"** → **Click Edit**
![Edit enforce policy]()
9. **Set "Enabled" to "True"** → **Save Policy**
![Enable enforce policy]()
![Save Policy]()
***
### Save Configuration
10. **Click "Save Configuration"** (floppy disk icon, bottom left)
![Save Configuration]()
11. **Select "No"** (unless deploying to a cluster) → **Submit**
:::tip
**Cloud Config**
Select "Yes" only if:
* You're deploying the same config to multiple SafeSquid instances (cluster)
* All sections are fully configured for production
Otherwise, select "No" to save locally only.
:::
***
## Step 2 validation checkpoint
Before client rollout, confirm:
* global inspection is enabled
* the intended inspection policy is enabled
* cluster-save behavior matches the rollout plan
If this is wrong here, client trust deployment will not produce the expected inspection outcome.
***
## Step 3: Deploy Root CA to Clients
All clients must trust the SafeSquid Root CA to avoid certificate warnings.
### Windows (Chrome, Edge, IE)
**See detailed guide:** [Import Certificate into Chrome/IE](/use_cases/ssl_inspection/import_certificate_chrome_ie)
**Quick summary:**
1. Double-click the downloaded certificate
2. **Install Certificate** → **Local Machine** → **Next**
3. **Browse** → **Trusted Root Certification Authorities** → **OK**
4. **Next** → **Finish**
**For enterprise deployment:** Use GPO to push the certificate to all Windows machines.
***
### Firefox (All Platforms)
Firefox uses its own certificate store.
1. **Download the SafeSquid Root CA** (from Step 1)
2. **Open Firefox** → **Settings** → **Privacy & Security** → **Certificates** → **View Certificates**
3. **Authorities tab** → **Import**
4. **Select the SafeSquid certificate file**
5. **Check "Trust this CA to identify websites"** → **OK**
**Verify:**
* Visit `https://www.google.com` (via SafeSquid proxy)
* Click padlock → **More information** → **View Certificate**
* Certificate chain should show SafeSquid Root CA
***
### macOS
**Via System Keychain:**
1. Double-click the certificate file
2. **Add** → Enter admin password
3. **Open Keychain Access** → **System** keychain
4. Find SafeSquid certificate → **Get Info**
5. **Trust** section → **When using this certificate** → **Always Trust**
**For enterprise:** Use MDM (Jamf, Intune) to deploy to all Macs.
***
### Mobile Devices
**iOS/Android:**
* Deploy via MDM (Jamf, Intune, Workspace ONE)
* Manual: Email certificate → Open on device → Install
***
## Step 4: Validate inspection and bypass behavior
Run both of these tests before broad rollout:
1. **Positive inspection test**\
Visit a site that should be inspected and confirm the presented certificate is issued through the SafeSquid trust path.
2. **Negative bypass test**\
Visit a destination that should be bypassed and confirm the original site certificate remains intact.
Also confirm that a content-aware policy which could not previously see HTTPS traffic now triggers on an inspected flow.
***
## Step 5: Configure Bypass Policies
Bypass HTTPS inspection for:
* Banking and financial sites (compliance)
* Healthcare portals (HIPAA)
* SSL-pinned applications (will break otherwise)
* Government sites
***
### Enable Default Bypass Policy
1. **Click "Configure"** in SafeSquid interface
![Click Configure]()
2. **Click Search** (magnifying glass icon, top right)
![Click Search]()
3. **Type "BYPASS SSL INSPECTION"** → **Enter**
![Search bypass]()
4. **Click Edit** on the bypass policy
![Edit bypass policy]()
5. **Set "Enabled" to "True"** → **Save Policy**
![Enable bypass]()
![Save bypass policy]()
6. **Review and enable related bypass policies** (for banking apps, Windows Update, etc.)
![Review bypass policies]()
***
### Create Custom Bypass for Specific Domains
**Example:** Bypass HTTPS inspection for Dropbox.
![Custom bypass example]()
**Step 1: Define Request Type**
1. **Sidebar** → **Profiling Engine** → **Request Types** → **Add New**
![Request Types]()
![Add New]()
2. **Comment:** "Dropbox domains"\
**Match pattern:** `.*dropbox.*`\
**Smart TLD:** True
![Define Dropbox pattern]()
![Enable Smart TLD]()
**Step 2: Create Access Policy**
3. **Sidebar** → **Access Policies** → **Access Profiles** → **Add New**
![Access Profiles]()
4. **Comment:** "Bypass SSL for Dropbox"\
**Request Type:** Select "Dropbox domains" (from Step 1)\
**Added profiles:** Select "BYPASS SSL INSPECTION"
![Create bypass policy]()
5. **Save Policy**
![Save bypass]()
6. **Save Configuration** (floppy disk icon, bottom left)
**Test:** Upload/download files via Dropbox to verify bypass works.
***
## Verification
### Test HTTPS Inspection is Working
**On a client with SafeSquid Root CA installed:**
1. **Browse to** `https://www.google.com`
2. **Click padlock** → **Certificate** → **View**
3. **Verify:** Certificate chain shows SafeSquid Root CA as the issuer
4. **No certificate warnings** should appear
**Expected certificate chain:**
```text theme={null}
www.google.com (issued by SafeSquid Root CA)
└─ SafeSquid Root CA (self-signed or your enterprise CA)
```
***
### Test Bypass is Working
**On the same client:**
1. **Browse to a bypassed site** (e.g., banking site you added to bypass)
2. **Click padlock** → **Certificate** → **View**
3. **Verify:** Certificate shows the **original site's CA** (not SafeSquid)
**Expected:** Bypassed sites show their original certificates (e.g., DigiCert, Let's Encrypt).
***
### Check SafeSquid Logs
**On SafeSquid server:**
```bash theme={null}
tail -f /var/log/safesquid/extended/extended.log
```
**Expected for inspected sites:**
* Full URL logged (including path, not just domain)
* `200 OK` or similar HTTP status
**Expected for bypassed sites:**
* Only `CONNECT` method logged
* No detailed path information
***
## Troubleshooting
| **Issue** | **Likely Cause** | **Fix** |
| - | - | - |
| Certificate warnings on all HTTPS sites | Root CA not installed on client | Install SafeSquid Root CA in Trusted Root store (see Step 3) |
| Firefox shows warnings, Chrome works | Firefox uses separate cert store | Import certificate into Firefox separately (see above) |
| Banking/healthcare sites broken | HTTPS inspection enabled, no bypass | Add sites to bypass policy (Step 4) |
| Mobile apps not working | SSL pinning | Add app's domains to bypass policy |
| "NET::ERR\_CERT\_AUTHORITY\_INVALID" | Root CA not trusted | Verify certificate installed in **Trusted Root Certification Authorities** (not Intermediate) |
| Inspection works, then stops | SafeSquid restart cleared config | Re-save configuration; check if config was saved to cloud |
| Some sites work, others don't | Partial bypass or incorrect policy | Review bypass policies; check logs for CONNECT vs full requests |
**Still not working?**
1. **Verify HTTPS Inspection is enabled:**
* Configuration Portal → Real time content security → HTTPS Inspection → Global = True
2. **Check certificate is deployed:**
* Windows: Run `certmgr.msc` → Trusted Root Certification Authorities → Certificates
* Firefox: Settings → Privacy & Security → Certificates → View Certificates → Authorities
* macOS: Keychain Access → System → Find SafeSquid cert
3. **Test with curl:**
```bash theme={null}
# Should work without cert if bypass is correct:
curl --proxy http://SAFESQUID-IP:8080 https://www.google.com
```
4. **Check SafeSquid logs:**
```bash theme={null}
tail -50 /var/log/safesquid/native/safesquid.log
grep -i "ssl\|cert\|handshake" /var/log/safesquid/native/safesquid.log
```
***
## Source register
| Topic | Status | Source |
| - | - | - |
| Root CA via Self-Service Portal | **Confirmed** | This guide, [Self-Service Portal](/architecture/interface/self_service_portal) |
| Enable inspection UI path | **Confirmed** | Steps in this guide |
| Client trust stores (Windows, Firefox, macOS) | **Confirmed** | This guide, [Import Certificate Chrome/IE](/use_cases/ssl_inspection/import_certificate_chrome_ie) |
***
## Next Steps
1. **[Authentication](/use_cases/authentication/authentication)** — Enable user-aware policies (SSL Inspection must be working first)
2. **[Access Restriction](/use_cases/access_restriction/access_restriction)** — Configure URL filtering (now works on HTTPS)
3. **[Data Leakage Prevention](/use_cases/data_leakage_prevention/data_leakage_prevention)** — Scan HTTPS uploads for sensitive data
4. **[Troubleshooting](/troubleshooting/troubleshooting)** — SSL-specific issues and diagnostics
**Related:**
* [Self-Service Portal](/architecture/interface/self_service_portal) — Manage certificates
* [Import Certificate into Chrome/IE](/use_cases/ssl_inspection/import_certificate_chrome_ie) — Detailed Windows guide
# Import Certificate into Chrome or Internet Explorer
Source: https://docs.safesquid.com/use_cases/ssl_inspection/import_certificate_chrome_ie
Step-by-step import of SafeSquid SSL certificate into Chrome or Internet Explorer for HTTPS inspection trust.
# Import SafeSquid Root CA into Chrome or Internet Explorer
Chrome, Edge, and Internet Explorer use the Windows certificate store. Follow this guide to import the SafeSquid Root CA into **Trusted Root Certification Authorities** so HTTPS inspection works without certificate warnings.
**Time to complete:** 2-5 minutes per machine
## Problem statement
HTTPS inspection fails visibly on Windows clients if the SafeSquid Root CA is not trusted. The result is certificate warnings, failed browsing, and a rollout that looks broken even when the proxy-side configuration is correct.
:::tip
**Automated Deployment**
For enterprise environments, deploy the certificate via **Group Policy (GPO)** instead of manual installation:
1. Copy certificate to `\\domain.com\SYSVOL\domain.com\Policies\`
2. GPO → Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies → Trusted Root Certification Authorities
3. Import → Select SafeSquid certificate → Apply
:::
:::note
**Firefox Users**
Firefox uses its own certificate store and ignores the Windows trust store. See [Import certificate into Firefox](/use_cases/ssl_inspection/configure_https_inspection#firefox-all-platforms).
:::
***
## Prerequisites
:::note
**Before You Start**
* SafeSquid Root CA certificate downloaded (from [Self-Service Portal](https://key.safesquid.com) or SafeSquid Configuration Portal)
* Windows machine with administrative privileges
* Chrome, Edge, or Internet Explorer installed
* SafeSquid HTTPS inspection already enabled on the proxy side
:::
***
## Import Steps
### 1. Open the Certificate File
Double-click the downloaded SafeSquid certificate file (usually `safesquid.crt` or `safesquid.cer`).
![Opening SafeSquid certificate]()
***
### 2. Click "Install Certificate"
![Install Certificate button]()
***
### 3. Select Store Location
Choose **"Local Machine"** (for all users on this computer) or **"Current User"** (for your account only).
**Recommended:** Local Machine (requires admin rights, applies to all users)
Click **Next**.
![Store location selection]()
***
### 4. Select Certificate Store
Click **"Browse"** to select the certificate store.
![Browse certificate store]()
***
### 5. Choose "Trusted Root Certification Authorities"
**Important:** Select **"Trusted Root Certification Authorities"** (NOT "Intermediate Certification Authorities").
Click **OK**.
![Select Trusted Root Certification Authorities]()
***
### 6. Continue with Import
Click **Next** to continue.
![Continue import]()
***
### 7. Finish Import
Click **Finish** to complete the import.
![Finish import]()
***
### 8. Confirm Success
A confirmation message appears: **"The import was successful."**
Click **OK**.
![Import successful confirmation]()
![Import complete]()
***
## Verify Installation
### Test in Chrome/Edge
1. **Open Chrome or Edge**
2. **Browse to** `https://www.google.com` (via SafeSquid proxy)
3. **Click the padlock** in the address bar → **Connection is secure** → **Certificate**
4. **Verify:** Certificate chain shows SafeSquid Root CA as the issuer
**Expected:** No certificate warnings, padlock shows secure connection.
***
### Verify Certificate is in Trust Store
1. **Press Windows + R** → Type `certmgr.msc` → **Enter**
2. **Expand** "Trusted Root Certification Authorities" → **Certificates**
3. **Find** "SafeSquid" (or your organization name) in the list
**Expected:** SafeSquid certificate appears with expiry date and issuer information.
## Operational note
For enterprise rollouts, GPO or another managed certificate-deployment path is safer than manual import because it reduces inconsistency across users and machines.
***
## Troubleshooting
| **Issue** | **Likely Cause** | **Fix** |
| - | - | - |
| Still seeing certificate warnings | Certificate installed in wrong store | Verify certificate is in **Trusted Root Certification Authorities** (not Intermediate) |
| "Windows cannot access the file" | No admin privileges | Right-click certificate → **Run as administrator** |
| Import succeeds but warnings persist | Browser cache | Clear browser cache and restart browser: `chrome://settings/clearBrowserData` |
| Certificate not visible in certmgr | Installed for Current User instead of Local Machine | Re-install, select "Local Machine" in step 3 |
| Some sites work, others don't | HTTPS Inspection not enabled or partial bypass | Check SafeSquid Configuration Portal → HTTPS Inspection → Global = True |
**Still not working?**
1. **Restart browser completely** (close all windows)
2. **Check proxy settings:**
* Chrome: `chrome://net-internals/#proxy`
* Edge: `edge://net-internals/#proxy`
3. **Verify SafeSquid HTTPS Inspection is enabled:**
* Navigate to SafeSquid Configuration Portal
* Real time content security → HTTPS Inspection → Global → Enabled = True
***
## Source register
| Topic | Status | Source |
| - | - | - |
| Windows Trusted Root import path | **Confirmed** | This guide, `certmgr.msc` |
| GPO deployment (tip) | **Draft** | Standard Windows CA deployment pattern; validate against org GPO practice |
***
## Next Steps
1. **[Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection)** — Complete setup guide (if you haven't enabled inspection yet)
2. **[Import certificate into Firefox](/use_cases/ssl_inspection/configure_https_inspection#firefox-all-platforms)** — Firefox uses separate trust store
3. **Deploy to all clients:**
* **Windows enterprise:** Use GPO (see tip at top of page)
* **macOS:** Use MDM or manual Keychain import
* **Mobile:** Use MDM or manual installation
4. **Verify your setup** — Confirm proxy and SSL Inspection are working
**Related:** [SSL Inspection Overview](/use_cases/ssl_inspection/ssl_inspection) | [Troubleshooting](/troubleshooting/troubleshooting)
# SSL Inspection
Source: https://docs.safesquid.com/use_cases/ssl_inspection/ssl_inspection
Configure HTTPS inspection in SafeSquid to decrypt and analyze encrypted traffic for web security, malware detection, and policy enforcement.
## Problems addressed
HTTPS hides URLs, payloads, and uploads from a proxy that only sees tunnel metadata. Malware delivery, phishing pages, and data exfiltration over TLS evade policy without deliberate inspection and trust deployment.
## Outcomes operators expect
* Policy on full HTTPS URLs and content where inspection runs.
* Malware and DLP controls on encrypted flows when licensed and configured.
* Selective bypass for pinned apps, regulated sites, and privacy policy carve-outs.
## Technical scope
SafeSquid's documented TLS support covers **TLS 1.0 through TLS 1.3**. This matters because modern threats overwhelmingly use encrypted web sessions. A proxy that cannot inspect current TLS traffic leaves the main enterprise web path opaque.
## Advantages vs “TLS blind proxying”
Inspection restores Layer 7 visibility on the proxy path at the cost of **client trust** in the SafeSquid root CA and operational work for bypass rules. **Comparative performance or legal suitability vs other vendors:** **Not SSOT-backed here**—see [What is SafeSquid SWG?](/architecture/what_is_safesquid_swg).
## Acquire, deploy, use
Follow [Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection): Root CA, enable inspection, deploy trust to clients, define bypasses, verify.
HTTPS inspection (SSL/TLS interception) allows SafeSquid to decrypt, inspect, and re-encrypt HTTPS traffic. Without inspection, encrypted sessions remain a blind spot for content-level malware, phishing, and data-leakage policy.
## When to Use SSL Inspection
| Enable SSL Inspection When | Use Bypass Instead |
| - | - |
| Enforcing web security policies on HTTPS | Banking and financial sites (compliance) |
| Scanning encrypted downloads for malware | Healthcare portals (HIPAA) |
| DLP on HTTPS uploads (file sharing, webmail) | SSL-pinned mobile apps (cannot inspect) |
| Application control (identify SaaS apps in HTTPS) | Government sites (security requirements) |
| URL filtering on encrypted sites | Personal/sensitive user traffic (privacy policy) |
:::tip
**Selective inspection**
Bypass policies can exclude sensitive categories while inspection remains enabled for the rest of traffic.
:::
***
## Why HTTPS Inspection Matters
**The problem**
* **Draft:** Most enterprise web traffic is HTTPS; measure with local metrics if a percentage is required for a board narrative.
* Encrypted traffic hides malicious payloads, phishing attempts, and data exfiltration from content-aware policy.
* Without inspection, the proxy sees tunnel metadata (for example SNI), not full URLs or bodies.
**What HTTPS Inspection Enables:**
* URL filtering on HTTPS sites
* Malware scanning of encrypted downloads
* Data Loss Prevention (DLP) on HTTPS uploads
* Application control (detect Google Drive, Dropbox, etc. in HTTPS traffic)
* Content security (block ransomware downloads, malicious scripts)
**Operationally important SSL capabilities from product knowledge:**
* real-time SSL certificate validation against remote servers
* automatic certificate-chain repair through AIA fetching for broken chains
* continuous updates to the trusted root CA list
These capabilities matter because HTTPS inspection is not only about decryption. It also depends on accurate trust evaluation of remote servers.
***
## How It Works
1. **Client → SafeSquid:** Browser connects to SafeSquid using SafeSquid's certificate
2. **SafeSquid → Origin:** SafeSquid creates a separate TLS connection to the destination
3. **Inspection:** SafeSquid sees the decrypted content and applies policies
4. **Re-encryption:** SafeSquid re-encrypts and forwards to the destination
**Result:** Traffic remains encrypted end-to-end, but SafeSquid can inspect the content.
***
## Important considerations
### Bypass is Required For:
* **SSL-pinned applications** (mobile apps, some desktop software)
* **Banking and financial sites** (compliance/privacy)
* **Healthcare portals** (HIPAA compliance)
* **Government sites** (security requirements)
SafeSquid allows bypass rules to exclude specific domains from inspection.
### Client Trust Required:
All client browsers and applications must trust the SafeSquid Root CA certificate. Without trust, users see certificate warnings on every HTTPS site.
**Deploy the Root CA to:**
* Windows certificate store (for Chrome, Edge, IE)
* Firefox certificate store (separate)
* macOS Keychain (for Safari, system-wide)
* Mobile devices (via MDM)
### Production safety
* Do not enable broad inspection in production before planning certificate deployment and bypass scope.
* Test certificate-pinned applications, regulated destinations, and business-critical SaaS before rollout.
* If inspection is introduced without a pilot, certificate warnings and application failures can create a self-inflicted outage.
***
## Configuration Guides
### [Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection)
**Complete setup guide covering:**
* Generate or import Root CA certificate (Self-Service Portal)
* Enable HTTPS inspection in SafeSquid
* Configure bypass policies for sensitive domains
* Deploy Root CA to clients (Windows, macOS, Firefox, mobile)
* Verify inspection is working
**Start here** for first-time SSL Inspection setup.
***
### [Import Certificate into Chrome/IE](/use_cases/ssl_inspection/import_certificate_chrome_ie)
**Step-by-step walkthrough** for importing the SafeSquid Root CA into the Windows Trusted Root Certification Authorities store (used by Chrome, Edge, and Internet Explorer).
**Use this** after enabling HTTPS inspection to eliminate browser certificate warnings on Windows clients.
***
## Quick Start Checklist
1. ✅ **[Generate Root CA](/use_cases/ssl_inspection/configure_https_inspection#generate-certificate-in-self-service-portal)** in Self-Service Portal
2. ✅ **[Enable HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection#step-2-enable-https-inspection-in-safesquid)** in SafeSquid Configuration Portal
3. ✅ **[Configure bypass policies](/use_cases/ssl_inspection/configure_https_inspection#step-5-configure-bypass-policies)** for banking/healthcare sites
4. ✅ **Deploy Root CA** to all clients:
* [Windows (Chrome/IE)](/use_cases/ssl_inspection/import_certificate_chrome_ie)
* [Firefox](/use_cases/ssl_inspection/configure_https_inspection#firefox-all-platforms)
* macOS via MDM or Keychain
* Mobile via MDM
5. ✅ **[Verify](/use_cases/ssl_inspection/configure_https_inspection#verification)** inspection is working (check padlock icon, test bypass)
## Verification and validation
After enabling SSL inspection, confirm all of the following:
* the client trusts the SafeSquid Root CA
* inspected sites show the expected SafeSquid-issued certificate path
* bypassed destinations remain uninspected
* blocked or scanned HTTPS transactions now trigger the intended policy outcomes
* logs show SSL-related decisions such as validation or decryption behavior where expected
Run both positive and negative tests:
* **Positive test:** browse to a site that should be inspected and confirm content-aware policy can now see it
* **Negative test:** browse to a bypassed site and confirm the original site certificate remains intact
## Troubleshooting
**Symptom:** Users see certificate warnings on normal HTTPS sites.\
**Likely cause:** The SafeSquid Root CA is not trusted on the client.\
**Isolation:** Inspect the presented certificate chain and confirm whether the SafeSquid CA is installed.\
**Remediation:** Deploy the CA correctly to the client trust store.\
**Retest:** Reload the same inspected site and confirm the warning disappears.
**Symptom:** A business-critical app breaks only when inspection is enabled.\
**Likely cause:** Certificate pinning, protocol sensitivity, or an application-specific trust expectation.\
**Isolation:** Compare behavior with a narrow bypass for the application domain.\
**Remediation:** Keep a tightly scoped bypass if inspection is not technically viable for that app.\
**Retest:** Confirm the application works and that unrelated traffic is still inspected.
**Symptom:** HTTPS traffic passes, but content-aware controls still do not trigger.\
**Likely cause:** Inspection is not actually active on that flow, or the destination is still bypassed.\
**Isolation:** Check the active SSL policy path, the certificate behavior, and the matching bypass rules.\
**Remediation:** Correct the inspection scope.\
**Retest:** Repeat the same policy-triggering transaction and confirm the control fires.
***
## Common Questions
**Q: Will users see certificate warnings?**\
A: Yes, until you deploy the SafeSquid Root CA to their devices. Once trusted, no warnings appear.
**Q: Can I inspect only some sites and not others?**\
A: Yes, use bypass policies to exclude specific domains (e.g., banking sites).
**Q: What about mobile apps that use certificate pinning?**\
A: Add those apps' domains to the bypass list. They cannot be inspected.
**Q: Does this slow down HTTPS traffic?**\
**A (Draft — pending engineering SSOT):** Inspection adds CPU-bound TLS work. [Hardware Sizing](/deployment/hardware_sizing) covers **AES-NI** and sizing. Do **not** treat fixed millisecond figures as verified product facts until CTO publishes benchmarks in-docs.
***
## Source register
| Topic | Status | Source |
| - | - | - |
| HTTPS inspection workflow (client → SafeSquid → origin) | **Confirmed** | [Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection), this page |
| Client trust requirement for Root CA | **Confirmed** | This page, certificate import guides |
| PCI / SOC framing as compliance context | **Context only** | Helpful for risk framing, not a compliance guarantee |
## Next Steps
1. **[Configure HTTPS Inspection](/use_cases/ssl_inspection/configure_https_inspection)** — Complete setup guide
2. **[Authentication](/use_cases/authentication/authentication)** — Enable user-aware policies after SSL Inspection
3. **[Access Restriction](/use_cases/access_restriction/access_restriction)** — Configure URL filtering (now works on HTTPS)
4. **[Data Leakage Prevention](/use_cases/data_leakage_prevention/data_leakage_prevention)** — Scan HTTPS uploads for sensitive data
# Upgrade Ubuntu
Source: https://docs.safesquid.com/use_cases/upgrade/os_upgrade
Non-interactive upgrade of SafeSquid SWG from Ubuntu 20.04 LTS to 24.04 LTS: prerequisites, OS upgrade, DNS, Netplan, and verification.
# Upgrade Ubuntu 20.04 to 24.04 for SafeSquid compatibility
## OS upgrade scope and procedure
Use this step-by-step, non-interactive procedure to upgrade the SafeSquid Secure Web Gateway system from Ubuntu 20.04 LTS to Ubuntu 24.04 LTS, then to SafeSquid version 2025.1001.1232.3.
The steps ensure **compatibility**, **security**, and **service continuity** for SafeSquid deployments running in production environments.
***
## Why This Upgrade Is Required
### **1. SafeSquid Compatibility Requirements for** The latest release:
**SafeSquid Secure Web Gateway 2025.1001.1232.3**
introduces the following **minimum system requirements**:
* **Linux Kernel:** 6.8 or higher
* **glibc:** 2.39 or higher
Ubuntu **20.04 LTS** includes:
* Kernel up to **5.15**
* glibc **2.31**
These versions are **too old** for SafeSquid verion 2025.1001.1232.3, which requires newer kernel APIs and library functions available only in **Ubuntu 24.04 LTS**.
Attempting to install the new version on 20.04 will cause dependency and runtime failures.
***
### **2. Ubuntu 20.04 End of Life (EoL)**
Ubuntu **20.04 LTS** reaches **End of Standard Support in April 2025**.
After this date:
* No further security patches or OS updates will be provided
* Package repositories may become unavailable
* Vulnerabilities and compatibility issues will accumulate
Upgrading to **Ubuntu 24.04 LTS (Noble Numbat)** ensures long-term security and system support until **2034** under extended maintenance.
***
## Important Pre-Requisite
1. Login as root
You **must be logged in as the root user** (or have full administrative privileges using `sudo`) to execute all commands in this procedure.
Upgrading the operating system and SafeSquid involves modifying system-level files, packages, and services that require **root-level access**.
To switch to the root user, run:
```bash theme={null}
sudo -i
```
Verify root access by checking the prompt changes to:
```bash theme={null}
root@hostname:~#
```
If you see this, you can proceed safely with the upgrade process
***
1. **Free Storage in `/root`:**
The `/root` partition must have **more than 15 GB of free space** to accommodate upgrade files, temporary packages, and extracted data.
Check available space:
```bash theme={null}
df -h
```
**Expected output for sufficient free space:**
```text theme={null}
Filesystem Size Used Avail Use% Mounted on
/dev/mapper/vgsab--ubantu-root 20G 4.0G 16G 20% /
tmpfs 392M 900K 391M 1% /run
tmpfs 2.0G 0 2.0G 0% /dev/shm
tmpfs 5.0M 0 5.0M 0% /run/lock
/dev/mapper/vgsab--ubantu-home 24G 48K 23G 1% /home
/dev/mapper/vgsab--ubantu-var+cache+safesquid 7.0G 24K 6.7G 1% /var/cache/safesquid
/dev/mapper/vgsab--ubantu-opt+safesquid 3.7G 48M 3.5G 2% /opt/safesquid
/dev/mapper/vgsab--ubantu-var+lib+safesquid 7.5G 4.3G 2.8G 61% /var/lib/safesquid
/dev/mapper/vgsab--ubantu-var+www+safesquid 14G 24K 14G 1% /var/www/safesquid
/dev/sda1 1.9G 193M 1.6G 11% /boot
/dev/mapper/vgsab--ubantu-usr+local+safesquid 3.7G 9.2M 3.5G 1% /usr/local/safesquid
/dev/mapper/vgsab--ubantu-var+log+safesquid 96G 885M 90G 1% /var/log/safesquid
/dev/mapper/vgsab--ubantu-var+db+safesquid 73G 1.1M 69G 1% /var/db/safesquid
/dev/ram1 60M 3.0M 54M 6% /tmp/safesquid
tmpfs 392M 8.0K 392M 1% /run/user/0
```
> Note: If free space is below 15 GB, clean up unnecessary files or resize the /root partition before proceeding.
***
1. Check Current OS Version
**Purpose:**
This step confirms the current OS version before proceeding, ensuring the system is actually running **Ubuntu 20.04**. The upgrade procedure must be followed sequentially, so the version check prevents applying incorrect upgrade steps.
**Command:**
```bash theme={null}
lsb_release -a
```
**Expected Output:**
```text theme={null}
description: Ubuntu 20.04 LTS
```
If the version shows **18.04**, perform an upgrade to **20.04** first before continuing.
***
## Step 1: Upgrade Ubuntu from 20.04 → 24.04 (Two-Step Process)
Ubuntu LTS upgrades must be done **sequentially** (20.04 → 22.04 → 24.04).
This ensures all intermediate packages, kernel modules, and libraries are properly migrated.
***
### **Phase 1 – Upgrade from 20.04 to 22.04**
**Why:**
* Ubuntu cannot skip LTS versions directly
* This step ensures that kernel, libc, and dependent packages are incrementally upgraded to versions compatible with 22.04
**Commands:**
```bash theme={null}
apt autoclean -y && apt autoremove -y
apt-get clean
apt update && apt upgrade -y
do-release-upgrade -f DistUpgradeViewNonInteractive
```
* `apt autoclean` removes obsolete package files
* `apt autoremove` clears unused dependencies to prevent clutter
* `apt-get clean`: Removes cached packages to free space and avoid conflicts
* `apt update && apt upgrade -y`: Ensures the system is fully patched before upgrading
* `do-release-upgrade -f DistUpgradeViewNonInteractive`: Initiates the upgrade to Ubuntu 22.04 in non-interactive mode,
This upgrades Ubuntu to the next LTS version **without stopping to ask questions**, ensuring a fully automated process suitable for remote servers or critical systems.
**After completion:**
```bash theme={null}
reboot
```
Reboot is required to boot into the new kernel and load updated system libraries.
***
### **Phase 2 – Upgrade from 22.04 to 24.04**
**Why:**
This phase upgrades the system to the final target OS, **Ubuntu 24.04 LTS**, which provides:
* Kernel **6.8**
* glibc **2.39**
* Modern dependencies required by SafeSquid 2025.1001.1232.3
**Commands:**
```bash theme={null}
apt autoclean -y && apt autoremove -y
apt-get clean
apt update && apt upgrade -y
do-release-upgrade -f DistUpgradeViewNonInteractive
```
* `apt autoclean` removes obsolete package files
* `apt autoremove` clears unused dependencies to prevent clutter
* **`apt-get clean`:** Removes all cached package files from `/var/cache/apt/archives` to free up space and prevent conflicts
* **`apt update && apt upgrade -y`:** Updates the package index and upgrades all installed packages to the latest available versions automatically
* **`do-release-upgrade -f DistUpgradeViewNonInteractive`:** Initiates the Ubuntu OS upgrade to the next release in a fully automated, non-interactive mode
***
After the upgrade completes:
```bash theme={null}
apt autoclean -y && apt autoremove -y
reboot
```
* `apt autoclean` removes obsolete package files
* `apt autoremove` clears unused dependencies to prevent clutter
* Reboot ensures the system loads the new kernel and environment
***
## Step 2: Update BIND Configuration
**Why:**
SafeSquid, during its operation, creates or modifies `/etc/bind/named.conf.appliance.options`, which automatically add options `dnssec-validation` and TTL limits.
These options cause conflicts when starting bind9 service.
The reason SafeSquid does this is to **ensure Active Directory (AD) integration works smoothly**, as these options control DNS validation and caching behavior, which are critical for resolving AD domain controllers and Kerberos services.
**Commands:**
```bash theme={null}
vim /etc/bind/named.conf.options
```
Comment the following lines:
```bash theme={null}
// dnssec-validation auto;
// max-cache-ttl 300;
// max-ncache-ttl 300;
```
**Save and restart BIND:**
```bash theme={null}
systemctl restart bind9
```
This restarts the DNS service with updated configuration.
***
## Step 3: Rename `msktutil` Binary
**Why:**`msktutil` is a tool used for managing machine accounts in Active Directory.
SafeSquid or system processes may attempt to use the existing `msktutil` binary, which was built for Ubuntu 20.04.
On Ubuntu 24.04, this older binary can have **dependency issues** with newer Kerberos libraries.
**Command:**
```bash theme={null}
mv /usr/local/bin/msktutil /usr/local/bin/msktutil_
```
***
## Step 4: Update Netplan Configuration
**Why:**
During OS upgrades, network settings may change or revert.
Updating Netplan ensures the system uses the **local DNS resolver (127.0.0.1)**, allowing proper DNS resolution through your AD-integrated BIND server.
**Commands:**
```bash theme={null}
vim /etc/netplan/00-installer-config.yaml
```
Add or modify the nameserver section:
```yaml theme={null}
nameservers:
addresses: [127.0.0.1]
```
**Apply the configuration:**
```bash theme={null}
netplan apply
```
This ensures DNS resolution functions correctly with BIND post-upgrade.
***
## Step 5: Upgrade SafeSquid Application
**Why:**
Once the OS environment is compatible (kernel 6.8, glibc 2.39), install the new SafeSquid version.
The latest release provides updated filtering features, enhanced TLS handling, and improved performance.
**Commands:**
```bash theme={null}
wget -P /usr/local/src https://downloads.safesquid.com/appliance/unstable/safesquid-2025.1001.1232.3-swg-standard.tar.gz
tar -xzf /usr/local/src/safesquid-2025.1001.1232.3-swg-standard.tar.gz -C /usr/local/src
/usr/local/src/_mkappliance/installation/setup.sh
```
**Check status:**
```bash theme={null}
systemctl status safesquid.service
```
**Enable at boot:**
```bash theme={null}
systemctl enable safesquid
```
This ensures SafeSquid starts automatically after system reboots.
***
## Step 6: Post-Upgrade Cleanup and Verification
**Why:**
Cleaning residual packages prevents storage bloat and ensures a consistent, stable environment.
Verification confirms that both OS and SafeSquid versions are upgraded successfully.
**Commands:**
```bash theme={null}
apt autoclean -y && apt autoremove -y
reboot
```
After reboot, verify OS versions:
```bash theme={null}
lsb_release -a
```
**Expected:**
```text theme={null}
description: Ubuntu 24.04 LTS
```
***
Verify Installed SafeSquid Version.
```bash theme={null}
ls -rlt /opt/safesquid/bin/safesquid
```
**Expected:**
```bash theme={null}
lrwxrwxrwx 1 ssquid root 39 Oct 13 22:22 /opt/safesquid/bin/safesquid -> safesquid-2025.1001.1232.3-swg-standard
```
## Next steps
* **[Upgrade SafeSquid](/use_cases/upgrade/version_upgrade)** - upgrade SafeSquid SWG via Web GUI: prerequisites, cleanup, and applying the new tarball package.
* **[Troubleshooting](/troubleshooting/troubleshooting)** - comprehensive diagnostic procedures and resolution guides for common SafeSquid proxy issues, connection failures, and configuration problems.
# Upgrade SafeSquid
Source: https://docs.safesquid.com/use_cases/upgrade/version_upgrade
Upgrade SafeSquid SWG via Web GUI: prerequisites, cleanup, and applying the new tarball package.
# Upgrade SafeSquid application via Web GUI
## Choose the upgrade path
There are two upgrade paths, and they answer different problems. Run the OS upgrade first
where both are due — a SafeSquid version that needs newer kernel or library versions will
not install cleanly on an end-of-life base.
| Path | Use when | Guide |
| - | - | - |
| Version upgrade | The OS is current and only the SafeSquid application needs updating | This page |
| OS upgrade | The base OS is end-of-life, or lacks versions a newer SafeSquid requires | [Upgrade Ubuntu](/use_cases/upgrade/os_upgrade) |
## Version upgrade scope and procedure
SafeSquid SWG upgrade is a newer version of the SafeSquid that offers a significant change or major improvement over your current version. Upgrade your SafeSquid to the latest version which may consists of bugfixes and enhancements. When you upload latest tarball of SafeSquid SWG from WebGUI monit service will automatically restart the SafeSquid service.
## Prerequisites
Monit service should be running and started on your SafeSquid server, you can check it by using below command from your SafeSquid server
```bash theme={null}
pidof monit
```
If you did not find pid of monit, run below command to Start the Monit service
```bash theme={null}
/etc/init.d/monit start
```
The partition size of /tmp/safesquid used must be less than 4%, you can check it by using below command
```bash theme={null}
df -kh
```
After executing the command last line of the output will be similar as shown below
```bash theme={null}
/dev/ram1 62M 1.3M 58M 3% /tmp/safesquid
```
Check the highlighted number which shows the actual usage, if it is greater than 4%, then remove the files from the folder /tmp/safesquid
You can remove files from /tmp/safesquid by going to that folder location using the command:
```bash theme={null}
cd /tmp/safesquid
```
Further delete all the files from the folder by using the command:
```bash theme={null}
rm -rf *
```
## Steps
### [Access the SafeSquid User Interface](/architecture/interface/configuration_portal)
![your current version of safesquid will be shown in the right hand bottom corner in the SafeSquid interface]()
### Go to Support Page
![clicking on support]()
### Go to upgradation
:::note
Download the latest SafeSquid SWG tarball from here and save into your machine.
:::
![clicking on upgradation]()
### Select new tarball
Select the latest SafeSquid tarball downloaded and saved in your machine before.
![uploading a new tarball file]()
![selecting the tarball file from the pc]()
![you can see the browsed tarball beside browse button]()
Click on upload button to upload new tar file.
![clicking on upload button to upload]()
## Testing Upgradation
You can see upgraded version number of SafeSquid SWG at the bottom right corner of interface.
![test if the newer version of the safesquid is showing in the bottom right hand corner]()
## Where should I get the latest version of SafeSquid to upgrade?
You can download **SafeSquid SWG for Windows** package from - [http://downloads.safesquid.net/SWG/windows/setup\_safesquid\_swg\_latest.exe](http://downloads.safesquid.net/SWG/windows/setup_safesquid_swg_latest.exe)
You can download **SafeSquid SWG for Linux** package from - [http://downloads.safesquid.net/appliance/binary/safesquid\_latest.tar.gz](http://downloads.safesquid.net/appliance/binary/safesquid_latest.tar.gz)
## Next steps
* **[Upgrade Ubuntu](/use_cases/upgrade/os_upgrade)** - non-interactive upgrade of SafeSquid SWG from Ubuntu 20.04 LTS to 24.04 LTS: prerequisites, OS upgrade, DNS, Netplan, and verification.
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# Redirect One Website to Another
Source: https://docs.safesquid.com/use_cases/url_redirection/redirect_one_website_to_another
Configure SafeSquid to redirect one URL to another using Real Time Content Security Redirect policies.
# Set Up URL Redirection Between Websites
## [Access the SafeSquid User Interface ](/architecture/interface/configuration_portal)
SafeSquid includes sample policies to support policy creation. The sample policy "Enable interface access through authentication" is already present. Enable those policies to make them applicable.
Click on 'Configure' which is at top right of the SafeSquid Interface.
On the left side bar of SafeSquid Interface click on\*\* Real Time Content Security >> Redirect\*\*
Make the Global Section Enabled to TRUE.
![Global Section Enabled to TRUE to access the SafeSquid User Interface]()
Click Redirection Policies to see default policies, then add a new policy.
![Default policies in Redirection Policies section]()
Create a policy in **Configure** → **Access Profiles** (or **Templates**) with source/destination and redirect action as in the following example:
![Policy to Redirect One Website To Another Website]()
Click on save (Save button is placed at right bottom)
## Verify redirect
In this the URL value 'rediff.com' is redirect to 'SafeSquid.com' and the port to redirect to 80.
In a browser, open [https://www.rediff.com/](https://www.rediff.com/), it must redirect to SafeSquid.com. Verify in SafeSquid under Native logs on SafeSquid interface Reports >> Native logs as like below.
![Verify Redirect One Website To Another Website in Native logs on]()
## Next steps
* **[Policy Management Console](/architecture/interface/configuration_portal)** - administrative interface for defining, simulating, and enforcing SafeSquid access control, URL filtering, SSL inspection, and DLP policies.
# URL Redirection
Source: https://docs.safesquid.com/use_cases/url_redirection/url_redirection
Configure URL redirection policies in SafeSquid to redirect websites, enforce safe search, and implement content steering for security and compliance.
## Problem
Users and applications request URLs that policy must steer elsewhere: enforce SafeSearch on major search engines, send traffic from deprecated hosts to approved destinations, or hide internal redirection from the browser. Without proxy-level redirection, administrators rely on client-side settings or DNS tricks that users can bypass.
## Benefits
Administrators expect SafeSquid to rewrite or redirect requests and responses consistently. HTTP 302 mode exposes the target URL to the client. Internal redirection keeps the original address bar while the proxy fetches alternate content—useful for compliance and seamless steering.
## Advantages
**Confirmed:** SafeSquid supports two modes (HTTP 302 vs internal) from one **302 Redirect** toggle, combined with [Access Restriction](/use_cases/access_restriction/access_restriction) and [Profiling Engine](/use_cases/profiling_engine/profiling_engine) for scoped application.
## Call to action
In the Configuration Portal, open Real Time Content Security → URL Redirection. Choose 302 or internal mode per policy, then follow [Enforce SafeSearch](/use_cases/access_restriction/safesearch) or [Redirect One Website to Another](/use_cases/url_redirection/redirect_one_website_to_another). Verify behavior in Native logs.
## Redirection Modes
SafeSquid supports two redirection modes controlled by the **302 Redirect** toggle:
### HTTP Redirection (302 Redirect Enabled)
When enabled, SafeSquid sends an HTTP 302 redirect response to the client browser. The browser sees the redirect and follows it to the new destination. This mode:
* Shows the redirect in browser history
* Allows the client to see both original and target URLs
* Uses standard HTTP redirect mechanisms
### Internal Redirection (302 Redirect Disabled)
When disabled, SafeSquid performs the redirection internally without informing the client. The proxy fetches content from the target URL and serves it transparently. This mode:
* Hides the redirect from the end user
* Maintains the original URL in the browser address bar
* Performs the redirection at the proxy level
Choose the mode based on whether users should see the redirect happening (HTTP) or experience seamless content steering (internal).
## URL redirection and SafeSearch guides
### [Enforce SafeSearch](/use_cases/access_restriction/safesearch)
Search engines return explicit content when SafeSearch is not enforced. SafeSquid appends SafeSearch parameters to Google, Yahoo, and Bing queries so users cannot disable filtering. Consistent content filtering across search traffic reduces exposure and supports policy compliance. Enable SafeSearch policies using this document.
### [Redirect One Website to Another](/use_cases/url_redirection/redirect_one_website_to_another)
Organizations need to send traffic from one URL to another for branding, blocking, or compliance. The document covers enabling the Redirect section and creating redirection policies in Real Time Content Security. Verification in Native logs confirms redirects work as intended. Use this document to configure and validate URL-to-URL redirection.
## Next steps
Combine with [Access Restriction](/use_cases/access_restriction/access_restriction) for allow/deny by URL; use [Profiling Engine](/use_cases/profiling_engine/profiling_engine) for category-based policy.
# Use Cases
Source: https://docs.safesquid.com/use_cases/use_cases
Find the SafeSquid control that closes a specific attack surface, compliance gap, or operational risk.
# Find the Control for Your Risk
A proxy that only forwards traffic is not a security control. Each use case below closes one
specific gap — encrypted-traffic blindness, credential misuse, DNS-layer evasion, sensitive-data
exfiltration — with a policy you configure and can prove is enforced. Start from the risk you
need to close, not from a feature list.
## Foundation
Controls most deployments configure first, because later use cases depend on them.
* **[SSL Inspection](/use_cases/ssl_inspection/ssl_inspection)** - decrypt and inspect HTTPS traffic; without it, every other control is blind to most of today's web.
* **[Authentication](/use_cases/authentication/authentication)** - attribute every request to a user or group so policy and logs mean something.
* **[Profiling Engine](/use_cases/profiling_engine/profiling_engine)** - classify requests and responses so downstream controls act on the right traffic.
## Threat prevention
* **[DNS Security](/use_cases/dns_security/dns_security)** - block malicious and tunnelling domains before a connection is ever made.
* **[Malware Scanning](/use_cases/malware_scanning/malware_scanners)** - inspect downloads and payloads in the request path, not after the fact.
## Access control
* **[Access Restriction](/use_cases/access_restriction/access_restriction)** - allow or block sites, apps, and categories by user, group, or time window.
* **[Content Modifier](/use_cases/content_modifier/content_modifier)** - rewrite pages in flight to remove risky elements without blocking the whole site.
* **[Cookie Inspection](/use_cases/cookie_inspection/cookie_inspection)** - strip or filter cookies that leak session or tracking data.
* **[Header Rewrite](/use_cases/header_rewrite/header_obfuscation)** - rewrite request and response headers to enforce corporate-account-only access to consumer services.
* **[URL Redirection](/use_cases/url_redirection/url_redirection)** - send a matched request to a different destination instead of blocking it outright.
## Data protection
* **[Data Leakage Prevention](/use_cases/data_leakage_prevention/data_leakage_prevention)** - stop sensitive content leaving over the web egress path, not just email.
## Visibility
* **[Audit & Forensics](/use_cases/audit_and_forensics/audit_forensics)** - preserve evidence an auditor or incident responder can actually use.
## Integrations
* **[Integrations](/use_cases/integrations/integrations)** - connect SafeSquid to ICAP scanners, SIEM, and VPN so existing tooling sees proxy-layer evidence.
## Operations and lifecycle
Day-2 operations for a control already in production — scaling, tuning, customisation, and
upgrades.
* **[Scaling & High Availability](/use_cases/scaling_and_high_availability/proxy_clustering)** - add clustering and failover once a single node is proven.
* **[Performance Acceleration](/use_cases/performance_acceleration/performance_accelerators)** - cache and tune so inspection doesn't cost you latency.
* **[Customisation](/use_cases/customisation/customisation)** - adapt templates, startup parameters, and configuration sync to your environment.
* **[Upgrade](/use_cases/upgrade/version_upgrade)** - plan version and OS upgrades without an enforcement gap.
## Next steps
* [SSL Inspection](/use_cases/ssl_inspection/ssl_inspection) - close the encrypted-traffic blind spot first.
* [Authentication](/use_cases/authentication/authentication) - attribute traffic before you write policy against it.
* [Deployment](/deployment/main) - plan sizing, installation, and rollout before configuring use cases.