search

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.

hashtag
Page Types

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

Page Type
Triggered When
HTTP Status Codes

Error Page

Your origin server is unreachable or times out

502 (Bad Gateway), 504 (Gateway Timeout)

Security Page

A request is blocked by WAF or security rules

403 (Forbidden)

Maintenance Page

You enable maintenance mode for your site

503 (Service Unavailable)

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

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

Variable
Description
Available 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 request

Error, Security

::SX_REMOTE_IP::

The visitor's IP address

Error, Security

circle-info

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

hashtag
Example Usage

hashtag
Requirements

Requirement
Details

File format

HTML only (.html or .txt extension)

Maximum file size

256 KB

MIME type

text/html

Other file types (images, PDFs, scripts) are not accepted. Your HTML page should be self-contained — inline your CSS and any images as Base64 data URIs if needed.

hashtag
Uploading a Custom Page

  1. Navigate to your Site in smoxy

  2. Open the Basic Configuration 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.

hashtag
Page Type Details

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

hashtag
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 site for security blocks to occur. See Security & WAF for details.

hashtag
Maintenance Page

The maintenance page is shown when you enable maintenance mode for your site. 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.

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

hashtag
Important Considerations

  • Self-contained HTML: Your custom page should be a single HTML file. External resources (CSS files, images, JavaScript) hosted on your own servers may not load if your origin is down. Use inline styles and Base64-encoded images instead.

  • File size limit: Keep your pages under 256 KB. This limit ensures fast delivery even under high load.

  • No JavaScript dependencies: Avoid relying on external JavaScript libraries. If your origin or CDN is down, those resources won't load either.

  • Test with the preview: Always use the preview feature to verify your template variables render correctly before going live.

  • One page per type: Each site has one custom page per type. You cannot configure different pages for different hostnames on the same site.

Last updated

Was this helpful?