Delivery Services

“Delivery Services” are a very important construct in ATC. At their most basic, they are a source of content and a set of cache servers and configuration options used to distribute that content.

Delivery Services are modeled several times over, in the Traffic Ops database, in Traffic Portal forms and tables, and several times for various Traffic Ops API versions in the new Go Traffic Ops codebase. Go-specific data structures can be found at github.com/apache/trafficcontrol/lib/go-tc.DeliveryServiceV4. Rather than application-specific definitions, what follows is an attempt at consolidating all of the different properties and names of properties of Delivery Service objects throughout the ATC suite. The names of these fields are typically chosen as the most human-readable and/or most commonly-used names for the fields, and when reading please note that in many cases these names will appear camelCased or snake_cased to be machine-readable. Any aliases of these fields that are not merely case transformations of the indicated, canonical names will be noted in a table of aliases.

See also

The API reference for Delivery Service-related endpoints such as deliveryservices contains definitions of the Delivery Service object(s) returned and/or accepted by those endpoints.

See also

Delivery Service Requests

Active

Whether or not this Delivery Service is active on the CDN and can be served. A Delivery Service’s “active state” can be one of the three values listed below.

ACTIVE

The Delivery Service’s configuration is deployed to the appropriate cache servers when updates are Queued, and Traffic Router is made aware of its existence through CDN Snapshots.

PRIMED

The Delivery Service’s configuration is deployed to the appropriate cache servers when updates are Queued, but Traffic Router is not made aware of its existence through CDN Snapshots, so clients will not be routed for it.

INACTIVE

The Delivery Service’s configuration is not deployed to any cache servers when updates are Queued, nor is Traffic Router made aware of its existence through CDN Snapshots.

Changing a Delivery Service’s “active state” either to or from “ACTIVE” will require that a new Snapshot be taken. Likewise, a Queue Updates must be performed if the “active state” changes either to or from “INACTIVE”. Table Table 16 expresses these relationships exhaustively.

Table 16 Active State Transitions

Original State	New State	CDN Snapshot Required	Queue Updates Required
ACTIVE	PRIMED
ACTIVE	INACTIVE
PRIMED	ACTIVE
PRIMED	INACTIVE
INACTIVE	ACTIVE
INACTIVE	PRIMED

Changed in version ATCv7.1: In API version 5, introduced in ATC version 7.1 (tentative plan for release at the time of this writing), this was switched to the enumerated strings listed here. Prior to version 5 of Traffic Ops API, this was a boolean having only the states “true” and “false”. “True” was identical to today’s “ACTIVE”, while “false” was identical to “PRIMED”. “INACTIVE” has no legacy analogue. Thus when requesting older API versions, an “active state” of “false” may actually be either INACTIVE or PRIMED, and there is no way to tell which.

Anonymous Blocking

Enables/Disables blocking of anonymized IP address - proxies, TOR exit nodes, etc - for this Delivery Service. Set to true to enable blocking of anonymous IPs for this Delivery Service.

Table 17 Aliases

Name	Use(s)	Type(s)
anonymousBlockingEnabled	Traffic Ops client and server Go code, Traffic Ops API requests and responses	usually unchanged (boolean), but sometimes as a string containing a boolean e.g. in the response of a GET request to cdns/{{name}}/snapshot

Note

Anonymous Blocking requires an anonymous IP address database from the Delivery Service’s Geolocation Provider. E.g. MaxMind’s Anonymous IP Database when MaxMind is used as the Geolocation Provider.

See also

The Configure Anonymous Blocking “Quick-How-To” guide.

Cache URL Expression

Deprecated since version 3.0: This feature is no longer supported by ATS and consequently it will be removed from Traffic Control in the future. Current plans are to remove after ATC 5.X is no longer supported.

Manipulates the cache key of the incoming requests. Normally, the cache key is the Origin domain. This can be changed so that multiple services can share a cache key, can also be used to preserve cached content if service origin is changed.

Warning

This field provides access to a feature that was only present in ATS 6.X and earlier. As cache servers must now use ATS 7.1.X, this field must be blank unless all cache servers can be guaranteed to use that older ATS version (NOT recommended).

CDN

A CDN to which this Delivery Service belongs. Only cache servers within this CDN are available to route content for this Delivery Service. Additionally, only Traffic Routers assigned to this CDN will perform said routing. Most often cdn/CDN refers to the name of the CDN to which the Delivery Service belongs, but occasionally (most notably in the payloads and/or query parameters of certain Traffic Ops API endpoints) it actually refers to the integral, unique identifier of said CDN.

Check Path

A request path on the origin server which is used to by certain Traffic Ops Extensions to indicate the “health” of the Origin.

Consistent Hashing Regular Expression

When Traffic Router performs Consistent Hashing on a client request to find an Edge-tier cache server to which to redirect them, it can optionally first modify the request path by extracting the pieces that match this regular expression.

See also

Consistent Hashing Patterns

Table 18 Aliases

Name	Use(s)	Type(s)
consistentHashRegex	In source code and Traffic Ops API requests and responses	unchanged (regular expression)
pattern-based consistent hashing	documentation and the Traffic Portal UI	unchanged (regular expression), but usually used when discussing the concept rather than the field

Consistent Hashing Query Parameters

When Traffic Router performs Consistent Hashing on a client request to find an Edge-tier cache server to which to redirect them, it can optionally take into account any number of query parameters. This field defines them, formally as a Set but often represented as an Array/List due to encoding limitations. That is, if the Consistent Hashing Query Parameters on a Delivery Service are {test} and a client makes a request for /?test=something they will be directed to a different cache server than a different client that requests /?test=somethingElse, but the same cache server as a client that requests /?test=something&quest=somethingToo.

Table 19 Aliases

Name	Use(s)	Type(s)
consistentHashQueryParams	In source code, Traffic Portal, and Traffic Ops API requests and responses	unchanged (Array of strings - should ALWAYS be unique, thus treated as a Set in most contexts)

Deep Caching

Controls the Deep Caching feature of Traffic Router when serving content for this Delivery Service. This should always be represented by one of two values:

ALWAYS

This Delivery Service will always use Deep Caching

NEVER

This Delivery Service will never use Deep Caching

Implementation Detail

Traffic Ops and Traffic Ops client Go code use an empty string as the name of the enumeration member that represents “NEVER”.

Display Name

The “name” of the Delivery Service. Since nearly any use of a string-based identification method for Delivery Services (e.g. in Traffic Portal tables) uses xml_id, this is of limited use. For that reason and for consistency’s sake it is suggested that this be the same as the xml_id. However, unlike the xml_id, this can contain any UTF-8 characters without restriction.

DNS Bypass CNAME

When the limits placed on this Delivery Service by the Global Max Mbps and/or Global Max Tps are exceeded, a DNS-Routed Delivery Service will direct excess traffic to the host referred to by this CNAME record.

Note

IPv6 traffic will be redirected if and only if IPv6 Routing Enabled is “true” for this Delivery Service.

DNS Bypass IP

When the limits placed on this Delivery Service by the Global Max Mbps and/or Global Max Tps are exceeded, a DNS-Routed Delivery Service will direct excess IPv4 traffic to this IPv4 address.

DNS Bypass IPv6

