The name and command line parameters of an admin-provided executable
for redirecting clients or adjusting/replacing client request URLs.
This helper is consulted after the received request is cleared by
http_access and adapted using eICAP/ICAP services (if any). If the
helper does not redirect the client, Squid checks adapted_http_access
and may consult the cache or forward the request to the next hop.
For each request, the helper gets one line in the following format:
[channel-ID <SP>] request-URL [<SP> extras] <NL>
Use url_rewrite_extras to configure what Squid sends as 'extras'.
The helper must reply to each query using a single line:
[channel-ID <SP>] result [<SP> kv-pairs] <NL>
The result section must match exactly one of the following outcomes:
OK [status=30N] url="..."
Redirect the client to a URL supplied in the 'url' parameter.
Optional 'status' specifies the status code to send to the
client in Squid's HTTP redirect response. It must be one of
the standard HTTP redirect status codes: 301, 302, 303, 307,
or 308. When no specific status is requested, Squid uses 302.
OK rewrite-url="..."
Replace the current request URL with the one supplied in the
'rewrite-url' parameter. Squid fetches the resource specified
by the new URL and forwards the received response (or its
cached copy) to the client.
WARNING: Avoid rewriting URLs! When possible, redirect the
client using an "OK url=..." helper response instead.
Rewriting URLs may create inconsistent requests and/or break
synchronization between internal client and origin server
states, especially when URLs or other message parts contain
snippets of that state. For example, Squid does not adjust
Location headers and embedded URLs after the helper rewrites
the request URL.
OK
Keep the client request intact.
ERR
Keep the client request intact.
BH [message="..."]
A helper problem that should be reported to the Squid admin
via a level-1 cache.log message. The 'message' parameter is
reserved for specifying the log message.
In addition to the kv-pairs mentioned above, Squid also understands
the following optional kv-pairs in URL rewriter responses:
clt_conn_tag=TAG
Associates a TAG with the client TCP connection.
The clt_conn_tag=TAG pair is treated as a regular transaction
annotation for the current request and also annotates future
requests on the same client connection. A helper may update
the TAG during subsequent requests by returning a new kv-pair.
Helper messages contain the channel-ID part if and only if the
url_rewrite_children directive specifies positive concurrency. As a
channel-ID value, Squid sends a number between 0 and concurrency-1.
The helper must echo back the received channel-ID in its response.
By default, Squid does not use a URL rewriter.