Conditional Rules

Conditional Rules let you customize smoxy's behavior based on rich conditions like IP addresses, geographic location, headers, cookies, and more. Unlike Page Rules which stop at first match, Conditional Rules allow multiple rules to apply to the same request, making them perfect for complex, layered configurations.

What are Conditional Rules?

Conditional Rules allow you to override any smoxy configuration setting based on powerful conditional logic. They're ideal for scenarios where you need multiple configuration changes to stack together or when URL patterns alone aren't sufficient.

Key characteristics:

  • Execute fourth (last) in the rule sequence (after Access, Rewrite, and Page Rules)

  • Rich condition matching - IP, country, headers, cookies, user agents, and more

  • Evaluated in position order (1, 2, 3...)

  • All matching rules apply - multiple rules can modify the same request

  • Optional Stop - set stop=true to halt further evaluation

  • Can override any smoxy setting from your site configuration

How Conditional Rules Work

Conditional Rules are evaluated in ascending position order (1 → 2 → 3...) for every incoming request. When a rule's conditions match, its settings are applied, and evaluation continues to the next rule (unless stop=true).

Position-Based Evaluation

Request from Germany, mobile device
    ↓
Conditional Rule (Position 1) → Match (Country = DE)? → Apply Settings → CONTINUE
    ↓
Conditional Rule (Position 2) → Match (Mobile)? → Apply Settings → CONTINUE
    ↓
Conditional Rule (Position 3) → Match (URI = /api)? → No match → Skip
    ↓
Response (with settings from Rule 1 AND Rule 2)

Important: Unlike Page and Access Rules, Conditional Rules do not automatically stop after the first match. All matching rules apply their settings unless a rule has stop=true.

Conditions & Expressions

Conditional Rules use a rich condition builder that lets you match requests based on various characteristics including:

  • URI: Request path

  • Host: Domain name

  • IP: Client IP address or IP ranges

  • Country: ISO 3166-2 country code

  • City: Client's city

  • Subdivisions: State/region

  • Is European: Boolean - true if request is from EU

  • Method: HTTP method (GET, POST, PUT, DELETE, etc.)

  • User Agent: Browser or client identifier

  • Referer: Referring page URL

  • Accept Language: Client's preferred language

  • Cookie: Specific cookie value

  • Arg: Query parameter value

  • HTTP: Any HTTP header value

  • Cache-Control: Cache-Control header directives

Operators

  • Equal: Value matches exactly

  • Not Equal: Value doesn't match

  • In: Value is in a list

  • Not In: Value is not in a list

  • Matches: Matches regex pattern

  • Contains: Contains substring

  • Not Contains: Doesn't contain substring

  • Exists: Field exists (regardless of value)

  • Not Exists: Field doesn't exist

AND/OR Logic

Combine multiple conditions with AND/OR operators to create sophisticated rules:

(Country = "DE" OR Country = "AT" OR Country = "CH")
AND
URI starts with /checkout

Stop Behavior

The Stop option is unique to Conditional Rules and controls whether evaluation continues after a rule matches.

How Stop Works

When stop=false (default):

  • Rule's settings are applied

  • Evaluation continues to the next Conditional Rule

  • Multiple rules can modify the same request

When stop=true:

  • Rule's settings are applied

  • All subsequent Conditional Rules are skipped

  • Other rule types (Access, Rewrite, Page) are not affected

When to Use Stop

Use stop=true when:

  • A rule should be final and no further modifications are needed

  • You want to prevent conflicting settings from other rules

  • You're implementing maintenance mode or similar override scenarios

Example:

Position 1: IF (maintenance mode cookie) THEN (show maintenance page) STOP
Position 2: IF (office IP) THEN (disable auth) [never evaluated during maintenance]
Position 3: IF (mobile) THEN (optimize) [never evaluated during maintenance]

When to Use Conditional Rules

Use Conditional Rules When:

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

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

  • ✅ You need advanced AND/OR logic with multiple conditions

  • ✅ URL patterns alone aren't sufficient

  • ✅ Different conditions require different configurations that should stack

Use Page Rules Instead When:

  • ❌ You only need simple URL-based matching

  • ❌ You want first match wins behavior

  • ❌ The logic can be expressed with URL patterns only

Settings: Override Any Configuration

Conditional Rules can override any setting from your site's configuration, just like Page Rules. This includes:

  • Routing: Choose different origins or load balancers

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

  • 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

Simply select the settings you want to override when creating or editing a Conditional Rule. The available settings are grouped by category in the smoxy dashboard.

Use Cases & Examples

Example 1: Geographic Content Optimization

Scenario: Serve higher quality images to users in wealthy markets, standard quality elsewhere.

Position: 1
Condition: Country in ["US", "GB", "DE", "CH", "AU"]
Settings:
- JPEG Quality: 85
- WebP Quality: 85

Position: 2
Condition: Country in ["IN", "BR", "MX"]
Settings:
- JPEG Quality: 70
- WebP Quality: 70

Result: Both rules can apply (if conditions match), US users get higher quality

