PARENT.CONFIG(5)

🌸 NAME 🌸

okay bestie, so parent.config is the Traffic Server parent cache configuration file 💖 and like, its whole thing is identifying the parent proxies you're using in a cache hierarchy. no cap. here's what you use it for:

• setting up parent cache hierarchies, with multiple parents AND parent failover 🔥
• configuring selected URL requests to bypass parent proxies 🙈

real talk: Traffic Server only even looks at parent.config when the parent caching option is enabled (go read "Configuring Traffic Server to Use a Parent Cache", it's giving prerequisites 💅).

And after you touch parent.config, you gotta run this to make it actually apply:

traffic_ctl config reload

periodt. no reload, no vibes. 😭

---

✨ FORMAT ✨

every single line in parent.config has to be a parent caching rule. Traffic Server recognizes three space-delimited tags, and the shape of it is:

primary_destination=value secondary_specifier=value action=value

the following list shows the possible primary destinations and their allowed values, and honestly? iconic lineup:

• dest_domain — a requested domain name, plus all its subdomains 🫶
• dest_host — a requested hostname
• dest_ip — a requested IP address, or a whole range of IP addresses separated by a dash (-)
• url_regex — a regular expression (regex) to be found in a URL ⭐

---

🎀 Secondary Specifiers 🎀

so the secondary specifiers are optional in parent.config. here's the list and their allowed values — but lowkey important: every line in parent.config must contain either a parent= or a go_direct= directive. no exceptions, bestie. 🚨

• 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 these:
  • get
  • post
  • put
  • trace
• time — a time range, like 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 or false, specifying if the rule should match (or not match) a transaction originating from an internal API. this one's useful for telling apart transactions that came from an ATS plugin 👑

---

🎀 Actions 🎀

and now the actions and their allowed values. sit up, this is the main character section 💅

• 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 can't be handled by the last parent server in the list, then it gets routed to the origin server. you can specify either a hostname or an IP address, but you must specify the port number. and if there are multiple IP addresses hanging off that hostname, Traffic Server treats them as a single entity when tracking health. example:

parent="p1.x.com:8080, 192.168.0.3:80, 192.168.0.4:80"

you can also throw an optional weight in there after a pipe (|). this example has one parent taking 20% (2/(2+3+5)) of the requests, another 30% (3/(2+3+5)), and the last one 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"

and if round_robin is set to consistent_hash, you may add a unique hash string following the weight for each parent. that hash string must start with &, and it's used to build both the primary and secondary rings using the hash string for each parent instead of the parent's hostname or ip address. super useful when two different hosts should be caching 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, same format as parent. this optional list may only be used when round_robin is set to consistent_hash. if the request can't be handled by the first parent server chosen from the parent list, then the request gets 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 reverts to trying alternative parents in the parent list. 🦋
• secondary_mode — one of the following values:
  • 1 — this is the default. parent selection first attempts to choose a parent from the parent list. if the chosen parent isn't available or is marked down, then another parent gets chosen from the secondary_parent list. choices in the secondary_parent list get exhausted before it attempts to choose another parent from the parent list.
  • 2 — parent selection first attempts to choose a parent from the parent list. if the chosen parent isn't available or is marked down, then another parent gets chosen from the parent list. choices in the parent list get exhausted before it attempts to choose another parent from the secondary_parent list.
  • 3 — parent selection first attempts to choose a parent from the parent list.
    • if the chosen parent is marked down, then another parent gets chosen from the secondary_parent list. the secondary_parent list gets exhausted before it attempts to choose another parent in the parent list. this depends on taking a parent down from a particular EDGE using traffic_ctl, like traffic_ctl host down sample.server.com. super handy during a maintenance window, or as a debugging aid when a user wants to take down specific parents. taking parents down with traffic_ctl causes the EDGE to ignore those parents immediately in parent selection logic.
    • if the chosen parent is unavailable but not marked down, then another parent gets chosen from the parent list. the parent list gets exhausted before it attempts to choose another parent in the secondary_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 servers. the go_direct flag is ignored and origins are selected using the specified round_robin algorithm. the FQDN is removed from the http request line. 😳
• parent_retry
  • simple_retry — if the parent returns a 404 response, or if the response matches a list of http 4xx and/or 5xx responses defined in simple_server_retry_responses, 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.
  • if not set, by default all response codes are considered a success, and parents will not be retried based on any HTTP response code.

NOTE: if a response code exists in both the simple and unavailable lists, and both is the retry type, then simple_retry takes precedence and unavailable_server_retry will not be used for that code. ⚠️

• simple_server_retry_responses — if parent_retry is set to either simple_retry or both, this parameter is a comma separated list of http 4xx and/or 5xx response codes that will invoke the simple_retry described in the parent_retry section. by default, simple_server_retry_responses is set to 404.
• 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 causes 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 causes 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 — the default. 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. and once the downed parent becomes available again, the traffic distribution returns to the pre-down state. 🌈✨
• latched — so the first parent in the list gets marked as primary, and it's literally always the chosen one until connection errors drag it down. When that happens, the next parent in the list becomes primary. And when the primary is the last parent in the list and gets marked down because of a connection error, it wraps all the way back to the first parent in the list. Newly chosen primary parents that are marked unavailable get restored if the failure retry time has elapsed and the transaction using the primary succeeds. iykyk 🫶

🦋 go_direct 🦋

Pick one of these, bestie:

• true — the default. Requests bypass parent hierarchies entirely and go straight to the origin server. no detours, main character energy 💅
• false — requests do not bypass parent hierarchies. they take the scenic route through the parents.

🌸 qstring 🌸

One of these values:

• consider — the default. Use the query string when finding a parent.
• ignore — do not consider the query string when finding a parent. This is especially useful when you're using the consistent_hash selection strategy, because a random query string would absolutely ruin your consistent parent selection. 😭

✨ ignore_self_detect ✨

One of the following:

• 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 💖

Okay so this first rule configures a parent cache hierarchy made of Traffic Server (which is the child, obviously) and two parents, p1.x.com and p2.x.com. Traffic Server forwards every request it can't 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

This next one 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. slay:

url_regex=politics prefix=/viewpoint go_direct=true

And this one configures Traffic Server to route http requests for example.com through parent servers — note that neither https nor www.example.com would match, so be careful 👀. Each url gets hashed to a specific parent. And if the chosen parent has been marked down? A parent from the secondary ring gets chosen for the retry. iconic:

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

---

👑 COPYRIGHT 👑

2026, dev@trafficserver.apache.org

---

and that's the whole page, bestie!! 💜 this was Traffic Server 9.2, dated Feb 12, 2026 — go forth and configure your parents, you absolute legend 🎀✨