When the limits placed on this Delivery Service by the Global Max Mbps and/or Global Max Tps are exceeded, a DNS-Routed Delivery Service will direct excess IPv6 traffic to this IPv6 address.

Note

This requires an accompanying configuration of IPv6 Routing Enabled such that IPv6 traffic is allowed at all.

DNS Bypass TTL

When the limits placed on this Delivery Service by the Global Max Mbps and/or Global Max Tps are exceeded, a DNS-Routed Delivery Service will direct excess traffic to their DNS Bypass IP, DNS Bypass IPv6, or DNS Bypass CNAME.

DNS TTL

The TTL on the DNS record for the Traffic Router A and AAAA records. DNS-Routed Delivery Services will send this TTL along with their record responses to clients requesting access to this Delivery Service. Setting too high or too low will result in poor caching performance.

Table 20 Aliases

Name	Use(s)	Type(s)
CCR DNS TTL	In Delivery Service objects returned by the Traffic Ops API	unchanged (int, integer etc.)
CCR TTL	Legacy Traffic Ops UI, documentation for older Traffic Control versions	unchanged (int, integer etc.)
ttl	In CDN Snapshot structures, where it is displayed on a per-record-type-basis	map of record type names to integral values

DSCP

The DSCP which will be used to mark IP packets as they are sent out of the CDN to the client.

See also

The Differentiated Services Wikipedia article.

Warning

The DSCP setting in Traffic Portal is only for setting traffic towards the client, and gets applied after the initial TCP handshake is complete and the HTTP request has been received. Before that the cache can’t determine what Delivery Service is being requested, and consequently can’t know what DSCP to apply. Therefore, the DSCP feature can not be used for security settings; the IP packets that form the TCP handshake are not going to be DSCP-marked.

Implementation Detail

DSCP settings only apply on cache servers that run Apache Traffic Server. The implementation uses the ATS Header Rewrite Plugin to create a rule that will mark traffic bound outward from the CDN to the client.

Edge Header Rewrite Rules

This field in general contains the contents of the a configuration file used by the ATS Header Rewrite Plugin when serving content for this Delivery Service - on Edge-tier cache servers.

Tip

Because this ultimately is the contents of an ATS configuration file, it can make use of the Strings with Special Meaning to t3c.

Note

This field cannot be used if the Delivery Service is assigned to a Topology.

EDNS0 Client Subnet Enabled

A boolean value that controls whether or not EDNS0 client subnet is enabled on this Delivery Service by Traffic Router. When creating a Delivery Service in Traffic Portal, this will default to “false”.

Example URLs

The Example URLs of a Delivery Service are the scheme/host specifications that clients can use to request content through it. These are determined by Traffic Ops from the Delivery Service’s configuration, and are read-only in virtually every context. The only reason a Delivery Service should ever have no Example URLs is if it is an ANY_MAP-Type Delivery Service (since they are not routed). For example, a Delivery Service that can deliver HTTP and HTTPS content, has a Routing Name of “cdn”, an xml_id of “demo1”, and belonging to a CDN that is authoritative for the mycdn.ciab.test domain would have two Example URLs:

• https://cdn.demo1.mycdn.ciab.test

• http://cdn.demo1.mycdn.ciab.test

Note that these are irrespective of request path; meaning a client can request e.g. https://cdn.demo1.mycdn.ciab.test/index.html through this Delivery Service.

Warning

This list does not consider any Static DNS Entries configured on the Delivery Service, those are

Table 21 Aliases

Name	Use(s)	Type(s)
Delivery Service URLs	Traffic Portal forms	unchanged (list of strings)

Fair-Queuing Pacing Rate Bps

The maximum bytes per second a cache server will deliver on any single TCP connection. This uses the Linux kernel’s Fair-Queuing setsockopt(2) (SO_MAX_PACING_RATE) to limit the rate of delivery. Traffic exceeding this speed will only be rate-limited and not diverted. This option requires extra configuration on all cache servers assigned to this Delivery Service - specifically, the line net.core.default_qdisc = fq must exist in /etc/sysctl.conf.

See also

tc-fq_codel(8)

See also

This is implemented using the ATS fq_pacing plign.

Table 22 Aliases

Name	Use(s)	Type(s)
FQPacingRate	Traffic Ops source code, Delivery Service objects returned by the Traffic Ops API	unchanged (int, integer etc.)

First Header Rewrite Rules

This field in general contains the contents of the a configuration file used by the ATS Header Rewrite Plugin when serving content for this Delivery Service - on First-tier cache servers.

Tip

Because this ultimately is the contents of an ATS configuration file, it can make use of the Strings with Special Meaning to t3c.

Note

This field can only be used if the Delivery Service is assigned to a Topology.

Geo Limit

Limits access to a Delivery Service by geographic location. The only practical difference between this and Regional Geoblocking is the configuration method; as opposed to Regional Geoblocking, GeoLimit configuration is handled by country-wide codes and the Coverage Zone File. When a client is denied access to a requested resource on an HTTP-Routed Delivery Service, they will receive a 503 Service Unavailable instead of the usual 302 Found response - unless Geo Limit Redirect URL is defined, in which case a 302 Found response pointing to that URL will be returned by Traffic Router. If the Delivery Service is a DNS-Routed Delivery Service, the IP address of the resolver for the client DNS request is what is checked. If the IP address of this resolver is found to be in a restricted location, the Traffic Router will respond with an NXDOMAIN response, causing the name resolution to fail. This is nearly always an integral, unique identifier for a behavior set to be followed by Traffic Router. The defined values are:

0

Geographic access limiting is not enabled, and content served by this Delivery Service will be accessible regardless of the clients geographic location. (Aliased as “0 - None” in Traffic Portal forms)

1

A client will be allowed to request content if and only if their IP address is found by Traffic Router within the Coverage Zone File. Otherwise, access will be denied. (Aliased as “1 - CZF Only” in Traffic Portal forms)

2

A client will be allowed to request content if their IP address is found by Traffic Router within the Coverage Zone File, or if looking up the client’s IP address in the Geographic IP mapping database provided by Geolocation Provider indicates the client resides in a country that is found in the Geo Limit Countries array. (Aliased as “2 - CZF + Country Code(s)” in Traffic Portal forms - formerly was known as “CZF + US” when only the US country code was supported)

Warning

The definitions of each integral, unique identifier are hidden in implementations in each ATC component. Different components will handle invalid values differently, and there’s no actual enforcement that the stored integral, unique identifier actually be within the representable range.

Table 23 Aliases

Name	Use(s)	Type(s)
coverageZoneOnly	In CDN Snapshot structures, especially in Traffic Ops API responses	A boolean which, if true, tells Traffic Router to only service requests when the client IP address is found in the Coverage Zone File

Danger

Geographic access limiting is not sufficient to guarantee access is properly restricted. The limiting is implemented by Traffic Router, which means that direct requests to Edge-tier cache servers will bypass it entirely.

Geo Limit Countries

When Geo Limit is being used with this Delivery Service (and is set to exactly 2), this is optionally a list of country codes to which access to content provided by the Delivery Service will be restricted. Normally, this is an array of strings representing country codes, but in legacy versions of the Traffic Ops API it was a comma-delimited string of said country codes rather than a real array. When creating or modifying this field of a Delivery Service in said legacy API versions, any amount of whitespace between country codes is permissible, as it will be removed on submission, but responses from the Traffic Ops API should never include such whitespace.

