parent.config - Traffic Server parent cache configuration file
The parent.config file identifies the parent proxies used
in an cache hierarchy. Use this file to perform the following
configuration:
- Set up parent cache hierarchies, with multiple parents and parent
failover
- Configure selected URL requests to bypass parent proxies
Traffic Server uses the parent.config file only when the
parent caching option is enabled (refer to
configuring-traffic-server-to-use-a-parent-cache).
After you modify the parent.config file, run the
traffic_ctl config reload command to apply your changes.
Each line in the parent.config file must contain a parent
caching rule. Traffic Server recognizes three space-delimited tags:
primary_destination=value secondary_specifier=value action=value
The following list shows the possible primary destinations and
their allowed values.
- dest_domain
- A requested domain name, and its subdomains.
- dest_ip
- A requested IP address or range of IP addresses separated by a dash
(-).
- url_regex
- A regular expression (regex) to be found in a URL
The secondary specifiers are optional in the parent.config
file. The following list shows the possible secondary specifiers and their
allowed values. Every line in the parent.config file must contain
either a parent= or go_direct= directive.
- port
- A requested URL port.
- scheme
- A request URL protocol: http or https.
- prefix
- A prefix in the path part of a URL.
- suffix
- A file suffix in the URL.
- method
- A request URL method. It can be one of the following:
- time
- A time range, such as 08:00-14:00, during which the parent cache is used
to serve requests.
- internal
- A boolean value, true or false, specifying if the rule
should match (or not match) a transaction originating from an internal
API. This is useful to differentiate transaction originating from an ATS
plugin.
The following list shows the possible actions and their allowed
values.
- parent
- An ordered list of parent servers. If the request cannot be handled by the
last parent server in the list, then it will be routed to the origin
server. You can specify either a hostname or an IP address, but; you must
specify the port number.
- secondary_parent
- An optional ordered list of secondary parent servers. This optional list
may only be used when round_robin is set to consistent_hash.
If the request cannot be handled by the first parent server chosen from
the parent list, then the request will be re-tried from a server
found in this list using a consistent hash of the url. The parent servers
in this list will be exhausted before the selection function will revert
to trying alternative parents in the parent list.
- secondary_mode
- One of the following values:
- 1 This is the default. The parent selection will first attempt to
choose a parent from the parent list. If the chosen parent is not
available or marked down then another parent will be chosen from the
secondary_parent list. Choices in the secondary_parent list
will be exhausted before attempting to choose another parent from the
parent list.
- 2 The parent selection will first attempt to choose a parent from
the parent list. If the chosen parent is not available or marked
down then another parent will be chosen from the parent list.
Choices in the parent list will be exhausted before attempting to
choose another parent from the secondary_parent list.
- 3 The parent selection will first attempt to choose a parent from
the parent list.
- If the chosen parent is marked down then another parent will be chosen
from the secondary_parent list. The secondary_parent list
will be exhausted before attempting to choose another parent in the
parent list.
- If the chosen parent is unavailable but not marked down then another
parent will be chosen from the parent list. The parent list
will be exhausted before attempting to choose another parent in the
secondary_parent list.
- parent_retry
- simple_retry - If the parent origin server returns a 404 response
on a request a new parent is selected and the request is retried. The
number of retries is controlled by max_simple_retries which is set
to 1 by default.
- unavailable_server_retry - If the parent returns a 503 response or
if the response matches a list of http 5xx responses defined in
unavailable_server_retry_responses, the currently selected parent
is marked down and a new parent is selected to retry the request. The
number of retries is controlled by max_unavailable_server_retries
which is set to 1 by default.
- both - This enables both simple_retry and
unavailable_server_retry as described above.
- unavailable_server_retry_responses
- If parent_retry is set to either unavailable_server_retry or
both, this parameter is a comma separated list of http 5xx response
codes that will invoke the unavailable_server_retry described in
the parent_retry section. By default,
unavailable_server_retry_responses is set to 503.
- max_simple_retries
- By default the value for max_simple_retries is 1. It may be set to
any value in the range 1 to 5. If parent_retry is set to
simple_retry or both a 404 response from a parent origin
server will cause the request to be retried using a new parent at most 1
to 5 times as configured by max_simple_retries.
- max_unavailable_server_retries
- By default the value for max_unavailable_server_retries is 1. It
may be set to any value in the range 1 to 5. If parent_retry is set
to unavailable_server_retries or both a 503 response by
default or any http 5xx response listed in the list
unavailable_server_retry_responses from a parent origin server will
cause the request to be retried using a new parent after first marking the
current parent down. The request will be retried at most 1 to 5 times as
configured by max_unavailable_server_retries.
- round_robin
- One of the following values:
- true - Traffic Server determines the parent based on client IP
address.
- strict - Traffic Server machines serve requests strictly in turn.
For example: machine proxy1 serves the first request, proxy2
serves the second request, and so on.
- false - Round robin selection does not occur.
- consistent_hash - consistent hash of the url so that one parent is
chosen for a given url. If a parent is down, the traffic that would go to
the down parent is rehashed amongst the remaining parents. The other
traffic is unaffected. Once the downed parent becomes available, the
traffic distribution returns to the pre-down state.
- latched - The first parent in the list is marked as primary and is
always chosen until connection errors cause it to be marked down. When
this occurs the next parent in the list then becomes primary. The primary
will wrap back to the first parent in the list when it is the last parent
in the list and is marked down due to a connection error. Newly chosen
primary parents marked as unavailable will then be restored if the failure
retry time has elapsed and the transaction using the primary
succeeds.
- go_direct
- One of the following values:
- true - requests bypass parent hierarchies and go directly to the
origin server.
- false - requests do not bypass parent hierarchies.
- qstring
- One of the following values:
- consider - Use the query string when finding a parent.
- ignore - Do not consider the query string when finding a parent.
This is especially useful when using the consistent_hash selection
strategy, and a random query string would prevent a consistent parent
selection.
The following rule configures a parent cache hierarchy consisting
of Traffic Server (which is the child) and two parents, p1.x.com and
p2.x.com. Traffic Server forwards the requests it cannot serve to the
parent servers p1.x.com and p2.x.com in a round-robin
fashion:
dest_domain=. method=get parent="p1.x.com:8080; p2.y.com:8080" round_robin=true
The following rule configures Traffic Server to route all requests
containing the regular expression politics and the path
/viewpoint directly to the origin server (bypassing any parent
hierarchies):
url_regex=politics prefix=/viewpoint go_direct=true
The following configures Traffic Server to route http requests for
example.com (neither https nor www.example.com would match) through parent
servers. Each url will be hashed to a specific parent. If the chosen parent
has been marked down, a parent from the secondary ring will be chosen for
the retry.:
dest_host=example.com scheme=http parent="p1.x.com:80,p2.x.com:80" secondary_parent="p3.x.com:80,p4.x.com:80" round_robin=consistent_hash go_direct=false
2022, dev@trafficserver.apache.org