.\" Man page generated from reStructuredText.
.
.TH "PARENT.CONFIG" "5" "January 24, 2017" "7.0" "Apache Traffic Server"
.SH NAME
parent.config \- Traffic Server parent cache configuration file
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
The \fI\%parent.config\fP file identifies the parent proxies used in an
cache hierarchy. Use this file to perform the following configuration:
.INDENT 0.0
.IP \(bu 2
Set up parent cache hierarchies, with multiple parents and parent
failover
.IP \(bu 2
Configure selected URL requests to bypass parent proxies
.UNINDENT
.sp
Traffic Server uses the \fI\%parent.config\fP file only when the parent
caching option is enabled (refer to \fIconfiguring\-traffic\-server\-to\-use\-a\-parent\-cache\fP).
.sp
After you modify the \fI\%parent.config\fP file, run the \fItraffic_ctl config reload\fP
command to apply your changes. When you apply the changes to one node in
a cluster, Traffic Server automatically applies the changes to all other
nodes in the cluster.
.SH FORMAT
.sp
Each line in the \fI\%parent.config\fP file must contain a parent caching
rule. Traffic Server recognizes three space\-delimited tags:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
primary_destination=value secondary_specifier=value  action=value
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following list shows the possible primary destinations and their
allowed values.
.INDENT 0.0
.TP
.B \fBdest_domain\fP
A requested domain name, and its subdomains.
.UNINDENT
.INDENT 0.0
.TP
.B \fBdest_host\fP
A requested hostname.
.UNINDENT
.INDENT 0.0
.TP
.B \fBdest_ip\fP
A requested IP address or range of IP addresses separated by a dash (\-).
.UNINDENT
.INDENT 0.0
.TP
.B \fBurl_regex\fP
A regular expression (regex) to be found in a URL
.UNINDENT
.sp
The secondary specifiers are optional in the \fI\%parent.config\fP file. The
following list shows the possible secondary specifiers and their allowed
values.
.INDENT 0.0
.TP
.B \fBport\fP
A requested URL port.
.UNINDENT
.INDENT 0.0
.TP
.B \fBscheme\fP
A request URL protocol: \fBhttp\fP or \fBhttps\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBprefix\fP
A prefix in the path part of a URL.
.UNINDENT
.INDENT 0.0
.TP
.B \fBsuffix\fP
A file suffix in the URL.
.UNINDENT
.INDENT 0.0
.TP
.B \fBmethod\fP
A request URL method. It can be one of the following:
.INDENT 7.0
.IP \(bu 2
get
.IP \(bu 2
post
.IP \(bu 2
put
.IP \(bu 2
trace
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBtime\fP
A time range, such as 08:00\-14:00, during which the parent cache is
used to serve requests.
.UNINDENT
.INDENT 0.0
.TP
.B \fBsrc_ip\fP
A client IP address.
.UNINDENT
.INDENT 0.0
.TP
.B \fBinternal\fP
A boolean value, \fBtrue\fP or \fBfalse\fP, 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.
.UNINDENT
.sp
The following list shows the possible actions and their allowed values.
.INDENT 0.0
.TP
.B \fBparent\fP
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.
.UNINDENT
.INDENT 0.0
.TP
.B \fBsecondary_parent\fP
An optional ordered list of secondary parent servers.  This optional
list may only be used when \fBround_robin\fP is set to \fBconsistent_hash\fP\&.
If the request cannot be handled by a parent server from the \fBparent\fP
list, then the request will be re\-tried from a server found in this list
using a consistent hash of the url.
.UNINDENT
.INDENT 0.0
.TP
.B \fBparent_is_proxy\fP
One of the following values:
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBtrue\fP \- This is the default.  The list of parents and secondary parents
are proxy cache servers.
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B \fBfalse\fP \- The list of parents and secondary parents are the origin
servers \fBgo_direct\fP flag is ignored and origins are selected using
the specified \fBround_robin\fP algorithm.  The FQDN is removed from
the http request line.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBparent_retry\fP
If \fBparent_is_proxy\fP is false, then you may configure \fBparent_retry\fP for one
of the following values:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBsimple_retry\fP \- 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 \fBmax_simple_retries\fP which is set to 1 by default.
.IP \(bu 2
\fBunavailable_server_retry\fP \- If the parent returns a 503 response or if the reponse matches
a list of http 5xx responses defined in \fBunavailable_server_retry_responses\fP, the currently selected
parent is marked down and a new parent is selected to retry the request.  The number of
retries is controlled by \fBmax_unavailable_server_retries\fP which is set to 1 by default.
.IP \(bu 2
\fBboth\fP \- This enables both \fBsimple_retry\fP and \fBunavailable_server_retry\fP as described above.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBunavailable_server_retry_responses\fP
If \fBparent_is_proxy\fP is false and \fBparent_retry\fP is set to either \fBunavailable_server_retry\fP or
\fBboth\fP, this parameter is a comma separated list of http 5xx response codes that will invoke the
\fBunavailable_server_retry\fP described in the \fBparent_retry\fP section.  By default, \fBunavailable_server_retry_responses\fP
is set to 503.
.UNINDENT
.INDENT 0.0
.TP
.B \fBmax_simple_retries\fP
By default the value for \fBmax_simple_retries\fP is 1.  It may be set to any value in the range 1 to 5.
If \fBparent_is_proxy\fP is false and \fBparent_retry\fP is set to \fBsimple_retry\fP or \fBboth\fP 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 by \fBmax_simple_retries\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBmax_unavailable_server_retries\fP
By default the value for \fBmax_unavailable_server_retries\fP is 1.  It may be set to any value in the range 1 to 5.
If \fBparent_is_proxy\fP is false and \fBparent_retry\fP is set to \fBunavailable_server_retries\fP or \fBboth\fP a 503 reponse
by default or any http 5xx response listed in the list \fBunavailable_server_retry_responses\fP 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 \fBmax_unavailable_server_retries\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBround_robin\fP
One of the following values:
.INDENT 7.0
.IP \(bu 2
\fBtrue\fP \- Traffic Server goes through the parent cache list in a
round robin\-based on client IP address.
.IP \(bu 2
\fBstrict\fP \- Traffic Server machines serve requests strictly in
turn. For example: machine \fBproxy1\fP serves the first request,
\fBproxy2\fP serves the second request, and so on.
.IP \(bu 2
\fBfalse\fP \- Round robin selection does not occur.
.IP \(bu 2
\fBconsistent_hash\fP \- 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.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBgo_direct\fP
One of the following values:
.INDENT 7.0
.IP \(bu 2
\fBtrue\fP \- requests bypass parent hierarchies and go directly to
the origin server.
.IP \(bu 2
\fBfalse\fP \- requests do not bypass parent hierarchies.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBqstring\fP
One of the following values:
.INDENT 7.0
.IP \(bu 2
\fBconsider\fP \- Use the query string when finding a parent.
.IP \(bu 2
\fBignore\fP \- Do not consider the query string when finding a parent.
.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
The following rule configures a parent cache hierarchy consisting of
Traffic Server (which is the child) and two parents, \fBp1.x.com\fP and
\fBp2.x.com\fP\&. Traffic Server forwards the requests it cannot serve to
the parent servers \fBp1.x.com\fP and \fBp2.x.com\fP in a round\-robin
fashion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
round_robin=true
dest_domain=. method=get parent="p1.x.com:8080; p2.y.com:8080" round_robin=true
round_robin=consistent_hash
dest_domain=. method=get parent="p1.x.com:8080|1.0; p2.y.com:8080|2.0" round_robin=consistent_hash
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following rule configures Traffic Server to route all requests
containing the regular expression \fBpolitics\fP and the path
\fB/viewpoint\fP directly to the origin server (bypassing any parent
hierarchies): \fBurl_regex=politics prefix=/viewpoint go_direct=true\fP
.sp
Every line in the \fI\%parent.config\fP file must contain either a
\fBparent=\fP or \fBgo_direct=\fP directive.
.SH COPYRIGHT
2015, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.