Rules Overview

Rules are powerful tools that allow you to customize how smoxy handles traffic to your site. They let you change smoxy's behavior for specific URLs, conditions, or security scenarios without modifying your site's base configuration.

What are Rules?

Think of rules as "if-then" statements for your CDN:

  • IF a request matches certain criteria (a URL pattern, an IP address, a geographic location, etc.)

  • THEN modify smoxy's behavior (change caching, route to different servers, block access, etc.)

Rules give you fine-grained control over how smoxy processes each request, allowing you to create sophisticated routing, caching, and security policies.

The 4 Rule Types

smoxy offers four types of rules, each designed for specific use cases:

Rule Type
Best For
Matching Based On
Execution Behavior

Access Rules

Security & access control

Rich conditions (IP, country, headers, etc.)

Runs first, before everything else

Rewrite Rules

URL rewriting & redirects

URL patterns

Runs second, nginx-style rewriting

Page Rules (Deprecated)

URL-specific configuration

URL patterns

First match wins, then stops

Conditional Rules

Complex logic & conditions

Rich conditions (IP, country, headers, etc.)

All matching rules apply

Quick Comparison

Access Rules vs Conditional Rules:

  • Both use rich condition matching (IP, country, headers, cookies, etc.)

  • Access Rules are for security (block, challenge, whitelist) and run first

  • Conditional Rules are for configuration changes (caching, routing, headers) and run later

Page Rules vs Conditional Rules:

  • Both can override smoxy settings

  • Page Rules match on URL patterns only and stop at first match

  • Conditional Rules use rich conditions and all matching rules apply

Rewrite Rules:

  • Specialized for URL rewriting (like nginx rewrite rules)

  • Limited to 5 rules per site

  • Runs second in the sequence (after Access Rules, before Page Rules)

Execution Order

Rules are evaluated in a specific sequence for every request:

Incoming Request
    ↓
1. Access Rules (Security Layer)
   - Position 1, 2, 3... (in order)
   - Block, challenge, or whitelist traffic
   - All matching rules apply (unless "Stop" is enabled)
    ↓
2. Rewrite Rules (URL Rewriting)
   - Position 1, 2, 3... (in order)
   - Rewrites URL if matched
    ↓
3. Page Rules (URL Matching)
   - Position 1, 2, 3... (in order)
   - First match wins → STOPS
    ↓
4. Conditional Rules (Condition Matching)
   - Position 1, 2, 3... (in order)
   - All matching rules apply (unless "Stop" is enabled)
    ↓
Response

Within Each Rule Type

Rules within the same type are evaluated based on their position (also called priority or order):

  • Position 1 is evaluated first

  • Position 2 is evaluated second

  • And so on...

You can reorder rules at any time using drag-and-drop in the smoxy hub.

When to Use Which Rule Type

Use Access Rules When:

  • ✅ You need to block or challenge suspicious traffic

  • ✅ You want to whitelist trusted IPs (skip security checks)

  • ✅ You need to bypass WAF for specific requests (e.g., internal tools)

  • ✅ Security decisions need to happen before any other processing

Example: Block all requests from a specific country, except for your office IP.

Use Rewrite Rules When:

  • ✅ You need to rewrite URLs (like nginx rewrite rules)

  • ✅ You're doing URL normalization or redirection

  • ✅ You need legacy URL support or clean URL structures

  • ✅ URL transformations need to happen before other rules evaluate

Example: Rewrite /old-path to /new-path, or normalize URLs for better caching.

Use Conditional Rules When:

  • ✅ You need different settings for different URLs

  • ✅ You need complex conditions (IPs, countries, headers, cookies, etc.)

  • ✅ You want multiple rules to apply to the same request

  • ✅ You need advanced logic (AND/OR combinations)

  • ✅ Different conditions require different configurations

Example: Serve higher quality images to users from Europe, enable basic auth for non-office IPs, and route mobile traffic differently.

Example: Disable caching for /admin/* URLs, or route /api/* to a different load balancer.

Settings: Override Any smoxy Configuration

Both Page Rules and Conditional Rules can override ANY setting from your site's configuration.

This means any configuration you can set in your site (caching, image optimization, load balancing, security, headers, etc.) can be overridden by a rule for specific requests.

Available settings include:

  • Routing: Choose different origins or load balancers

  • Caching: Control cache TTL, cache keys, cache tags

  • Image Optimization: AVIF, WebP, JPEG, PNG quality levels

  • Security: Enable/disable WAF, basic auth, custom error pages

  • Headers: Add, modify, or remove request/response headers

  • Optimization: HTML/JS/CSS minification

  • Advanced: Maintenance mode, debug headers, proxy timeouts, SSI/ESI

The available settings are the same for both Page Rules and Conditional Rules - the only difference is when and how the rules are matched.

Best Practices

  1. Start with Access Rules for security: Always define your whitelist (skip/continue) rules first, then add block/challenge rules

  2. Use Rewrite Rules early: URL rewrites happen before Page and Conditional Rules evaluate, so plan accordingly

  3. Use Conditional Rules for complex logic: When you need multiple conditions or want multiple rules to apply

  4. Test with debug headers: Enable debug headers to see which rules are being applied to your requests

  5. Order matters: Review the position/order of your rules - especially important for Access and Page Rules

Last updated

Was this helpful?