You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ml...@apache.org on 2025/04/29 20:44:42 UTC
(trafficserver) branch mlibbey-patch-1 created (now 200516b007)
This is an automated email from the ASF dual-hosted git repository.
mlibbey pushed a change to branch mlibbey-patch-1
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
at 200516b007 Minor header_rewrite doc cleanup
This branch includes the following new commits:
new 200516b007 Minor header_rewrite doc cleanup
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(trafficserver) 01/01: Minor header_rewrite doc cleanup
Posted by ml...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
mlibbey pushed a commit to branch mlibbey-patch-1
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
commit 200516b0071281b0447410043dc00bed4d45c805
Author: mlibbey <ml...@apache.org>
AuthorDate: Tue Apr 29 13:44:33 2025 -0700
Minor header_rewrite doc cleanup
- Fixed a few examples (where the default hook wouldn't work)
- Few formatting typos
- Added whitespace for some operators for consistency.
---
doc/admin-guide/plugins/header_rewrite.en.rst | 88 ++++++++++++++-------------
1 file changed, 46 insertions(+), 42 deletions(-)
diff --git a/doc/admin-guide/plugins/header_rewrite.en.rst b/doc/admin-guide/plugins/header_rewrite.en.rst
index c6da5747de..f6de468fd0 100644
--- a/doc/admin-guide/plugins/header_rewrite.en.rst
+++ b/doc/admin-guide/plugins/header_rewrite.en.rst
@@ -114,12 +114,14 @@ Rewriting Rules
Header rewriting rules consist of zero or more `Conditions`_ followed by one or
more `Operators`_. Conditions are used to limit the requests which will be
-affected by the operator(s). Additionally, both conditions and operators may
-have flags which modify their behavior.
+affected by the operator(s), and define when the ruleset is run during the
+transaction (through the `Hook Conditions`_). Additionally, both conditions
+and operators may have flags which modify their behavior.
A complete rule, consisting of two conditions and a single operator might look
like the following::
+ cond %{READ_RESPONSE_HDR_HOOK} [AND]
cond %{STATUS} >399 [AND]
cond %{STATUS} <500
set-status 404
@@ -400,7 +402,7 @@ HTTP-CNTL
cond %{HTTP-CNTL:<controller>}
This condition allows you to check the state of various HTTP controls. The controls
-are of the same name as for `set-http-cntl`. This condition returns a ``true`` or
+are of the same name as for `set-http-cntl`_. This condition returns a ``true`` or
``false`` value, depending on the state of the control. For example::
cond %{HTTP-CNTL:LOGGING} [NOT]
@@ -489,7 +491,7 @@ possible parts being
%{IP:SERVER} Upstream (next-hop) server IP address (typically origin, or parent)
%{IP:OUTBOUND} ATS's outbound IP address, that was used to connect upstream (next-hop)
-Note that both `%{IP:SERVER}` and `%{IP:OUTBOUND}` can be unset, in which case the
+Note that both ``%{IP:SERVER}`` and ``%{IP:OUTBOUND}`` can be unset, in which case the
empty string is returned. The common use for this condition is
actually as a value to an operator, e.g. ::
@@ -537,7 +539,7 @@ within a rule, and not across rules.
This condition may be most useful as a value to an operand, such as::
cond %{HEADER:X-Foo} /foo-(.*)/
- set-header X-Foo %{LAST-CAPTURE:1}"
+ set-header X-Foo %{LAST-CAPTURE:1}
METHOD
~~~~~~~
@@ -760,7 +762,7 @@ EXT The substring match only applies to the file extension following a dot.
====== ========================================================================
**Note**: At most, one of ``[PRE]``, ``[SUF]``, ``[MID]``, or ``[EXT]`` may be
-used at any time. They can however be used together with ``[NOCASE]]`` and the
+used at any time. They can however be used together with ``[NOCASE]`` and the
other flags.
Operators
@@ -895,15 +897,15 @@ send a 500 status code to the client with the desired response. If this is trigg
on any error status code, that original status code will be sent to the client.
**Note**: This config should only be set using READ_RESPONSE_HDR_HOOK
-An example config would look like
+An example config would look like::
cond %{READ_RESPONSE_HDR_HOOK}
- set-body-from http://www.example.com/second
+ set-body-from http://www.example.com/second
Where ``http://www.example.com/second`` is the destination to retrieve the custom response from.
This can be enabled per-mapping or globally.
Ensure there is a remap rule for the second endpoint as well!
-An example remap config would look like
+An example remap config would look like::
map /first http://www.example.com/first @plugin=header_rewrite.so @pparam=cond1.conf
map /second http://www.example.com/second
@@ -953,7 +955,7 @@ the appropriate logs even when the debug tag has not been enabled. For
additional information on |TS| debugging statements, refer to
:ref:`developer-debug-tags` in the developer's documentation.
-**Note**: This operator is deprecated, use the `set-http-cntl` operator instead,
+**Note**: This operator is deprecated, use the `set-http-cntl`_ operator instead,
with the ``TXN_DEBUG`` control.
set-destination
@@ -1069,7 +1071,7 @@ When invoked, and when ``<value>`` is any of ``1``, ``true``, or ``TRUE``, this
operator causes |TS| to abort further request remapping. Any other value and
the operator will effectively be a no-op.
-**Note**: This operator is deprecated, use the `set-http-cntl` operator instead,
+**Note**: This operator is deprecated, use the `set-http-cntl`_ operator instead,
with the ``SKIP_REMAP`` control.
set-cookie
@@ -1184,7 +1186,7 @@ As another example, a remap rule might use the `set-destination`_ operator to
change just the hostname via::
cond %{HEADER:X-Mobile} = "foo"
- set-destination HOST foo.mobile.bar.com [L]
+ set-destination HOST foo.mobile.bar.com
Requests vs. Responses
======================
@@ -1390,8 +1392,8 @@ by setting the hook context and then removing the cookie and basic
authentication headers.::
cond %{READ_RESPONSE_HDR_HOOK}
- rm-header Set-Cookie
- rm-header WWW-Authenticate
+ rm-header Set-Cookie
+ rm-header WWW-Authenticate
Count Teapots
-------------
@@ -1399,8 +1401,9 @@ Count Teapots
Maintains a counter statistic, which is incremented every time an origin server
has decided to be funny by returning HTTP 418::
+ cond %{READ_RESPONSE_HDR_HOOK}
cond %{STATUS} =418
- counter plugin.header_rewrite.teapots
+ counter plugin.header_rewrite.teapots
Normalize Statuses
------------------
@@ -1413,7 +1416,7 @@ the origin server with ``404``::
cond %{SEND_RESPONSE_HDR_HOOK}
cond %{STATUS} >399
cond %{STATUS} <500
- set-status 404
+ set-status 404
Remove Cache Control to Origins
-------------------------------
@@ -1422,8 +1425,8 @@ Removes cache control related headers from requests before sending them to an
origin server::
cond %{SEND_REQUEST_HDR_HOOK}
- rm-header Cache-Control
- rm-header Pragma
+ rm-header Cache-Control
+ rm-header Pragma
Enable Debugging Per-Request
----------------------------
@@ -1433,7 +1436,7 @@ header is present in the client request::
cond %{READ_REQUEST_HDR_HOOK}
cond %{CLIENT-HEADER:X-Debug} =supersekret
- set-debug
+ set-http-cntl TXN_DEBUG on
Remove Internal Headers
-----------------------
@@ -1442,8 +1445,8 @@ Removes special internal/development headers from origin responses, unless the
client request included a special debug header::
cond %{CLIENT-HEADER:X-Debug} =keep [NOT]
- rm-header X-Debug-Foo
- rm-header X-Debug-Bar
+ rm-header X-Debug-Foo
+ rm-header X-Debug-Bar
Return Original Method in Response Header
-----------------------------------------
@@ -1452,7 +1455,7 @@ This rule copies the original HTTP method that was used by the client into a
custom response header::
cond %{SEND_RESPONSE_HDR_HOOK}
- set-header X-Original-Method %{METHOD}
+ set-header X-Original-Method %{METHOD}
Useless Example From Purpose
----------------------------
@@ -1460,26 +1463,27 @@ Useless Example From Purpose
Even that useless example from `Purpose`_ in the beginning of this document is
possible to accomplish::
+ cond %{READ_RESPONSE_HDR_HOOK}
cond %{INBOUND:LOCAL-PORT} =8090
cond %{METHOD} =HEAD
cond %{CLIENT-HEADER:Accept-Language} /es-py/ [NOT]
cond %{STATUS} =304 [OR]
cond %{RANDOM:500} >290
- set-status 403
+ set-status 403
-Add Cache Control Headers Based on Origin Path
-----------------------------------------------
+Add Cache Control Headers Based on URL Path
+-------------------------------------------
-This rule adds cache control headers to CDN responses based matching the origin
+This rule adds cache control headers to CDN responses based matching the
path. One provides a max age and the other provides a "no-cache" statement to
two different file paths. ::
cond %{SEND_RESPONSE_HDR_HOOK}
cond %{CLIENT-URL:PATH} /examplepath1/
- add-header Cache-Control "max-age=3600" [L]
+ add-header Cache-Control "max-age=3600"
cond %{SEND_RESPONSE_HDR_HOOK}
cond %{CLIENT-URL:PATH} /examplepath2\/examplepath3\/.*/
- add-header Cache-Control "no-cache" [L]
+ add-header Cache-Control "no-cache"
Redirect when the Origin Server Times Out
-----------------------------------------
@@ -1490,7 +1494,7 @@ Query string when the Origin server times out or the connection is refused::
cond %{SEND_RESPONSE_HDR_HOOK}
cond %{STATUS} =502 [OR]
cond %{STATUS} =504
- set-redirect 302 http://different_origin.example.com/%{CLIENT-URL:PATH} [QSA]
+ set-redirect 302 http://different_origin.example.com/%{CLIENT-URL:PATH} [QSA]
Check for existence of a header
-------------------------------
@@ -1502,7 +1506,7 @@ already set to some value, and the status code is a 2xx::
cond %{HEADER:Cache-Control} ="" [AND]
cond %{STATUS} >199 [AND]
cond %{STATUS} <300
- set-header Cache-Control "max-age=600, public"
+ set-header Cache-Control "max-age=600, public"
Add HSTS
--------
@@ -1511,8 +1515,8 @@ Add the HTTP Strict Transport Security (HSTS) header if it does not exist and th
cond %{READ_RESPONSE_HDR_HOOK} [AND]
cond %{HEADER:Strict-Transport-Security} ="" [AND]
- cond %{INBOUND:TLS} /./
- set-header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
+ cond %{INBOUND:TLS} ="" [NOT]
+ set-header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
This is mostly used by being attached to a remap rule that maps to a host known to support TLS. If
the parallel `OUTBOUND` supported is added then this could be done by checking for inbound TLS both
@@ -1531,7 +1535,7 @@ configuration.::
cond %{SEND_RESPONSE_HDR_HOOK}
cond %{ACCESS:/path/to/the/healthcheck/file.txt} [NOT,OR]
- set-header Connection "close"
+ set-header Connection "close"
Use Internal header to pass data
--------------------------------
@@ -1541,7 +1545,7 @@ this to pass data to different |TS| systems. For instance, a series of remap rul
could each be tagged with a consistent name to make finding logs easier.::
cond %{REMAP_PSEUDO_HOOK}
- set-header @PropertyName "someproperty"
+ set-header @PropertyName "someproperty"
(Then in :file:`logging.yaml`, log ``%<{@PropertyName}cqh>``)
@@ -1556,17 +1560,17 @@ Remove Client Query Parameters
The following ruleset removes any query parameters set by the client.::
cond %{REMAP_PSEUDO_HOOK}
- rm-destination QUERY
+ rm-destination QUERY
Remove only a few select query parameters::
cond %{REMAP_PSEUDO_HOOK}
- rm-destination QUERY foo,bar
+ rm-destination QUERY foo,bar
Keep only a few select query parameters -- removing the rest::
cond %{REMAP_PSEUDO_HOOK}
- rm-destination QUERY foo,bar [I]
+ rm-destination QUERY foo,bar [I]
Mimic X-Debug Plugin's X-Cache Header
-------------------------------------
@@ -1576,11 +1580,11 @@ the ``CACHE`` condition results to a header.::
cond %{SEND_RESPONSE_HDR_HOOK} [AND]
cond %{HEADER:All-Cache} ="" [NOT]
- set-header All-Cache "%{HEADER:All-Cache}, %{CACHE}"
+ set-header All-Cache "%{HEADER:All-Cache}, %{CACHE}"
cond %{SEND_RESPONSE_HDR_HOOK} [AND]
cond %{HEADER:All-Cache} =""
- set-header All-Cache %{CACHE}
+ set-header All-Cache %{CACHE}
Add Identifier from Server with Data
------------------------------------
@@ -1592,7 +1596,7 @@ the client where the requested data was served from.::
cond %{SEND_RESPONSE_HDR_HOOK} [AND]
cond %{HEADER:ATS-SRVR-UUID} ="" [OR]
cond %{CACHE} ="hit-fresh"
- set-header ATS-SRVR-UUID %{ID:UNIQUE}
+ set-header ATS-SRVR-UUID %{ID:UNIQUE}
Apply rate limiting for some select requests
--------------------------------------------
@@ -1602,7 +1606,7 @@ limiting to the request.::
cond %{REMAP_PSEUDO_HOOK} [AND]
cond %{CLIENT-HEADER:Some-Special-Header} ="yes"
- run-plugin rate_limit.so "--limit=300 --error=429"
+ run-plugin rate_limit.so "--limit=300 --error=429"
Check the ``PATH`` file extension
---------------------------------
@@ -1611,4 +1615,4 @@ This rule will deny all requests for URIs with the ``.php`` file extension::
cond %{REMAP_PSEUDO_HOOK} [AND]
cond %{CLIENT-URL:PATH} ="php" [EXT,NOCASE]
- set-status 403
+ set-status 403