Redirect Rollback & Recovery

Context

When a new redirect map sends traffic into loops, dead ends, or the wrong targets, you need to restore the previous routing layer in seconds without dropping a request. This guide covers reverting redirect maps and rules through atomic config swaps, restoring the previous server configuration, and purging the edge caches that would otherwise keep serving broken routes. It runs under Migration Rollback Playbooks and reverses changes deployed via URL Mapping & Redirect Architecture.

Atomic redirect swap A symlink repoints from the broken redirect map to the previous known-good map, the config is validated and reloaded, then the edge cache is purged. Atomic Redirect Swap 1. Repoint link 2. Validate 3. Reload 4. Purge edge ln -sfn prev map nginx -t systemctl reload CDN purge API Reload is zero-downtime; a failed validation aborts before any traffic shifts.
The swap repoints a symlink to the previous map, validates, reloads with no dropped connections, then purges the edge.

Pre-flight Checks

Keep the previous routing layer archived and ready so reversion is a swap, not a rebuild.

  • Archive the previous redirect map and server config under version control, tagged to the last verified state.
  • Confirm the live config references the map via an indirection (symlink or include) so swaps are atomic.
  • Verify nginx -t / apachectl configtest pass on the archived config before you need it.
  • Confirm CDN purge credentials and the exact paths or tags to invalidate.

Redirect Rollback Readiness Checklist:

  • redirects.prev.conf)
  • curl -IL) scripted for verification

Execution Steps

Swap the routing layer atomically, reload without downtime, then clear stale edge state.

1. Repoint to the Previous Map Atomically

Use a symlink swap (ln -sfn) or activate the archived include so the server reads the previous known-good map in a single filesystem operation. Editing the live map in place risks serving a half-written file to live traffic. Confirm the restored rules match the last verified state in URL Mapping & Redirect Architecture.

2. Validate Before Reload

Run nginx -t or apachectl configtest so a syntax error aborts the rollback before it can take down the routing layer. A failed validation must stop the process — never reload an unvalidated config during an incident. This gate is what makes the swap safe to run under pressure.

3. Reload With Zero Downtime

Apply the config with systemctl reload nginx or apachectl graceful, both of which finish in-flight requests on old workers while new workers pick up the restored rules. A hard restart drops connections and worsens the incident. Reload, then immediately spot-check a known-broken path.

4. Purge the Edge Cache

Redirect responses are cacheable, so the CDN may keep serving the broken Location header after the origin is fixed. Purge the affected paths or cache tags via the provider API, then confirm a MISS followed by a correct HIT. Coordinate the purge timing with the recovery broadcast in Migration Rollback Playbooks, and use trigger conditions from Rollback Trigger Thresholds to decide when to fire.

Configs / Commands

Nginx — atomic map swap, validate, reload:

# Repoint the active map to the archived known-good version, then reload safely
ln -sfn /etc/nginx/maps/redirects.prev.conf /etc/nginx/maps/redirects.active.conf
nginx -t && systemctl reload nginx   # reload finishes in-flight requests, no drops

Apache — restore prior rewrite config gracefully:

# Activate the archived rules, test syntax, then graceful restart
a2disconf redirects && cp /etc/apache2/conf-available/redirects.prev.conf \
  /etc/apache2/conf-available/redirects.conf
a2enconf redirects && apachectl configtest && apachectl graceful

Cloudflare API — purge cached redirect responses:

# Purge specific URLs so the broken Location header is no longer served from edge
curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE/purge_cache" \
  -H "Authorization: Bearer $CF_TOKEN" -H "Content-Type: application/json" \
  --data '{"files":["https://www.example.com/old-path","https://www.example.com/category/"]}'

Validation

Prove loops are gone, targets are correct, and the edge serves fresh responses.

  • curl -sIL https://www.example.com/old-path resolves to the correct target in a single hop with no loop.
  • curl -sI https://www.example.com/category/ | grep -i cf-cache-status shows MISS then HIT after purge.
  • A crawl of the top traffic paths returns no new 3xx chains or 404s versus the pre-migration baseline.
  • 4xx rate returns below the ceiling defined in Rollback Trigger Thresholds.

Rollback Triggers

Fire the redirect rollback when routing faults breach these limits.

  • Redirect loops: any path exceeding 2 hops or returning a loop fires an immediate swap to the previous map.
  • 4xx spike: 4xx rate above baseline + 10 points sustained for 10 minutes signals broken targets.
  • Wrong targets: confirmed mismatches on top-traffic URLs (wrong Location header) trigger reversion.
  • Stale edge: if a purge fails to clear broken responses, escalate to a zone-wide purge before standing down.

FAQ

Why use a symlink swap instead of editing the live redirect map? A symlink repoint is a single atomic filesystem operation, so the server never reads a partially written file. Editing the live map in place can expose live traffic to an inconsistent rule set mid-save, which is exactly the kind of second fault you cannot afford during a rollback.

Does systemctl reload drop any in-flight requests? No. A reload starts new worker processes with the restored config while existing workers finish their current requests, then exit. This is why you reload rather than restart during a rollback — a hard restart would terminate active connections.

Why do I need to purge the CDN after fixing redirects at the origin? Redirect responses carry cacheable status codes, so the CDN may keep returning the broken Location header from its edge nodes even after the origin is corrected. A targeted purge of the affected paths forces the edge to re-fetch the fixed response.

Can I roll back redirects without touching DNS? Yes, and you often should. Redirect faults live entirely in the HTTP routing layer, so an atomic config swap plus a cache purge fixes them without the TTL-bound wait that a DNS rollback incurs. Reserve DNS rollback for origin-level failures.

Related

← Back to Migration Rollback Playbooks