smoxy

English

Deutsch

English

Deutsch

Appearance

Custom Pages ​

smoxy allows you to replace the default error, security, and maintenance pages with your own custom HTML pages. This gives you full control over what your visitors see during outages, security blocks, or scheduled maintenance.

Custom error, security, and maintenance pages.Custom error, security, and maintenance pages.
Custom error, security, and maintenance pages.

Page Types ​

smoxy supports three custom page types, each triggered by different scenarios:

Page TypeTriggered WhenHTTP Status Codes
Error PageYour origin server is unreachable or times out502 (Bad Gateway), 504 (Gateway Timeout)
Security PageA request is blocked by WAF or security rules403 (Forbidden)
Maintenance PageYou enable maintenance mode for your zone503 (Service Unavailable)

Each page type can be enabled independently -- you can use a custom error page without customizing your security or maintenance pages.

Template Variables ​

Custom pages support dynamic template variables that smoxy replaces with real values when the page is served. Use these to display contextual information to your visitors.

The Template Variables card, with a copy button for each variable.The Template Variables card, with a copy button for each variable.
The Template Variables card, with a copy button for each variable.
VariableDescriptionAvailable In
::SX_STATUS::The HTTP status code (e.g., 502, 403)Error, Security
::SX_STATUS_TEXT::Human-readable status text (e.g., Bad Gateway, Forbidden)Error, Security
::SX_HOST::The hostname that received the requestError, Security
::SX_REMOTE_IP::The visitor's IP addressError, Security

INFO

Note: Maintenance pages do not support template variables. The maintenance page is served as static content.

Example Usage ​

html
<!DOCTYPE html>
<html>
<head>
    <title>Error ::SX_STATUS:: - ::SX_HOST::</title>
</head>
<body>
    <h1>::SX_STATUS:: ::SX_STATUS_TEXT::</h1>
    <p>Sorry, something went wrong while loading <strong>::SX_HOST::</strong>.</p>
    <p>IP address: ::SX_REMOTE_IP::</p>
    <p>If this problem persists, please contact our support team.</p>
</body>
</html>

Requirements ​

RequirementDetails
FormatHTML only (.html)
SizeMaximum 100 KB per file
SyntaxMust be valid HTML5
AssetsExternal resources must use absolute HTTPS URLs
ScriptsJavaScript is supported but may be restricted
EncodingUTF-8

Other file types (images, PDFs, scripts) are not accepted. Keep your HTML page self-contained and lightweight, and reference any external assets via absolute HTTPS URLs.

The File Requirements card summarizing format, size and encoding rules.The File Requirements card summarizing format, size and encoding rules.
The File Requirements card summarizing format, size and encoding rules.

Uploading a Custom Page ​

  1. Navigate to your Zone in smoxy
  2. Open the Proxy page
  3. Scroll to the relevant section (Custom Error Page, Custom Security Page, or Maintenance Mode)
  4. Toggle the feature on
  5. Upload your HTML file
  6. Save the configuration

After uploading, a live preview of your page appears in the configuration panel. You can click the preview to open it in a new tab.

The upload card for a page type: toggle it on and upload an HTML file.The upload card for a page type: toggle it on and upload an HTML file.
The upload card for a page type: toggle it on and upload an HTML file.

Page Type Details ​

Error Page ​

The error page is shown when smoxy cannot reach your origin server or the origin takes too long to respond.

When it appears:

  • 502 Bad Gateway -- Your origin returned an invalid response or is offline
  • 504 Gateway Timeout -- Your origin did not respond in time

Template variables: All 4 variables are available (::SX_STATUS::, ::SX_STATUS_TEXT::, ::SX_HOST::, ::SX_REMOTE_IP::)

Tip: Use ::SX_STATUS:: to differentiate between 502 and 504 errors in a single page, for example to show different troubleshooting advice.

Security Page ​

The security page is shown when a request is blocked by smoxy's security rules or WAF.

When it appears:

  • 403 Forbidden -- The request was blocked by an access rule or WAF

Template variables: All 4 variables are available

Prerequisite: The security feature must be enabled on your zone for security blocks to occur. See Security & WAF for details.

Maintenance Page ​

The maintenance page is shown when you enable maintenance mode for your zone. This is useful for planned downtime or deployments.

When it appears:

  • 503 Service Unavailable -- Maintenance mode is active

Template variables: None -- the maintenance page is served as static HTML without variable substitution.

Tip: Since maintenance pages don't support template variables, include all necessary information directly in the HTML.

Preview ​

After uploading a custom page, smoxy provides an interactive preview with a toolbar that lets you test how your page looks with different values:

  • Status code -- Select different status codes to see how your template variables render
  • Hostname -- Enter a hostname to test ::SX_HOST:: substitution
  • Remote IP -- Enter an IP to test ::SX_REMOTE_IP:: substitution

The preview updates in real time as you change the toolbar values.

Important Considerations ​

  • Keep pages self-contained and lightweight: Resources hosted on your own servers may not load if your origin is down. Any external assets you do reference must use absolute HTTPS URLs.
  • File size limit: Keep your pages under 100 KB. This limit ensures fast delivery even under high load.
  • JavaScript may be restricted: JavaScript is supported but may be restricted, and external scripts won't load if your origin or CDN is down. Don't rely on it for critical content.
  • Test with the preview: Always use the preview feature to verify your template variables render correctly before going live.
  • One page per type: Each zone has one custom page per type. You cannot configure different pages for different hostnames on the same zone.