Setting up for the first time? Follow First configuration. This page explains 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.
What to configure first
This is setup order, not the order a live request is processed.- Network settings — where SafeSquid listens
- Access restrictions — who may connect, login if required, HTTP vs HTTPS rights
- Access Profiles — which sites and content to allow
- 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, Clam antivirus, and 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
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
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
Only buffered responses are scanned — a streamed response passes the download scanners unexamined. DLP does not run on the response at all. FTP browsing handlesftp:// 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 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.
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.
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.
Peer connection and FTP handling — not verified on this build
Peer connection and FTP handling — not verified on this build
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.
- 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 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.