Basic Configuration

Getting Started

Each site in smoxy represents an isolated configuration space for one or more hostnames. The Basic Configuration page is where you define the core behavior of the site — including routing to origin infrastructure, enabling CDN and optimization features, and managing cache behavior and fallback pages.

Before continuing with rules, response headers, SSL settings, or analytics, ensure that your site is correctly configured here. This is the foundation for all further features in smoxy.

---

smoxy Activation

Toggle: Enable smoxy This switch activates smoxy's optimization features. When enabled, smoxy will:

• Optimize images

• Cache and accelerate HTML

• Apply bot protection

When disabled, smoxy acts as a pure reverse proxy and bypasses all caching, optimization, and protection logic.

Note: Disabling this will stop CDN delivery, HTML caching, and optimization. DNS and routing remain functional.

---

Hostname Management

Add Hostname

Each site can serve one or more hostnames. Adding a hostname links it to the site’s configuration.

When adding a hostname:

1. Enter a valid domain name.

2. Submit the form.

smoxy will asynchronously check DNS and SSL status in the background.

Make sure to:

• Point your DNS to the provided CNAME target (unique per hostname).

• Let smoxy manage SSL certificates for the domain (recommended).

How SSL works in smoxy: When you add a hostname, smoxy will automatically add the root domain of that hostname to your domain management page. From there, you can choose to have smoxy generate an SSL certificate. For every Subject Alternative Name (SAN), smoxy will request a dedicated _acme_challenge DNS record, which is used to validate the certificate.

When a new domain is detected, smoxy pre-configures SAN entries for yourdomain.com and *.yourdomain.com, giving you a starting point for wildcard coverage.

Tip: If you prefer to use your own SSL certificates, you can upload them manually. Just keep in mind that smoxy cannot renew them for you — you’ll need to update them before they expire.

Linked Hostnames Table

For each linked hostname, you can:

• Visit the hostname

• View configuration issues (e.g. missing CNAME)

• Move the hostname to another site

• Delete the hostname

• Access DNS & SSL settings

---

Origin or Loadbalancer

Choose the upstream for your site’s traffic:

• Origin: A single backend server.

• Loadbalancer: A group of origin servers with internal smoxy load balancing.

You can switch between origins or load balancers at any time.

Switching targets does not purge cached content. Use the invalidation API or zone token to clear cache. Alternatively, you can use the quick actions available in the site’s dashboard to:

• Clear the entire cache

• Clear by URL

• Clear by cache tag

---

Site Token

Each site has a unique invalidation token, used for:

• Bypassing the cache (with a special request header)

• Authenticating with the cache invalidation API

Changing this token affects all hostnames linked to the site.

---

Debug Headers

Enables HTTP response headers showing smoxy internals for debugging.

• Enabled: Adds s- prefixed headers to the response.

• Disabled: smoxy remains silent.

Debug headers include:

• s-cache: Cache status (HIT, MISS, BYPASS)

• s-cache-key-page-str: Cache key composition (e.g. host, uri)

• s-debug-message: Always 1 if debug is enabled

• s-env: Environment tag (e.g. prod, dev)

• s-node: smoxy edge node that handled the request

• s-upstream: Upstream server address that served the request

• s-zone-id: Internal site identifier (e.g. 5_38 = org ID + site ID)

Additionally, the response includes details about which rules have been evaluated and applied.

---

SSI & ESI

SSI (Server Side Includes)

Allows processing of <!--#include --> directives. This enables smoxy to render server-side fragment includes.

ESI (Edge Side Includes)

smoxy detects <esi:include> tags in HTML responses and automatically rewrites them to SSI (<!--#include-->) directives. This allows seamless support for applications using ESI, without requiring backend changes.

The following ESI constructs are supported and rewritten internally:

• <esi:include src="..."/> → <!--#include virtual="..." -->

• <esi:remove>...</esi:remove> → will be removed completely

• <esi:choose> → <!--#if expr="" -->

• <esi:when test="..."> → <!--#if expr="%1" -->

  • </esi:when> → <!--#endif -->

• <esi:otherwise> → <!--#else -->

  • </esi:otherwise> → ""

• <esi:choose> → <!--#if expr=""

  • </esi:choose> → <!--#endif -->

This rewriting happens transparently during response processing and enables compatibility with typical Varnish-style or Akamai ESI logic, as long as the includes and conditions can be mapped to basic SSI syntax.

---

Expire In (Cache Lifetime)

Define the default cache lifetime for cached resources.

• Value: 0 = smoxy default (7 days)

• Min: 300 seconds (5 min)

• Max: 604800 seconds (7 days)

Override Reasons: When overriding defaults, an optional reason can be stored for auditing.

---

Cache Control Header Respect

When enabled, smoxy honors the origin server’s Cache-Control response header.

• If the header contains no-store, private, max-age=0, or no-cache, smoxy skips the cache.

---

Cache Key

Configure how smoxy builds cache keys.

Options:

• Request Hostname: Cache varies per hostname.

• Cookie: Enable to vary cache based on selected cookie values. Provide a list of relevant cookie names.

Each unique key combination results in a separate cache object.

---

Excluded URL Parameters

Define a list of URL parameters that should not affect the cache key.

This is particularly useful when running marketing campaigns that append unique query parameters (e.g., tracking codes, UTM parameters). Without exclusion, each request would generate a new cache entry, reducing cache hit efficiency.

By excluding such parameters:

• Cache hit rates are significantly improved.

• The response is served directly by smoxy.

• The request may not reach your backend — so server-side analytics based on those parameters won't fire.

Example: utm_campaign, utm_source, gclid, ref, etc.

---

Ignored Cache Tags

Some applications inject large sets of cache tags into every page, causing single-tag invalidations to unintentionally purge too much content.

Use this setting to exclude certain tags from being tracked by smoxy. These tags will not be stored or considered for invalidation, improving control over what gets purged and preserving cache efficiency.

---

Custom Cache Tag Headers

By default, smoxy inspects the x-cache-tags header in responses to extract tag information.

If your application or framework already uses a different header (e.g., xkey) or delimiter (e.g., space or semicolon), you can configure smoxy to read and parse those correctly.

Supports up to 4 custom headers, each with its own delimiter.

---

Stale Cache (CDN only)

Two options for serving expired cache temporarily:

• While Offline: Serve stale cache when origin is unreachable.

• While Updating: Serve stale cache while a fresh version is fetched in the background.

Improves perceived uptime and resilience.

---

Cache Error Response (CDN only)

If enabled, smoxy will cache error responses (HTTP status 5xx and similar) for 5 seconds.

This helps protect your origin servers from burst traffic, retries, or DDoS-style behavior.

---

HTTP Headers

Request Headers

Custom headers added when forwarding requests to the origin. Format: one per line, e.g.

x-app-env = staging
x-feature-flag = true

Response Headers

Custom headers added to the response sent back to the client. Same format as above.

---

Custom Pages

Error Page (502/504)

Upload an HTML file shown when the origin returns a 502 or 504.

• Max size: 4KB

• Supports variables like:

  • ::SX_STATUS::

  • ::SX_REMOTE_IP::

  • ::SX_HOST::

  • ::SX_STATUS_TEXT::

Security Page

Shown when smoxy blocks a request based on security rules. Supports same file format and template variables as the error page.

Maintenance Page

Shown when maintenance mode is active. You can upload your own HTML file. To whitelist IPs during maintenance, use a conditional rule.