Table 24 Aliases

Name	Use(s)	Type(s)
geoEnabled	In CDN Snapshot structures, especially in Traffic Ops API responses	An array of objects each having the key “countryCode” that is a string containing an allowed country code - one should exist for each allowed country code

Geo Limit Redirect URL

If Geo Limit is being used with this Delivery Service, this is optionally a URL to which clients will be redirected when Traffic Router determines that they are not in a geographic zone that permits their access to the Delivery Service content. This changes the response from Traffic Router from 503 Service Unavailable to 302 Found with a provided location that will be this URL. There is no restriction on the provided URL; it may even be the path to a resource served by this Delivery Service. In fact, this field need not even be a full URL, it can be a relative path. Both of these cases are handled specially by Traffic Router.

• If the provided URL is a resource served by the Delivery Service (e.g. if the client requests http://cdn.dsXMLID.somedomain.example.com/index.html but are denied access by Geo Limit and the Geo Limit Redirect URL is something like http://cdn.dsXMLID.somedomain.example.com/help.php), Traffic Router will find an appropriate Edge-tier cache server and redirect the client, ignoring Geo Limit restrictions for this request only.

• If the provided “URL” is actually a relative path, it will be considered relative to the requested Delivery Service FQDN. This means that e.g. if the client requests http://cdn.dsXMLID.somedomain.example.com/index.html but are denied access by Geo Limit and the Geo Limit Redirect URL is something like /help.php, Traffic Router will find an appropriate Edge-tier cache server and redirect the client to it as though they had requested http://cdn.dsXMLID.somedomain.example.com/help.php, ignoring Geo Limit restrictions for this request only.

Table 25 Aliases

Name	Use(s)	Type(s)
NGB	Older documentation, in Traffic Router comments and error logs	unchanged (string, String etc.)
geoRedirectURLType	Internally in Traffic Router	A String that describes whether or not the actual Geo Limit Redirect URL is relative to the Delivery Service base FQDN. Should be one of: INVALID_URL The Geo Limit Redirect URL has not yet been parsed, or an error occurred during parsing DS_URL The Geo Limit Redirect URL is served by this Delivery Service NOT_DS_URL The Geo Limit Redirect URL is external to this Delivery Service

Note

The use of a redirect URL relies on the ability of Traffic Router to redirect the client using HTTP 302 Found responses. As such, this field has no effect on DNS-Routed Delivery Services.

Geolocation Provider

This is nearly always the integral, unique identifier of a provider for a database that maps IP addresses to geographic locations. Less frequently, this may be accompanied by the actual name of the provider. Only two values are possible at the time of this writing:

0: MaxMind

IP address to geographic location mapping will be provided by a MaxMind GeoIP2 database.

1: Neustar

IP address to geographic location mapping will be provided by a Neustar GeoPoint IP address database.

Warning

It’s not clear whether Neustar databases are actually supported; this is an old option and compatibility may have been broken over time.

Table 26 Aliases

Name	Use(s)	Type(s)
geoProvider	Traffic Ops and Traffic Ops client code, Traffic Ops API requests and responses	unchanged (integral, unique identifier)

Geo Miss Default Latitude

Default Latitude for this Delivery Service. When the geographic location of the client cannot be determined, they will be routed as if they were at this latitude.

Table 27 Aliases

Name	Use(s)	Type(s)
missLat	In Traffic Ops API responses and Traffic Ops source code	unchanged (numeric)

Geo Miss Default Longitude

Default Longitude for this Delivery Service. When the geographic location of the client cannot be determined, they will be routed as if they were at this longitude.

Table 28 Aliases

Name	Use(s)	Type(s)
missLong	In Traffic Ops API responses and Traffic Ops source code	unchanged (numeric)

Global Max Mbps

The maximum Mbps this Delivery Service can serve across all Edge-tier cache servers before traffic will be diverted to the bypass destination. For a DNS-Routed Delivery Service, the DNS Bypass IP or DNS Bypass IPv6 will be used (depending on whether this was a A or AAAA request), and for HTTP-Routed Delivery Services the HTTP Bypass FQDN will be used.

Table 29 Aliases

Name	Use(s)	Type(s)
totalKbpsThreshold	In Traffic Ops API responses - most notably cdns/{{name}}/configs/monitoring	unchanged (numeric), but converted from Mbps to Kbps

Global Max TPS

The maximum TPS this Delivery Service can serve across all Edge-tier cache servers before traffic will be diverted to the bypass destination. For a DNS-Routed Delivery Service, the DNS Bypass IP or DNS Bypass IPv6 will be used (depending on whether this was a A or AAAA request), and for HTTP-Routed Delivery Services the HTTP Bypass FQDN will be used.

Table 30 Aliases

Name	Use(s)	Type(s)
totalTpsThreshold	In Traffic Ops API responses - most notably cdns/{{name}}/configs/monitoring	unchanged (numeric)

HTTP Bypass FQDN

When the limits placed on this Delivery Service by the Global Max Mbps and/or Global Max Tps are exceeded, an HTTP-Routed Delivery Service will direct excess traffic to this Fully Qualified Domain Name.

IPv6 Routing Enabled

A boolean value that controls whether or not clients using IPv6 can be routed to this Delivery Service by Traffic Router. When creating a Delivery Service in Traffic Portal, this will default to “true”.

Info URL

This should be a URL (though neither the Traffic Ops API nor the Traffic Ops Database in any way enforce the validity of said URL) to which administrators or others may refer for further information regarding a Delivery Service - e.g. a related JIRA ticket.

Initial Dispersion

The number of Edge-tier cache servers across which a particular asset will be distributed within each Cache Group. For most use-cases, this should be 1, meaning that all clients requesting a particular asset will be directed to 1 cache server per Cache Group. Depending on the popularity and size of assets, consider increasing this number in order to spread the request load across more than 1 cache server. The larger this number, the more copies of a particular asset are stored in a Cache Group, which can “pollute” caches (if load distribution is unnecessary) and decreases caching efficiency (due to cache misses if the asset is not requested enough to stay “fresh” in all the caches).

Inner Header Rewrite Rules

This field in general contains the contents of the a configuration file used by the ATS Header Rewrite Plugin when serving content for this Delivery Service - on Inner-tier cache servers.

Tip

Because this ultimately is the contents of an ATS configuration file, it can make use of the Strings with Special Meaning to t3c.

Note

This field can only be used if the Delivery Service is assigned to a Topology.

Last Header Rewrite Rules

This field in general contains the contents of the a configuration file used by the ATS Header Rewrite Plugin when serving content for this Delivery Service - on Last-tier cache servers.

Tip

Because this ultimately is the contents of an ATS configuration file, it can make use of the Strings with Special Meaning to t3c.

Note

This field can only be used if the Delivery Service is assigned to a Topology.

Logs Enabled

A boolean switch that can be toggled to enable/disable logging for a Delivery Service.

Note

This doesn’t actually do anything. It was part of the functionality for a planned Traffic Control component named “Traffic Logs” - which was never created.

Long Description

Free text field that has no strictly defined purpose, but it is suggested that it contain a short description of the Delivery Service and its purpose.

Name	Use(s)	Type(s)
longDesc	Traffic Control source code and Traffic Ops API responses	unchanged (string, String etc.)

Match List

A Match List is a set of regular expressions used by Traffic Router to determine whether a given request from a client should be served by this Delivery Service. Under normal circumstances this field should only ever be read-only as its contents should be generated by Traffic Ops based on the Delivery Service’s configuration. These regular expressions can each be one of the following types:

HEADER_REGEXP

This Delivery Service will be used if an HTTP Header/Value pair can be found in the clients request matching this regular expression.[3]

HOST_REGEXP

This Delivery Service will be used if the requested host matches this regular expression. The host can be found using the Host HTTP Header, or as the requested name in a DNS request, depending on the Type of the Delivery Service.

PATH_REGEXP

This Delivery Service will be used if the request path matches this regular expression.[3]

STEERING_REGEXP

This Delivery Service will be used if this regular expression matches the xml_id of one of this Delivery Service’s “targets”

Note

This regular expression type can only exist in the Match List of STEERING-Type Delivery Services - and not CLIENT_STEERING.

Table 31 Aliases

Name	Use(s)	Type(s)
deliveryservice_regex	Traffic Ops database	unique, integral identifier for a regular expression

Max DNS Answers

DNS-routed Delivery Service

The maximum number of Edge-tier cache server IP addresses that the Traffic Router will include in responses to DNS requests. When provided, the cache server IP addresses included are rotated in each response to spread traffic evenly. This number should scale according to the amount of traffic the Delivery Service is expected to serve.

HTTP-routed Delivery Service

If the Traffic Router profile parameter “edge.http.limit” is set, setting this to a non-zero value will override that parameter for this delivery service, limiting the number of Traffic Router IP addresses (A records) that are included in responses to DNS requests for this delivery service.

Max Origin Connections

The maximum number of TCP connections individual Mid-tier cache servers are allowed to make to the Origin Server Base URL. A value of 0 in this field indicates that there is no maximum.

Note

Max Origin Connections can be made per-Cache Group by setting the Regional field.

Max Request Header Bytes

The maximum size(in bytes) of the request header that is allowed for this Delivery Service.

Mid Header Rewrite Rules

This field in general contains the contents of the a configuration file used by the ATS Header Rewrite Plugin when serving content for this Delivery Service - on Mid-tier cache servers.

Tip

Because this ultimately is the contents of an ATS configuration file, it can make use of the Strings with Special Meaning to t3c.

Note

This field cannot be used if the Delivery Service is assigned to a Topology.

Origin Server Base URL

The Origin Server’s base URL which includes the protocol (http or https). Example: http://movies.origin.com. Must not include paths, query parameters, document fragment identifiers, or username/password URL fields.

Table 32 Aliases

Name	Use(s)	Type(s)
orgServerFqdn	Traffic Ops API responses and in Traffic Control source code	unchanged (usually str, string etc.)

Origin Shield

An experimental feature that allows administrators to list additional forward proxies that sit between the Mid-tier and the Origin. In most scenarios, this is represented (and required to be input) as a pipe (|)-delimited string.

Profile

Either the Name of a Profile used by this Delivery Service, or the ID of said Profile.

Table 33 Aliases

Name	Use(s)	Type(s)
profileId	In Traffic Control source code and some Traffic Ops API responses dealing with Delivery Services	Unlike the more general “Profile”, this is always an integral, unique identifier
profileName	In Traffic Control source code and some Traffic Ops API responses dealing with Delivery Services	Unlike the more general “Profile”, this is always a name (str, string, etc.)

Protocol

The protocol with which to serve content from this Delivery Service. This defines the way the Delivery Service will handle client requests that are either HTTP or HTTPS, which is distinct from what protocols are used to direct traffic. For example, this can be used to direct clients to only request content using HTTP, or to allow clients to use either HTTP or HTTPS, etc. Normally, this will be the name of the protocol handling, but occasionally this will appear as the integral, unique identifier of the protocol handling instead. The integral, unique identifiers and their associated names and meanings are:

0: HTTP

This Delivery Service will only accept unsecured HTTP requests. Requests made with HTTPS will fail.

1: HTTPS

This Delivery Service will only accept secured HTTPS requests. Requests made with HTTP will fail.

2: HTTP AND HTTPS

This Delivery Service will accept both unsecured HTTP requests and secured HTTPS requests.

3: HTTP TO HTTPS

When this Delivery Service is using HTTP Content Routing unsecured HTTP requests will be met with a response that indicates to the client that further requests must use HTTPS.

Note

If any other type of Content Routing is used, this functionality cannot be used. In those cases, a protocol setting of 3/”HTTP TO HTTPS” will result in the same behavior as 1/”HTTPS”. This behavior is tracked by GitHub Issue #3221

Warning

The definitions of each integral, unique identifier are hidden in implementations in each ATC component. Different components will handle invalid values differently, and there’s no actual enforcement that the stored integral, unique identifier actually be within the representable range.

Table 34 Aliases

Name	Use(s)	Type(s)
Protocol	CDN Snapshots | An object containing the key "acceptHttps" that is a string containing a boolean that expresses whether Traffic Router should accept HTTPS requests for this Delivery Service, and the key "redirectToHttps" that is also a string containing a boolean which expresses whether or not Traffic Router should redirect HTTP requests to HTTPS URLs. Optionally, the key "acceptHttp" may also appear, once again a string containing a boolean that expresses whether or not Traffic Router should accept unsecured HTTP requests - this is implicitly treated as "true" by Traffic Router when it is not present.

Query String Handling

Describes how query strings should be handled by the Edge-tier cache servers when serving content for this Delivery Service. This is nearly always expressed as an integral, unique identifier for each behavior, though in Traffic Portal a more descriptive value is typically used, or at least provided in addition to the integral, unique identifier. The allowed values and their meanings are:

0

For the purposes of caching, Edge-tier cache servers will consider URLs unique if and only if they are unique up to and including any and all query parameters. They will also pass the query parameters in their own requests to Mid-tier cache servers (which in turn will exhibit the same caching behavior and pass the query parameters in requests to the Origin). (Aliased as “USE” in Traffic Portal tables, and “0 - use qstring in cache key, and pass up” in Traffic Portal forms)

1

For the purposes of caching, neither Edge-tier nor Mid-tier cache servers will consider the query parameter string when determining if a URL is stored in cache. However, the query string will still be passed in upstream requests to Mid-tier cache servers and in turn the Origin. (Aliased as “IGNORE” in Traffic Portal tables and “1 - ignore in cache key, and pass up” in Traffic Portal forms)

2

The query parameter string will be stripped from URLs immediately when the request is received by an Edge-tier cache server. This means it is never considered for the purposes of caching unique URLs and will not be passed in upstream requests. (Aliased as “DROP” in Traffic Portal tables and “2 - drop at edge” in Traffic Portal forms)

Warning

The implementation of dropping query parameter strings at the Edge-tier uses a Regex Remap Expression and thus Delivery Services with this type of query string handling cannot make use of Regex Remap Expressions.

Table 35 Aliases

Name	Use(s)	Type(s)
Qstring Handling	Traffic Portal tables	One of the Traffic Portal value aliases “USE” (0), “IGNORE” (1), “DROP” (2)
qstringIgnore	Traffic Ops code, Traffic Ops API requests/responses	unchanged (integral, unique identifier)

The Delivery Service’s Query String Handling can be set directly as a field on the Delivery Service object itself, or it can be overridden by a Parameter on a Profile used by this Delivery Service. The special Parameter named psel.qstring_handling and configuration file parent.config will have it’s contents directly inserted into the parent.config file on all cache servers assigned to this Delivery Service.

Danger

Using the psel.qstring_handling Parameter is strongly discouraged for several reasons. Firstly, at a Delivery Service level it will NOT change the configuration of that Delivery Service’s own Query String Handling - which will cause it to appear in Traffic Portal and in Traffic Ops API responses as though it were configured one way while actually behaving a different way altogether. Also, no validation is performed on the value given to it. Because it’s inserted verbatim into the qstring field of a line in ATS parent.config configuration file, a typo or an ignorant user can easily cause ATS instances on all cache servers assigned to that Delivery Service to fail to reload their configuration, possibly grinding entire CDNs to a halt.

See also

When implemented as a Parameter (psel.qstring_handling), its value must be a valid value for the qstring field of a line in the ATS parent.config configuration file. For a description of valid values, see the documentation for parent.config

Range Request Handling

Describes how HTTP “Range Requests” should be handled by the Delivery Service at the Edge-tier. This is nearly always an integral, unique identifier for the behavior set required of the Edge-tier cache servers. The valid values and their respective meanings are:

0

Do not cache Range Requests at all. (Aliased as “0 - Don’t cache” in Traffic Portal forms)

Note

This is not retroactive - when modifying an existing Delivery Services to have this value for “Range Request Handling”, ranges requested from files that are already cached due to a non-range request will be served out of cache for as long as the Cache-Control headers allow.

1

Use the background_fetch plugin to service the range request while caching the whole object. (Aliased as “1 - Use background_fetch plugin” in Traffic Portal forms)

2

Use the cache_range_requests plugin to cache ranges as unique objects. (Aliased as “2 - Use cache_range_requests plugin” in Traffic Portal forms)

3

Use the slice plugin to slice range based requests into deterministic chunks. (Aliased as “3 - Use slice plugin” in Traffic Portal forms)

Note

The -–consider-ims parameter will automatically be added to the remap line by t3c for self healing. If any other range request parameters are being used you must also include --consider-ims to enable self healing. Automatic self healing can be disabled by adding a remap.config parameter with a value of no_self_healing

New in version ATCv4.1.

Note

Range Request Handling can only be implemented on cache servers using ATS because of its dependence on ATS plugins. The value may be set on any Delivery Service, but will have no effect when the cache servers that ultimately end up serving the content are e.g. Grove, Nginx, etc.

Warning

The definitions of each integral, unique identifier are hidden in implementations in each ATC component. Different components will handle invalid values differently, and there’s no actual enforcement that the stored integral, unique identifier actually be within the representable range.

Range Slice Request Block Size

The block size in bytes that is used for slice plugin.

This can only and must be set if the Range Request Handling is set to 3.

Raw Remap Text

For HTTP and DNS-Routed Delivery Services, this will be added to the end of a line in the remap.config ATS configuration file line on the cache verbatim. For ANY_MAP-Type Delivery Services this must be defined.

Tip

Because this ultimately is a raw line of content in a configuration file, it can make use of the Strings with Special Meaning to t3c. Of particular note is the Remap Override template string.

Note

This field must be defined on ANY_MAP-Type Delivery Services, but is otherwise optional.

See also

The Apache Trafficserver documentation for the Regex Remap plugin

Table 36 Aliases

Name	Use(s)	Type(s)
remapText	In Traffic Ops source code and Traffic Ops API requests/responses	unchanged (text, string etc.)

Directives “””

The Raw Remap text is ordinarily added at the end of the line, after everything else. However, it may be necessary to change the normal arg ordering, especially if the user needs to modify the cachekey, range headers or URI in a way that may change cachekey or regex_remap behaviors.

It may be necessary to add Range Request Handling after the Raw Remap. For example, if you have a plugin which manipulates the Range header. In this case, you can insert the text __RANGE_DIRECTIVE__ in the Raw Remap text, and the range request handling directives will be added at that point.

For example, if you have an Apache Traffic Server lua plugin which manipulates the range, and are using Slice Range Request Handling which needs to run after your plugin, you can set a Raw Remap, @plugin=tslua.so @pparam=range.lua __RANGE_DIRECTIVE__, and the @plugin=slice.so range directive will be inserted after your plugin.

Another example might be a Delivery Service which modifies the uri in a way that changes the cachey key (cachekey), and affects parent routing (regex_remap) with the possibility of range request handling via background fetch. Raw Remap Text might then look like: @plugin=tslua.so @pparam=uri-manip.lua __CACHEKEY_DIRECTIVE__ __REGEX_REMAP_DIRECTIVE__ __RANGE_DIRECTIVE__. This would set things up such that background_fetch would issue a request to the proper remap parent.

Table 37 Supported Raw Remap Directives

Name	Use(s)
__CACHEKEY_DIRECTIVE__ __RANGE_DIRECTIVE__ __REGEX_REMAP_DIRECTIVE__	Inserts cachekey plugin and args (if any) Inserts range directive args (if any) Inserts regex_remap directive (if any)

Regex Remap Expression

Allows remapping of incoming requests URL using regular expressions to search and replace text. In a more literal sense, this is the raw contents of a configuration file used by the ATS regex_remap plugin. At its most basic, the contents of this field should consist of map followed by a regular expression and then a “template URL” - all space-separated. The regular expression matches a client’s request path (i.e. not a full URL - /path/to/content not https://origin.example.com/path/to/content) and when such a match occurs, the request is transformed into a request for the template URL. The most basic usage of the template URL is to use $1-$9 to insert the corresponding regular expression capture group. For example, a regular expression of ^/a/(.*) and a template URL of https://origin.example.com/b/$1 maps requests for Origin content under path /a/ to the same sub-paths under path b. Note that since it’s a full URL, this mapping can be made to another server entirely.

See also

The documentation for the regex_remap plugin for ATS

Caution

This field is not validated by Traffic Ops to be correct syntactically, and can cause Traffic Server to not start if invalid. Please use with caution.

Warning

Regex remap expressions are incompatible with Query String Handling being set to 2. The behavior of a cache server under that configuration is undefined.

Tip

It is, of course, entirely possible to write a Regex Remap Expression that reproduces the desired Query String Handling as well as any other desired behavior.

See also

The Apache Trafficserver documentation for the Regex Remap plugin

Table 38 Aliases

Name	Use(s)	Type(s)
regexRemap	Traffic Ops source code and database, and Traffic Ops API requests/responses	unchanged (string etc.)

Regional

A boolean value. If a Delivery Service is Regional (true), then Max Origin Connections is per Cache Group, rather than divided over all Cache Servers in child Cache Groups of the Origin (false, the default).

Regional Geoblocking

A boolean value that defines whether or not Regional Geoblocking is active on this Delivery Service. The actual configuration of Regional Geoblocking is done in the Profile used by the Traffic Router serving the Delivery Service. Rules for this Delivery Service may exist, but they will not actually be used unless this field is true.

Tip

Regional Geoblocking is configured primarily with respect to Canadian postal codes, so unless specifically Canadian regions should be allowed/disallowed to access content, Geo Limit is probably a better setting for controlling access to content according to geographic location.

Required Capabilities

New in version ATCv4.

A Delivery Service can be associated with Server Capabilities that it requires cache servers serving its content to have. When one or more Server Capability is required by a Delivery Service, it will block the assignment of cache servers to it that do not have those Server Capabilities. Additionally, the Edge-tier cache servers assigned to a Delivery Service that requires a Server Capability will only request content they do not have cached from Mid-tier cache servers which also have this Server Capability.

Typically, a required Server Capability is represented merely by the name of said Server Capability. In fact, there’s nothing more to a Server Capability than its name; it’s the responsibility of CDN operators to ensure that they are assigned and required properly. There is no mechanism to detect whether or not a cache server has a given Server Capability, it must be assigned manually.

Routing Name

A DNS label in the Delivery Service’s domain that forms the FQDN that is used by clients to request content. All together, the constructed FQDN looks like: Delivery Service Routing Name.Delivery Service xml_id.CDN Subdomain.CDN Domain.Top-Level Domain[1].

Servers

Servers can be assigned to Delivery Services using the Servers and Delivery Services Traffic Portal sections, or by directly using the deliveryserviceserver endpoint. Only Edge-tier cache servers can be assigned to a Delivery Service, and once they are so assigned they will begin to serve content for the Delivery Service (after updates are queued and then applied). Any servers assigned to a Delivery Service must also belong to the same CDN as the Delivery Service itself. At least one server must be assigned to a Delivery Service in order for it to serve any content.

Service Category

A service category is a tag that describes the type of content being delivered by the Delivery Service. Some example values are: “Linear” and “VOD”

Signing Algorithm

URLs/URIs may be signed using one of two algorithms before a request for the content to which they refer is sent to the Origin (which in practice can be any upstream network). At the time of this writing, this field is restricted within the Traffic Ops Database to one of two values (or NULL/”None”, to indicate no signing should be done).

See also

The url_sig README.

See also

The draft RFC for uri_signing - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, NOT the latest.

url_sig

URL signing will be implemented in this Delivery Service using the url_sig Apache Traffic Server plugin. (Aliased as “URL Signature Keys” in Traffic Portal forms)

uri_signing

URL signing will be implemented in this Delivery Service using an algorithm based on a work-in-progress RFC specification draft. (Aliased as “URI Signing Keys” in Traffic Portal forms)

Table 39 Aliases

Name	Use(s)	Type(s)
Signed	In all components prior to Traffic Control v2.2. Some endpoints in early versions of the Traffic Ops API will still return this field instead of “signingAlgorithm”.	A boolean value where true was the same as “url_sig” in current versions, and false indicated URL signing would not be done for the Delivery Service.

Keys for either algorithm can be generated within Traffic Portal.

SSL Key Version

An integer that describes the version of the SSL key(s) - if any - used by this Delivery Service. This is incremented whenever Traffic Portal generates new SSL keys for the Delivery Service.

Warning

This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!

Static DNS Entries

Static DNS Entries can be added under a Delivery Service’s domain. These DNS records can be configured in the Delivery Services section of Traffic Portal, and can be any valid CNAME, A or AAAA DNS record - provided the associated hostname falls within the DNS domain for the Delivery Service. For example, a Delivery Service with xml_id “demo1” and belonging to a CDN with domain “mycdn.ciab.test” could have Static DNS Entries for hostnames “foo.demo1.mycdn.ciab.test” or “foo.bar.demo1.mycdn.ciab.test” but not “foo.bar.mycdn.ciab.test” or “foo.bar.test”.

Note

The Routing Name of a Delivery Service is not part of the SOA record for the Delivery Service’s domain, and so there is no need to place Static DNS Entries below a domain containing it.

Tenant

The Tenant who owns this Delivery Service. They (and their parents, if any) are the only ones allowed to make changes to this Delivery Service. Typically, tenant/Tenant refers to the name of the owning Tenant, but occasionally (most notably in the payloads and/or query parameters of certain Traffic Ops API requests) it actually refers to the integral, unique identifier of said Tenant.

Table 40 Aliases

Name	Use(s)	Type(s)
TenantID	Go code and Traffic Ops API requests/responses	Integral, unique identifier (bigint, int etc.)

TLS Versions

The versions of TLS that can be used in HTTP requests to Edge-tier cache servers for this Delivery Service’s content can be limited using this property. When a Delivery Service has this property set to anything other than a null value, it lists the versions that will be allowed. Any versions can be added to the supported set, so long as they are of the form Major.Minor, e.g. 1.1 or 42.0. When this is a null value, no restrictions are placed on the TLS versions that may be used for retrieving Delivery Service content.

Implementation Detail

Traffic Ops will accept empty arrays as a synonym for null in requests, but will always represent them as null in responses. Note that this means it’s impossible to create a Delivery Service that explicitly supports no TLS versions - the proper way to disable HTTPS for a Delivery Service is to set its Protocol accordingly.

A Delivery Service that has a Type of STEERING or CLIENT_STEERING may not legally be set to have a TLS Versions property that is non-null.

Warning

Using this setting may cause old clients that only support archaic TLS versions to break suddenly. Be sure that the security increase is worth this risk.

Topology

A structure composed of Cache Groups and parent relationships, which is assignable to one or more Delivery Services.

Traffic Router Additional Response Headers

List of HTTP header {{name}}:{{value}} pairs separated by __RETURN__ or simply on separate lines. Listed pairs will be included in all HTTP responses from Traffic Router for HTTP-Routed Delivery Services.

Deprecated since version 4.0: The use of __RETURN__ as a substitute for a real newline is unnecessary and the ability to do so will be removed in the future.

Table 41 Aliases

Name	Use(s)	Type(s)
trResponseHeaders	Traffic Control source code and Delivery Service objects returned by the Traffic Ops API	unchanged (string etc.)

Traffic Router Log Request Headers

List of HTTP header names separated by __RETURN__ or simply on separate lines. Listed pairs will be logged for all HTTP requests to Traffic Router for HTTP-Routed Delivery Services.

Deprecated since version 4.0: The use of __RETURN__ as a substitute for a real newline is unnecessary and the ability to do so will be removed in the future.

Table 42 Aliases

Name	Use(s)	Type(s)
trRequestHeaders	Traffic Control source code and Delivery Service objects returned by the Traffic Ops API	unchanged (string etc.)

Type

Defines the content routing method used by the Delivery Service. In most cases this is an integral, unique identifier that corresponds to an enumeration of the Delivery Service Types. In other cases, this the actual name of said type.

The “Type” of a Delivery Service can mean several things. First, it can be used to refer to the “routing type” of Delivery Service. This is one of:

Tip

The only way to get the integral, unique identifier of a Type of Delivery Service is to look at the database after it has been generated; these are non-deterministic and cannot be guaranteed to have any particular value, or even consistent values. This can be done directly or, preferably, using the types endpoint. Unfortunately, knowing the name of the Type is rarely enough for many applications. The useInColumn values of these Types will be deliveryservice.

DNS

Delivery Services of this routing type are routed by Traffic Router by providing DNS records that provide the IP addresses of cache servers when clients look up the full Delivery Service FQDN.

HTTP

The Traffic Router(s) responsible for routing this Delivery Service will still answer DNS requests for the Delivery Service FQDN, but will provide its own IP address. The client then directs its HTTP request to the Traffic Router, which will use an HTTP redirection response to direct the client to a cache server.

More generally, though, Delivery Services have a Type that defines not only how traffic is routed, but also how content is cached and semantically defines what “content” means in the context of a given Delivery Service.

ANY_MAP

This is a special kind of Delivery Service that should only be used when control over the clients is guaranteed, and very fine control over the ATS remap.config line for this Delivery Service is required. ANY_MAP is not known to Traffic Router. It is not routed in any way. For Delivery Services of this type, the “Raw Remap Text” field must be defined, as it is the only configuration generated by Traffic Control. The only way for a client to utilize delivery through an ANY_MAP service is by knowing in advance the IP address of one or more Edge-tier cache servers and make the appropriate request(s).

DNS

Uses DNS content routing. Delivers content normally. This is the recommended Type for delivering smaller objects like web page images.

DNS_LIVE[2]

Uses DNS Content routing, but optimizes caching for live video streaming. Specifically, the configuration generated for cache servers responsible for serving content for this Delivery Service will not cache that content on storage disks. Instead, they will make use of RAM block devices dedicated to ATS - as specified by the special RAM_Drive_Prefix and RAM_Drive_Letters Parameters. Also, any Mid-tier of caching is bypassed.

DNS_LIVE_NATNL

Works exactly the same as DNS_LIVE, but is optimized for delivery of live video content across a wide physical area. What this means is that the Mid-tier of caching is not bypassed, unlike DNS_LIVE. The Mid-tier will also use block RAM devices.

HTTP

Uses HTTP content routing, delivers content normally. This is the recommended Type for delivering larger objects like video streams.

HTTP_LIVE[2]

Uses HTTP Content routing, but optimizes caching for live video streaming. Specifically, the configuration generated for cache servers responsible for serving content for this Delivery Service will not cache that content on storage disks. Instead, they will make use of RAM block devices dedicated to ATS - as specified by the special RAM_Drive_Prefix and RAM_Drive_Letters Parameters. Also, any Mid-tier of caching is bypassed.

HTTP_LIVE_NATNL

Works exactly the same as HTTP_LIVE, but is optimized for delivery of live video content across a wide physical area. What this means is that the Mid-tier of caching is not bypassed, unlike HTTP_LIVE. The Mid-tier will also use block RAM devices.

HTTP_NO_CACHE[2]

Uses HTTP Content Routing, but cache servers will not actually cache the delivered content - they act as just proxies. This will bypass any existing Mid-tier entirely (as it’s totally useless when content is not being cached).

STEERING

This is a sort of “meta” Delivery Service. It is used for directing clients to one of a set of Delivery Services, rather than delivering content directly itself. The Delivery Services to which a STEERING Delivery Service routes clients are referred to as “targets”. Targets in general have an associated “value” and can be of several Types that define the meaning of the value - these being:

STEERING_ORDER

The value of a STEERING_ORDER target sets a strict order of preference. In cases where a response to a client contains multiple Delivery Services, those targets with a lower “value” appear earlier than those with a higher “value”. In cases where two or more targets share the same value, they each have an equal chance of being presented to the client - effectively spreading traffic evenly across them.

STEERING_WEIGHT

The values of STEERING_WEIGHT targets are interpreted as “weights”, which define how likely it is that any given client will be routed to a specific Delivery Service - effectively this determines the spread of traffic across each target.

The targets of a Delivery Service may be set using the appropriate section of Traffic Portal or via the steering/{{ID}}/targets and steering/{{ID}}/targets/{{targetID}} Traffic Ops API endpoints.

See also

For more information on setting up a STEERING (or CLIENT_STEERING) Delivery Service, see Configure Delivery Service Steering.

See also

For implementation details about how Traffic Router routes STEERING (and CLIENT_STEERING) Delivery Services, see Steering Feature.

CLIENT_STEERING

A CLIENT_STEERING Delivery Service is exactly like STEERING except that it provides clients with methods of bypassing the weights, orders, and localizations of targets in order to choose any arbitrary target at will. When utilizing these methods, the client will either directly choose a target immediately or request a list of all available targets from Traffic Router and then choose one to which to send a subsequent request for actual content. CLIENT_STEERING also supports two additional target types:

STEERING_GEO_ORDER

These targets behave exactly like STEERING_ORDER targets, but Delivery Services are grouped according to the “locations” of their Origins. Before choosing a Delivery Service to which to direct the client, Traffic Router will first create subsets of choices according to these groupings, and order them by physical distance from the client (closest to farthest). Within these subsets, the values of the targets establish a strict precedence ordering, just like STEERING_ORDER targets.

STEERING_GEO_WEIGHT

These targets behave exactly like STEERING_WEIGHT targets, but Delivery Services are grouped according to the “locations” of their Origins. Before choosing a Delivery Service to which to direct the client, Traffic Router will first create subsets of choices according to these groupings, and order them by physical distance from the client (closest to farthest). Within these subsets, the values of the targets establish the likelihood that any given target within the subset will be chosen for the client - effectively determining the spread of traffic across targets within that subset.

Important

To make use of the STEERING_GEO_ORDER and/or STEERING_GEO_WEIGHT target types, it is first necessary to ensure that at least the “primary” Origin of the Delivery Service has an associated geographic coordinate pair. This can be done either from the Origins page in Traffic Portal, or using the origins Traffic Ops API endpoint.

Note

“Steering” is also commonly used to collectively refer to either of the kinds of Delivery Services that can participate in steering behavior (STEERING and CLIENT_STEERING).

Table 43 Aliases

Name	Use(s)	Type(s)
Content Routing Type	Traffic Portal forms	The name of any of the Delivery Service Types (string)
TypeID	In Go code and Traffic Ops API requests/responses	Integral, unique identifier (bigint, int etc.)

Use Multi-Site Origin Feature

A boolean value that indicates whether or not this Delivery Service serves content for an Origin that provides content from two or more redundant servers. There are very few good reasons for this to not be false. When true, Traffic Ops will configure Mid-tier cache servers to perform load-balancing and other optimizations for redundant origin servers.

Naturally, this assumes that each redundant server is exactly identical, from request paths to actual content. If Multi-Site Origin is configured for servers that are not identical, the client’s experience is undefined. Furthermore, the origin servers may have differing IP addresses, but must serve content for a single FQDN - as defined by the Delivery Service’s Origin Server Base URL. These redundant servers must be configured as servers (server Type ORG) in Traffic Ops - either using the appropriate section of Traffic Portal or the servers endpoint.

Important

In order for a given Mid-tier cache server to support Multi-Site Origins, the value of a Parameter named http.parent_proxy_routing_enable in configuration file records.config must be set to 1 on that server’s Profile. If using an optional secondary grouping of Multi-Site Origins, the Parameter named url_remap.remap_required in configuration file records.config must also be set to 1 on that Profile. These settings must be applied to all Mid-tier cache servers’ that are the parents of any Edge-tier cache server assigned to this Delivery Service.

See also

These parameters are described in the ATS documentation sections for Parent Proxy Configuration and URL Remap Rules, respectively.

Table 44 Aliases

Name	Use(s)	Type(s)
multiSiteOrigin	In Go code and Traffic Ops API requests/responses	unchanged (bool, boolean etc.)
MSO	In documentation and used heavily in discussion in Slack, mailing list etc.	unchanged (usually only used where implicitly true)

A Delivery Service Profile can have Parameters that affect Multi-Site Origin configuration. These are detailed in Parameters that Affect Multi-Site Origin and Parent Down Behavior.

See also

A quick guide on setting up Multi-Site Origins is given in Configure Multi-Site Origin.

xml_id

A text-based unique identifier for a Delivery Service. Many Traffic Ops API endpoints and internal ATC functions use this to uniquely identify a Delivery Service as opposed to the historically favored “ID”. This string will become a part of the CDN service domain, which all together looks like: Delivery Service Routing Name.Delivery Service xml_id.CDN Subdomain.CDN Domain.Top-Level Domain. Must be all lowercase, no spaces or special characters, but may contain dashes/hyphens[1].

Table 45 Aliases

Name	Use(s)	Type(s)
Key	Traffic Portal tables and forms	unchanged (string)

Delivery Service Parameters

Features which are new, experimental, or not significant enough to be first-class Delivery Service fields are often added as Parameters. To use these, add a Profile to the Delivery Service, with the given Parameter assigned.

parent.config

The following Parameters must have the Config File parent.config to take effect - even if, strictly speaking, they aren’t used to modify the contents of the ATS parent.config configuration file.

See also

See the Apache Traffic Server documentation for parent.config and their documentation for strategies.yaml for more information on its implementation of parent selection (and in particular Multi-Site Origins).

• try_all_primaries_before_secondary - on a Delivery Service Profile, if this exists, try all “primary parents” before “failing over” to “secondary parents”, which may be ideal if objects are unlikely to be in cache. The default behavior is to immediately fail to a secondary, which is ideal if objects are likely to be in cache, as the first consistent-hashed “secondary parent” will be the “primary parent” in its own Cache Group and therefore receive requests for that object from clients near its own Cache Group.

  Caution

  The Value of this Parameter is ignored. It is considered implicitly “truthy” if the Parameter is present at all on the Profile. This means that the Values false, 0, and "no" will all result in the behavior described being adopted, contrary to what might be intuitively expected.

• enable_h2 - On a Delivery Service Profile, if the Value of this Parameter begins with t or y (case-insensitive), HTTP/2 is enabled for client requests. ATS must also be listening for HTTP/2 - configured in records.config - or this will have no effect.

  Implementation Detail

  This Parameter does not affect the contents of parent.config, but instead either ssl_server_name.yaml in ATS 8 or sni.yaml in ATS 9. It has the parent.config Config File value for consistency.

  Warning

  Interpretation of the Value of this Parameter is extremely permissive. For example, the Values t, Y, True, yes, talse, yno, Yeah, don't do this, You should never under any circumstances allow HTTP/2, and totally horrible idea to enable this all equally mean “true”. No part of ATC checks or warns about typos or strange Values for this Parameter, so take care to prevent typos, misspellings, and the like to avoid confusing situations.

• tls_versions - on a Delivery Service Profile, if this exists, enable the given comma-delimited[4] TLS versions for client requests e.g. 1.1,1.2,1.3. ATS must also be accepting those TLS versions - configured in records.config - or this will have no effect.

  Implementation Detail

  This Parameter does not affect the contents of parent.config, but instead either ssl_server_name.yaml in ATS 8 or sni.yaml in ATS 9. It has the parent.config Config File value for consistency.

  Caution

  The actual permitted TLS versions are the union of those laid out in this Parameter and those configured as the TLS Versions property of the Delivery Service.

• use_peering - on a Deliver Service Profile, if this exists and is true, the strategy ring_mode will be set to peering_ring for large library DNS support.

  Implementation Detail

  This Parameter does not affect the contents of parent.config, but instead strategies.yaml in ATS 9. It has the parent.config Config File value for consistency.

• merge_parent_groups - on a Deliver Service Profile, if this exists, moves each of the space-separated Cache Groups named in the Value from the secondary parent list into the primary parent list. This can be used to combine all parents into a single consistent hash ring.

Deprecated since version 6.2: In Traffic Ops API version 4, TLS versions should be configured using the TLS Versions property of the Delivery Service, and support for this Parameter will be removed at some point after the stabilization of Traffic Ops API version 4.

Parameters that Affect Multi-Site Origin and Parent Down Behavior

Each Parameter directly corresponds to a field in a line of the ATS parent.config file (usually by almost the same name), and documentation for these fields is provided in the form of links to their entries in the ATS documentation.

Table 46 Parameters of a Delivery Service Profile that Affect MSO Configuration

Name | ATS parent.config field			Effect
algorithm	round_robin		Sets the algorithm used to determine from which origin server content will be requested.
parent_retry	parent_retry		Sets whether the cache servers will use “simple retries”, “unavailable server retries”, or both. (deprecated)
simple_server_retry_responses	simple_server_retry_responses		Defines HTTP response codes for an origin server that necessitate a “simple retry”.
max_simple_retries	max_simple_retries		Sets a strict limit on the number of “simple retries” allowed before giving up
unavailable_server_retry_response_codes	unavailable_server_retry_responses		Defines HTTP response codes from an origin server that indicate it is currently “unavailable”.
max_unavailable_server_retries	max_unavailable_server_retries		Sets a strict limit on the number of times the cache server will attempt to request content from an origin server that has previously been considered “unavailable”.

The above Parameters are supported for first, inner and last tiers by specifying prefixes first., inner. and last., applicable to both topology and non topology. This allows fine tuning of marking parents “down” and retry behavior inside a CDN.

Deprecated since version 7.0: The mso. prefix is deprecated. last. prefix should be preferred although no prefix can also be used.

Deprecated since version 7.0: The parent_retry parameters are now inferred from the simple retry and unavailable server retry parameters. To disable “simple retries” for a Profile, set the Value of its max_simple_retries Parameter to 0, and the Value of its max_simple_retry_responses Parameter to an empty string. “Unavailable server retries” may disabled in much the same way, using the analogous Parameters.

Implementation Detail

With Apache Traffic Server 8.1.x the simple_retry_response_codes setting is not available.

Implementation Detail

With Apache Traffic Server 9.2.x unavailable_server_retry_response_codes are limited to 5xx responses and simple_retry_response_codes are limited to 4xx.

Implementation Detail

Apache Traffic Server 9.2.x allows more flexibility with 4xx and 5xx codes available for use with simple_retry_response_codes.

See also

To see how the Values of these Parameters are interpreted, refer to the Apache Traffic Server documentation on the parent.config configuration file

[1] (1,2)

Some things to consider when choosing an xml_id and routing name: the name should be descriptive and unique, but as brief as possible to avoid creating a monstrous FQDN. Also, because these are combined to form an FQDN, they should not contain any characters that are illegal for a DNS subdomain, e.g. . (period/dot). Finally, the restrictions on what characters are allowable (especially in xml_id) are, in general, NOT enforced by the Traffic Ops API, so take care that the name is appropriate. See RFC 1035 for exact guidelines.

[2] (1,2,3)

These Delivery Services Types are vulnerable to what this writer likes to call the “Duplicate Origin Problem”. This problem is tracked by Issue #3537.

[3] (1,2)

These regular expression types can only appear in the Match List of HTTP-Routed Delivery Services.

[4]

The list may also be separated by spaces or semicolons, or spread across lines.