Rewrite variables

A rewrite variable is an object that stores a dynamic value like an entry path of a request or a session id. Rewrite variables are represented as strings in the format %<variable name>% or %<variable name>[argument]%. They are, for example, useful to define generic rewrite rules independent of the selected mapping, virtual host, or back-end group.

For pattern and substitution:

  • Request Actions
  • Response Actions
  • URL Encryption
  • CSRF Tokens
  • Deny Rules
  • Allow Rules

For redirect locations:

  • Reverse Proxy >> Mapping detail page >> tab Access >> Denied access URL
  • Reverse Proxy >> Mapping detail page >> tab URL Encryption >> Invalid URL redirect location
  • Reverse Proxy >> Mapping detail page >> tab CSRF Tokens >> Invalid token redirect location
  • Maintenance page redirects can be configured in the Expert Settings.

  • To enable/disable maintenance page redirect in the GUI, go to:

    • Reverse Proxy >> Virtual Host detail page >> tab Basic >> Show maintenance page
    • Reverse Proxy >> Mapping detail page >> tab Basic >> Show maintenance page

For variable-specific exceptions, see the table below.

List of rewrite variables

Variable names in the table starting with %ENTRY... refer to front-end use, while %BACKEND... refer to back-end use. Variables with a different naming scheme are either specified in the description column or of general use.

Variable name

Description

Not available in

%ENTRYPROTOCOL%

Current request protocol from the client, HTTP or HTTPS.

  • Redirect locations

%ENTRYHOST%

Entry host of the current mapping, without port.

  • Redirect locations

%ENTRYPORT%

Entry host port number of the current mapping.

  • Redirect locations

%ENTRYDIR% and %ENTRYDIR[<mapping>]%

Entry path of the current mapping and the specified mapping name trimmed of trailing slashes, empty for root entry path.

Example:
/webmail/inbox

  • Mappings with a regex entry path

%ENTRYPATH% and %ENTRYPATH[<mapping>]%

Same as %ENTRYDIR% but also trimmed of leading slashes.

Example:
mailapplication/inbox

  • Mappings with a regex entry path

%BACKENDDIR% and %BACKENDDIR[<mapping>]%

Back-end path of the current mapping trimmed of trailing slashes, empty for root back-end path.

Example:
/mailapplication/inbox

  • Mappings with a regex entry path

%BACKENDPATH% and %BACKENDPATH[<mapping>]%

Same as %BACKENDDIR% but also trimmed of leading slashes.

Example:
mailapplication/inbox

  • Mappings with a regex entry path

%BACKENDPROTOCOL%

Back-end protocol, http or https.

  • Redirect locations

%BACKENDHOSTNAME%

Back-end host for this request is dynamically set based on the current load-balancing back-end host, without port.

  • Redirect locations

%BACKENDPORT%

Port number of back-end host.

  • Redirect locations

%BACKENDHOST%

Combined value of back-end host and port – omitting default ports: 80, 443.

  • Redirect locations

%VHCOOKIEDOMAIN%

The cookie domain is configured in the virtual host.

  • Redirect locations

%REQUESTID%

Current request id.

  • Redirect locations
  • Patterns

%SESSIONID%

Current session id; “<n/a>” if no session is available,

  • Redirect locations
  • Patterns

%SSL_SESSION_ID%

Front-end SSL session ID, same value as the environment cookie AL_ENV_SSL_SESSION_ID.

  • Patterns

%SSL_PROTOCOL%

Front-end SSL protocol, same value as the environment cookie AL_ENV_SSL_PROTOCOL.

  • Patterns

%SSL_CIPHER%

Front-end SSL cipher suite, same value as the environment cookie AL_ENV_SSL_CIPHER.

  • Patterns

%SSL_CLIENT_S_DN%

Front-end SSL client subject name, same value as the environment cookie AL_ENV_SSL_CLIENT_S_DN.

  • Patterns

%SESSIONTIMINGINFO%

Timing information in seconds.
{remaining session idle timeout}:{remaining session lifetime}

  • Redirect locations
  • Patterns

%AUDITTOKEN%

Current audit token.

  • Redirect locations
  • Patterns

%REMOTEADDR%

Current IP address of the client (front-end).

  • Redirect locations
  • Patterns

%ROLES%

Role information, all timings in seconds:
{role1 name}:{remaining role1 idle timeout}:{remaining role1 lifetime},{role2 name}:{remaining role2 idle timeout}:{remaining role2 lifetime},...

  • Redirect locations
  • Patterns

%ENTRYADDR%

IP address of current entry host.

  • Redirect locations
  • Patterns

Example

The following example demonstrates how an incoming URL such as https://example.com/webmail/inbox/index.html can be rewritten using the related variables.

URL part

Related variable

Example values

Entry protocol

%ENTRYPROTOCOL%

https

Entry host

%ENTRYHOST%

example.com

Entry path

%ENTRYPATH%

webmail/inbox

Back-end protocol

%BACKENDPROTOCOL%

http

Back-end host

%BACKENDHOST%

mserv.net.local:8080

Back-end path

%BACKENDPATH%

mailapplication/inbox

Using the variables and values from the table above, we get the following solution:

Incoming URL

https://example.com/webmail/inbox/index.html

Rewrite from

%ENTRYPROTOCOL%://%ENTRYHOST%/%ENTRYPATH%(/.*)?

Rewrite to

%BACKENDPROTOCOL%://%BACKENDHOST%/%BACKENDPATH%$1

Back-end URL results in

http://mserv.net.local:8080/mailapplication/inbox/index.html

 
Functional limitation

If a variable is unavailable, e.g., %SSL_CIPHER% in case of HTTP, the action, e.g., Replace with will not be processed.

Literal mode

All variables are treated as literal values - characters do not have any special regular expression significance. This means, that the variable value www.example.com just matches www.example.com and not www-example/com nor wwwXexampleYcom.

Technically this is achieved by internally surrounding all variables by an extra \Q .. \E span.