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.
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:
Enter a valid domain name.
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.
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
: Always1
if debug is enableds-env
: Environment tag (e.g.prod
,dev
)s-node
: smoxy edge node that handled the requests-upstream
: Upstream server address that served the requests-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.
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)
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
, orno-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.
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.
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.
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.
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.
Last updated
Was this helpful?