Nginx-Style Header Variables

September 9, 2025 · View on GitHub

Easegress HTTPServer supports nginx-style variables in the setHeaders configuration, allowing you to dynamically populate HTTP headers with request information. This feature provides powerful capabilities for debugging, logging, routing decisions, and passing contextual information to backend services.

Overview

The nginx variable system in Easegress supports:

Request line variables (method, URI, query parameters)
Host and server variables
Client information (remote address, user agent)
Time and timestamp variables
Content and protocol information
HTTP header extraction
Query parameter extraction
Cookie value extraction
Default value support with ${variable:default} syntax
String interpolation for building complex values

Easegress adopts nginx variables as much as possible for compatibility. For a complete reference of nginx variables, see the official nginx variable index.

Variable Syntax

Easegress supports two nginx-compatible variable syntaxes:

# Simple variable reference
X-Method: "$request_method"

# Variable with default value
X-Version: "${arg_version:v1.0}"

# String interpolation
X-Backend-URL: "${scheme}://${host}-backend${uri}"

Complete Example

See the complete example configuration at: example/config/test-nginx-header-vars.yaml

This example demonstrates all available variable types and usage patterns.

Variable Categories

1. Request Line Variables

Extract information from the HTTP request line:

Variable	Description	Example Value
`$request_method`	HTTP method	`GET`, `POST`, `PUT`
`$request_uri`	Full request URI with query string	`/api/users?page=1`
`$uri`	Path portion of URI (without query)	`/api/users`
`$scheme`	Protocol scheme	`http`, `https`
`$query_string`	Query string portion	`page=1&limit=10`
`$args`	Alias for `$query_string`	`page=1&limit=10`
`$request`	Full request line	`GET /api/users HTTP/1.1`

2. Host and Server Variables

Information about the server and request host:

Variable	Description	Example Value
`$host`	Host from request (without port)	`api.example.com`
`$hostname`	Alias for `$host`	`api.example.com`
`$http_host`	Host header value (with port)	`api.example.com:8080`
`$server_name`	Server name	`api.example.com`
`$server_protocol`	HTTP protocol version	`HTTP/1.1`, `HTTP/2.0`

3. Client Information Variables

Information about the client making the request:

Variable	Description	Example Value
`$remote_addr`	Client IP address	`192.168.1.100`
`$remote_user`	Authenticated username	`john_doe`
`$proxy_add_x_forwarded_for`	X-Forwarded-For with client IP	`10.0.0.1, 192.168.1.100`

4. Time and Timestamp Variables

Current time in various formats:

Variable	Description	Example Value
`$time_iso8601`	ISO 8601 timestamp	`2025-09-05T10:30:45+08:00`
`$time_local`	Local time format	`05/Sep/2025:10:30:45 +0800`
`$msec`	Timestamp in milliseconds	`1725508245123`
`$request_time`	Request processing time	`0.045`

5. Content and Protocol Variables

Information about request content:

Variable	Description	Example Value
`$content_type`	Content-Type header	`application/json`
`$content_length`	Content-Length header	`1024`
`$request_length`	Total request size	`1024`

6. HTTP Header Variables

Extract any HTTP header using the $http_ prefix:

Variable Pattern	Description	Example
`$http_user_agent`	User-Agent header	`Mozilla/5.0 (...)`
`$http_accept`	Accept header	`application/json`
`$http_x_forwarded_for`	X-Forwarded-For header	`10.0.0.1`
`$http_authorization`	Authorization header	`Bearer token123`
`$http_*`	Any header (replace * with header name)	Various

Note: Header names are converted using these rules:

Convert to lowercase
Replace hyphens with underscores
Add http_ prefix

Examples:

Content-Type → $http_content_type
X-API-Key → $http_x_api_key
User-Agent → $http_user_agent

7. Query Parameter Variables

Extract query parameters using the $arg_ prefix:

Variable Pattern	Description	Example
`$arg_page`	Extract `page` parameter	`1`
`$arg_limit`	Extract `limit` parameter	`50`
`$arg_api_key`	Extract `api_key` parameter	`abc123`
`$arg_*`	Any query parameter	Various

Example URL: https://api.example.com/users?page=2&limit=50&api_key=abc123

Extract cookie values using the $cookie_ prefix:

Variable Pattern	Description	Example
`$cookie_session_id`	Extract `session_id` cookie	`sess_abc123`
`$cookie_user_pref`	Extract `user_pref` cookie	`dark_mode`
`$cookie_*`	Any cookie value	Various

9. Path Parameter Variables

Extract path parameters from route patterns (when using parameterized routes):

Variable	Description	Example
`$id`	Path parameter `id`	`123`
`$name`	Path parameter `name`	`john`
Custom names	Based on route definition	Various

Default Values

Use the ${variable:default} syntax to provide fallback values:

setHeaders:
  X-Version: "${arg_version:v1.0}"          # Default to "v1.0" if no version param
  X-User: "${remote_user:anonymous}"        # Default to "anonymous" if not authenticated
  X-Content-Type: "${content_type:none}"    # Default to "none" if no content type

Complex String Building

Combine multiple variables to build complex header values:

setHeaders:
  # Build backend URL
  X-Backend-URL: "${scheme}://${host}-backend${uri}"

  # Client information summary
  X-Client-Info: "IP: ${remote_addr}, Agent: ${http_user_agent:unknown}"

  # Request summary
  X-Request-Summary: "Method=${request_method}, Host=${host}, Path=${uri}, Client=${remote_addr}"

  # Proxy chain information
  X-Proxy-Chain: "Forwarded: ${proxy_add_x_forwarded_for}"

  # Processing information
  X-Processing-Time: "Started at ${time_iso8601} using ${server_protocol}"

Usage Examples

Basic Request Information

kind: HTTPServer
name: basic-vars-demo
port: 10080
rules:
  - paths:
    - pathPrefix: /
      backend: my-backend
      setHeaders:
        X-Method: "$request_method"
        X-Path: "$uri"
        X-Client-IP: "$remote_addr"
        X-Timestamp: "$time_iso8601"

API Gateway Headers

setHeaders:
  # API versioning
  X-API-Version: "${arg_version:v1}"
  X-API-Key: "${http_x_api_key:none}"

  # Request tracking
  X-Request-ID: "${http_x_request_id:auto-generated}"
  X-Trace-ID: "${http_x_trace_id:${time_msec}}"

  # Client information
  X-Client-IP: "$remote_addr"
  X-User-Agent: "$http_user_agent"
  X-Forwarded-For: "$proxy_add_x_forwarded_for"

Debugging Headers

setHeaders:
  # Full request debugging
  Debug-Method: "$request_method"
  Debug-URI: "$request_uri"
  Debug-Query: "$query_string"
  Debug-Host: "$http_host"
  Debug-Content-Type: "${content_type:none}"
  Debug-Content-Length: "${content_length:0}"
  Debug-User-Agent: "$http_user_agent"
  Debug-Request-Time: "$request_time"

Load Balancer Headers

setHeaders:
  # Upstream information
  X-Upstream-Server: "${scheme}://${host}"
  X-Original-Host: "$http_host"
  X-Original-URI: "$request_uri"

  # Load balancing info
  X-LB-Method: "roundrobin"
  X-LB-Timestamp: "$time_iso8601"
  X-Client-Real-IP: "$remote_addr"

Testing Variables

To test your nginx variables configuration:

Apply the configuration:

egctl create -f example/config/test-nginx-header-vars.yaml

Send test requests:

# Basic request
curl -H "User-Agent: MyApp/1.0" \
     -H "X-API-Key: test123" \
     "http://localhost:10080/api/users?page=1&debug=true"

# Request with cookies
curl -H "Cookie: session_id=sess_abc123; user_pref=dark_mode" \
     "http://localhost:10080/profile"

# POST request with content
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"name":"test"}' \
     "http://localhost:10080/api/create"

Check backend logs to see the populated header values.

Best Practices

1. Use Default Values

Always provide sensible defaults for variables that might not be present:

X-Version: "${arg_version:v1.0}"       # Good
X-Version: "$arg_version"              # Bad - might be empty

2. Sanitize Sensitive Information

Be careful with variables that might contain sensitive data:

# Good - mask sensitive tokens
X-Auth-Present: "${http_authorization:false}"

# Bad - might expose sensitive data
X-Auth-Token: "$http_authorization"

3. Use Descriptive Header Names

Choose clear, descriptive header names:

X-Client-IP: "$remote_addr"            # Good
X-IP: "$remote_addr"                   # Less clear

Organize headers logically:

setHeaders:
  # Client information
  X-Client-IP: "$remote_addr"
  X-Client-Agent: "$http_user_agent"

  # Request information
  X-Request-Method: "$request_method"
  X-Request-Path: "$uri"

  # Timing information
  X-Request-Time: "$time_iso8601"

Common Use Cases

1. Microservices Communication

Pass request context to downstream services:

setHeaders:
  X-Original-Method: "$request_method"
  X-Original-URI: "$request_uri"
  X-Client-IP: "$remote_addr"
  X-Request-ID: "${http_x_request_id:${msec}}"

2. Security Headers

Add security and tracking information:

setHeaders:
  X-Forwarded-Proto: "$scheme"
  X-Real-IP: "$remote_addr"
  X-Forwarded-For: "$proxy_add_x_forwarded_for"
  X-Request-Start: "$msec"

3. API Gateway

Standardize API request information:

setHeaders:
  X-API-Gateway: "easegress"
  X-API-Version: "${arg_version:v1}"
  X-Client-ID: "${http_x_client_id:anonymous}"
  X-Rate-Limit-Key: "${remote_addr}-${http_x_api_key:none}"

4. Debugging and Monitoring

Add comprehensive debugging information:

setHeaders:
  X-Debug-Method: "$request_method"
  X-Debug-Path: "$uri"
  X-Debug-Query: "$query_string"
  X-Debug-Client: "$remote_addr"
  X-Debug-Timestamp: "$time_iso8601"
  X-Debug-Protocol: "$server_protocol"