Why not Page Rules? Page Rules can't match on country - you need Conditional Rules for geographic targeting.

Example 2: Disable Basic Auth for Office IPs

Scenario: Your site uses basic authentication, but your team shouldn't need to login from the office.

Position: 1
Condition: IP in [203.0.113.0/24, 198.51.100.50]
Settings:
- Basic Authentication: Disabled

Position: 2
Condition: URI starts with "/admin"
Settings:
- Basic Authentication: Enabled
- Basic Auth Users: admin_users

Result: Office bypasses auth (Rule 1), but auth is still enabled for admin area (Rule 2)

Why not Access Rules? Access Rules are for blocking/challenging/whitelisting, not for toggling features like basic auth.

Example 3: Mobile-Optimized Images

Scenario: Mobile users should get more aggressive image optimization to save bandwidth.

Position: 1
Condition: User Agent matches "(Mobile|Android|iPhone|iPad)"
Settings:
- JPEG Quality: 75
- PNG Quality: 80
- WebP Quality: 75
- Image Max Width: 1200px

Position: 2
Condition: Country = "IN" AND User Agent matches "(Mobile|Android)"
Settings:
- JPEG Quality: 65
- WebP Quality: 65

Result: Mobile users get optimized images, mobile users in India get extra optimization

Why multiple rules? Both rules can apply - Rule 1 sets baseline mobile optimization, Rule 2 adds extra optimization for specific markets.

Conditional Rules vs Page Rules

The key differences:

Feature
Page Rules
Conditional Rules

Matching

URL patterns only

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

Execution

First match wins, stops

All matching rules apply

Stop option

No

Yes (optional)

Position

3rd in sequence

4th (last) in sequence

Settings

Override any setting

Override any setting

Can you use both? Absolutely! They complement each other:

Page Rule: /api/* → Set API load balancer
Conditional Rule: User-Agent = "mobile" → Enable mobile optimizations
→ Both apply to mobile requests to /api/users

Execution order: Page Rule executes first (stops on match), then Conditional Rules evaluate (all matching apply).

Rule Order Best Practices

1. Critical Rules First

Place rules that should always take precedence at lower positions:

Position 1: Maintenance mode (with stop=true)
Position 2-5: Business logic rules
Position 6+: Optimization rules

2. Use Stop Strategically

Position 1: IF (emergency mode) THEN (minimal features) STOP
Position 2+: Normal operational rules (skipped during emergency)

3. Layer Complementary Rules

Since all matching rules apply, you can build layered configurations:

Position 1: IF (Country = "DE") THEN (GDPR-compliant headers)
Position 2: IF (Mobile) THEN (Mobile optimizations)
Position 3: IF (URI = /checkout) THEN (High security)
→ German mobile checkout gets all three!

4. Avoid Conflicting Settings

If multiple rules set the same configuration key, the last matching rule wins:

Position 1: IF (Country = "US") THEN (Cache TTL = 3600)
Position 2: IF (URI = /api) THEN (Cache TTL = 60)
→ US requests to /api get TTL = 60 (last match wins)

Using IP Lists

Instead of hardcoding IPs in each rule, create reusable IP Lists in your account settings:

  1. Create an IP List named "office_ips" with your office IP ranges

  2. Reference it in your Conditional Rule conditions

Benefit: Update the IP list once, and all rules using it are automatically updated across all your sites.

Uniqueness

Each site can only have one Conditional Rule per unique expression. If you try to create a duplicate, you'll see: "The rule for this expression already exists."

This prevents duplicate rules and keeps your configuration clean.

Common Mistakes

❌ Forgetting rules stack

Position 1: IF (URI = /api) THEN (Cache = disabled)
Position 2: IF (URI = /api/*) THEN (Cache = enabled & Cache TTL = 3600)
→ Both apply, last one wins: Cache = enabled with TTL 3600

✅ Be aware of interactions

Use stop=true or consolidate into one rule when needed

❌ Using Stop too early

Position 1: IF (Country = "US") THEN (settings) STOP
Position 2: IF (Mobile) THEN (mobile settings) [never applies to US mobile users]

✅ Stop only when necessary

Remove stop=true unless you specifically need to halt evaluation

❌ Using Conditional Rules for simple URLs

Condition: URI starts with "/admin"
→ Should use Page Rule instead

✅ Use Page Rules for URL-only logic

Page Rule: Match /admin/* → Settings
(Simpler and executes earlier)

❌ Conflicting settings from multiple rules

Position 1: IF (Mobile) THEN (Image Quality = 80)
Position 2: IF (Country = "US") THEN (Image Quality = 90)
→ US mobile users get Quality = 90 (last match wins)

✅ Plan for overlapping conditions

Either use stop, adjust positions, or accept last-match-wins behavior

Testing Conditional Rules

  1. Enable Debug Headers in your site configuration

  2. Make test requests with different conditions (IPs, user agents, etc.)

  3. Check response headers to see which Conditional Rules matched

  4. Verify settings are being applied in the expected order

  5. Test overlapping conditions to ensure the last-match-wins behavior is acceptable

Last updated

Was this helpful?