parent.config¶
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.
Format¶
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_host
A requested hostname.
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
orhttps
.
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:
get
post
put
trace
time
A time range, such as 08:00-14:00, during which the parent cache is used to serve requests.
src_ip
A client IP address.
internal
A boolean value,
true
orfalse
, 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
(hostname or IP address):port[|weight][&hash name][,another host]An ordered list of parent servers, separated by commas or semicolons. 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. If there are multiple IP addresses associated with the hostname, Traffic Server will treat them as a single entity when tracking health. Example:
parent="p1.x.com:8080, 192.168.0.3:80, 192.168.0.4:80"
An optional weight can be specified after a pipe (
|
). This example has one parent take 20% (2/(2+3+5)) of the requests, another 30% (3/(2+3+5)), and the last 50% (5/(2+3+5)):parent="p1.x.com:8080|2.0, 192.168.0.3:80|3.0, 192.168.0.4:80|5.0"
If
round_robin
is set toconsistent_hash
, you may add a uniquehash string
following theweight
for each parent. Thehash string
must start with&
and is used to build both the primary and secondary rings using the
hash string
for each parent insted of the parents
hostname
orip address
. This can be useful so that two different hosts may be used to cache the same requests. Example:parent="p1.x.com:80|1.0&abcdef, p2.x.com:80|1.0&xyzl, p3.x.com:80|1.0&ldffg" round_robin=consistent_hash
secondary_parent
An optional ordered list of secondary parent servers in the same format as parent. This optional list may only be used when
round_robin
is set toconsistent_hash
. If the request cannot be handled by the first parent server chosen from theparent
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 theparent
list.secondary_mode
One of the following values:
1
This is the default. The parent selection will first attempt to choose a parent from theparent
list. If the chosen parent is not available or marked down then another parent will be chosen from thesecondary_parent
list. Choices in thesecondary_parent
list will be exhausted before attempting to choose another parent from theparent
list.2
The parent selection will first attempt to choose a parent from theparent
list. If the chosen parent is not available or marked down then another parent will be chosen from theparent
list. Choices in theparent
list will be exhausted before attempting to choose another parent from thesecondary_parent
list.3
The parent selection will first attempt to choose a parent from theparent
list.If the chosen parent is marked down then another parent will be chosen from the
secondary_parent
list. Thesecondary_parent
list will be exhausted before attempting to choose another parent in theparent
list.If the chosen parent is unavailable but not marked down then another parent will be chosen from the
parent
list. Theparent
list will be exhausted before attempting to choose another parent in thesecondary_parent
list.
parent_is_proxy
One of the following values:
true
- This is the default. The list of parents and secondary parents are proxy cache servers.false
- The list of parents and secondary parents are the origin serversgo_direct
flag is ignored and origins are selected using the specifiedround_robin
algorithm. The FQDN is removed from the http request line.
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 bymax_simple_retries
which is set to 1 by default.unavailable_server_retry
- If the parent returns a 503 response or if the reponse matches a list of http 5xx responses defined inunavailable_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 bymax_unavailable_server_retries
which is set to 1 by default.both
- This enables bothsimple_retry
andunavailable_server_retry
as described above.
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. Ifparent_retry
is set tosimple_retry
orboth
a 404 reponse from a parent origin server will cause the request to be retried using a new parent at most 1 to 5 times as configured bymax_simple_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: machineproxy1
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 theconsistent_hash
selection strategy, and a random query string would prevent a consistent parent selection.
ignore_self_detect
One of the following values:
true
- Ignore the marked down status of a host, typically the local host,when the reason code is Reason::SELF_DETECT and use the host as if it were marked up.
false
- The default. Do not ignore the host status.
Examples¶
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