Configuration: URL rewriting

This page documents the rewrite directive for transforming request URLs using regular expression patterns. Ferron applies rewrites in the request pipeline, before proxying or static file serving, so later stages use the rewritten URL.

Directives⁠#

rewrite⁠#

• rewrite <regex: string> <replacement: string>
  • This directive specifies a regular expression pattern and replacement string for URL rewriting. You can reference regex capture groups in the replacement string ($1, $2, and so on). Default: none

Block options⁠#

Configuration example:

example.com {
    rewrite r"^/old-path/(.*)" "/new-path/$1"
}

Simple rewrite⁠#

example.com {
    rewrite r"^/old-path/(.*)" "/new-path/$1"
}

Ferron internally rewrites all /old-path/anything requests to /new-path/anything. The client sees no redirect. The rewrite is transparent.

Stop processing with last⁠#

example.com {
    rewrite r"^/api/v1/(.*)" "/api/v2/$1" {
        last
    }
    rewrite r"^/api/v2/(.*)" "/api/v3/$1"
}

Ferron rewrites /api/v1/users requests to /api/v2/users and then stops. The second rule never sees the /api/v2/ prefix.

Chained rules without last⁠#

example.com {
    rewrite r"^/legacy/(.*)" "/modern/$1"
    rewrite r"^/modern/(.*)" "/current/$1"
}

Ferron first rewrites a /legacy/foo request to /modern/foo. Then the second rule rewrites it to /current/foo.

When several rules share a host, give them name values so observability output tells them apart:

example.com {
    rewrite r"^/legacy/(.*)" "/modern/$1" {
        name "legacy-to-modern"
    }
    rewrite r"^/modern/(.*)" "/current/$1" {
        name "modern-to-current"
    }
}

File/directory-specific rules⁠#

file false and directory false skip the rule when the URL maps to a real file or directory under root. Use both guards for fallback patterns such as single-page apps and front controllers. Without the guards, a broad pattern rewrites static asset requests too, and scripts, styles, and images break.

example.com {
    root /var/www

    rewrite r"^/static/(.*)" "/assets/$1" {
        file
        directory false
    }
}

rewrite_log⁠#

• rewrite_log <bool>
  • This directive specifies whether Ferron logs each URL rewrite operation to the error log. Default: rewrite_log false

Configuration example:

example.com {
    rewrite_log
}

Example log output:

URL rewritten from "/old-path/users" to "/new-path/users"

Regex syntax⁠#

The regular expression engine used is regex, which executes regular expressions in linear time (no support for backtracking). This means that regular expressions are executed efficiently without backtracking, mitigating potential ReDoS and catastrophic backtracking attacks.

However, this also means you cannot use syntax listed below:

• Lookahead statements ((?= ...), (?! ...))
• Lookbehind statements ((?<= ...), (?<! ...))
• Backreferences to capture groups (\1)

If you have to negate a condition, you can use negated variants of some directives, such as if_not blocks instead of if, or !~ in matchers instead of ~.

The matching is case-insensitive on Windows and case-sensitive on other platforms.

Observability⁠#

Rule positions below are 1-based: the first rewrite directive in a block is rule 1. Give rules name values when you need readable identifiers instead of positions.

Metrics⁠#

Logs⁠#

When rewrite_log is on, Ferron logs each rewrite operation to the error log at DEBUG level.

Structured logs⁠#

Access log fields⁠#

The rewrite module contributes the following fields to the HTTP access log line:

Trace spans⁠#

The rewrite stage sets the following attributes on its ferron.stage.rewrite span: