Docs

Configuration: placeholders

This page describes placeholder variables that can be used in KDL directives. There are two kinds: environment variable placeholders (resolved when the configuration file is loaded) and request/logging placeholders (resolved per request).

Environment variable placeholders

Environment variable placeholders let you reference environment variables directly in your KDL configuration. They are resolved when the server starts, so the values are baked into the parsed configuration.

Syntax

{env:VARIABLE_NAME}

Behavior

  • If the environment variable exists, its value is substituted in place of the placeholder.
  • If the environment variable is missing or unset, the placeholder text is kept as-is (for example, {env:MY_VAR}).
  • Unknown placeholder kinds (anything other than env) are also kept as-is.

Examples

Given these environment variables:

export APP_ROOT="/var/www/app"
export DB_HOST="db.example.com"

You can use them in a KDL configuration like this:

site {
  root "{env:APP_ROOT}/public"

  reverseProxy {
    to "http://{env:DB_HOST}:5432"
  }
}

At load time, these resolve to:

site {
  root "/var/www/app/public"

  reverseProxy {
    to "http://db.example.com:5432"
  }
}

Notes

  • Environment variable placeholders work in any string value throughout the KDL configuration file.
  • They are resolved early, before the configuration is parsed, so they behave like compile-time constants.
  • If you need a variable that changes at runtime (per request), use one of the request placeholders instead.

Placeholders

Ferron supports the following placeholders for header values, subconditions, reverse proxying, and redirect destinations:

  • {path} - the request URI with path (for example, /index.html)
  • {path_and_query} - the request URI with path and query string (for example, /index.html?param=value)
  • {method} - the request method
  • {version} - the HTTP version of the request
  • {header:<header_name>} - the value of a header with the specified name (<header_name> is replaced with the name of the header, for example, Content-Type)
  • {scheme} - the scheme of the request URI (http or https), applicable only for subconditions, reverse proxying and redirect destinations.
  • {client_ip} - the client IP address, applicable only for subconditions, reverse proxying and redirect destinations.
  • {client_port} - the client port number, applicable only for subconditions, reverse proxying and redirect destinations.
  • {client_ip_canonical} (Ferron 2.3.0 or newer) - the client IP address in canonical form (IPv4-mapped IPv6 addresses, like ::ffff:127.0.0.1, are converted to IPv4, like 127.0.0.1), applicable only for subconditions, reverse proxying and redirect destinations.
  • {server_ip} - the server IP address, applicable only for subconditions, reverse proxying and redirect destinations.
  • {server_port} - the server port number, applicable only for subconditions, reverse proxying and redirect destinations.
  • {server_ip_canonical} (Ferron 2.3.0 or newer) - the server IP address in canonical form (IPv4-mapped IPv6 addresses, like ::ffff:127.0.0.1, are converted to IPv4, like 127.0.0.1), applicable only for subconditions, reverse proxying and redirect destinations.

Log placeholders

Ferron 2.0.0 and newer supports the following placeholders for access logs:

  • {path} - the request URI with path (for example, /index.html)
  • {path_and_query} - the request URI with path and query string (for example, /index.html?param=value)
  • {method} - the request method
  • {version} - the HTTP version of the request
  • {header:<header_name>} - the value of a header with the specified name (<header_name> is replaced with the name of the header, for example, Content-Type; -, if header is missing)
  • {scheme} - the scheme of the request URI (http or https).
  • {client_ip} - the client IP address.
  • {client_port} - the client port number.
  • {client_ip_canonical} (Ferron 2.3.0 or newer) - the client IP address in canonical form (IPv4-mapped IPv6 addresses, like ::ffff:127.0.0.1, are converted to IPv4, like 127.0.0.1).
  • {server_ip} - the server IP address.
  • {server_port} - the server port number.
  • {server_ip_canonical} (Ferron 2.3.0 or newer) - the server IP address in canonical form (IPv4-mapped IPv6 addresses, like ::ffff:127.0.0.1, are converted to IPv4, like 127.0.0.1).
  • {auth_user} - the username of the authenticated user (-, if not authenticated)
  • {timestamp} - the formatted timestamp of the entry
  • {status_code} - the HTTP status code of the response
  • {content_length} - the content length of the response (-, if not available)

These placeholders can be used both in log_format and in log_json additional property templates.