Skip to main content

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

​
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, 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

Templates — Manage templates rows

​
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.
  • Access Profiles — a Deny action invokes a block template by name.
  • Header filter — the Drop Original CSP pattern that keeps an isolation or block page’s own CSP from merging incorrectly with the destination’s.