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, in the legacy Perl Traffic Ops codebase, and several times for various Traffic Ops API versions in the new Go Traffic Ops codebase. Go-specific data structures can be found in the project’s GoDoc documentation. 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.

Active

Whether or not this Delivery Service is active on the CDN and can be served. When a Delivery Service is not “active”, Traffic Router will not be made aware of its existence - i.e. it will not appear in CDN Snapshots. Setting a Delivery Service to be “active” (or “inactive”) will require that a new Snapshot be taken.

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 1 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.

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.

Table 2 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 3 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 4 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.

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 ORT.

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)

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

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 6 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 a comma-delimited string of said country codes. When creating a Delivery Service with this field or modifying the Geo Limit Countries field on an existing Delivery Service, 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 7 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 :abbr:`FQDN (Fully Qualified Domain Name)`. 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 8 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 9 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 10 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 11 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 12 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 13 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).

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.)

Long Description 2

Free text field that has no strictly defined purpose.

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

Long Description 3

Free text field that has no strictly defined purpose.

Name Use(s) Type(s)
longDesc2[2] 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.[4]
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.[4]
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 14 Aliases
Name Use(s) Type(s)
deliveryservice_regex Traffic Ops database unique, integral identifier for a regular expression

Max DNS Answers

The maximum number of Edge-tier cache server IP addresses that the Traffic Router will include in responses to DNS requests for DNS-Routed Delivery Services. The Traffic Ops API restricts this value to the range [1, 15], but no matching restraints are placed on the actual data as stored in the Traffic Ops Database. 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.

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 ORT.

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 15 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 an integral, unique identifier for said Profile.

Table 16 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 17 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 18 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 Go/Perl 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)

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.

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 ORT. 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.

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

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.

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.

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

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.

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 Service 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.

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.

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 21 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.

Static DNS Entries

Static DNS Entries can be added under a Delivery Service’s domain. These DNS records can be configured in the Delivery Service 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 22 Aliases
Name Use(s) Type(s)
TenantID Go code and Traffic Ops API requests/responses Integral, unique identifier (bigint, int etc.)

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 23 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 24 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[3]
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[3]
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[3]
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 25 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 26 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 the Parameters of a Delivery Service Profile that Affect MSO Configuration table. All of these Parameters should have their Configuration File set to parent.config. Each Parameter directly corresponds to a field in a line of the ATS parent.config file <https://docs.trafficserver.apache.org/en/7.1.x/admin-guide/files/parent.config.en.html> (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 27 Parameters of a Delivery Service Profile that Affect MSO Configuration
Name ATS parent.config field Effect
mso.algorithm round_robin Sets the algorithm used to determine from which origin server content will be requested.
mso.max_simple_retries max_simple_retries Sets a strict limit on the number of “simple retries” allowed before giving up
mso.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”.
mso.parent_retry parent_retry Sets whether the cache servers will use “simple retries”, “unavailable server retries”, or both.
mso.simple_retry_response_codes UNKNOWN UNKOWN - supposedly defines HTTP response codes from an origin server that necessitate a “simple retry”.
mso.unavailable_server_retry_response_codes unavailable_server_retry_responses Defines HTTP response codes from an origin server that indicate it is currently “unavailable”.

Warning

The mso.simple_retry_response_codes Parameter has no apparent, possible use according to the ATS parent.config documentation. Whether or not it has any effect - let alone the intended effect - is not known, and its use is therefore strongly discouraged.

See also

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

See also

See the Apache Traffic Server documentation for more information on its implementation of Multi-Site Origins.

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 28 Aliases
Name Use(s) Type(s)
Key Traffic Portal tables and forms unchanged (string)
[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) In source code and Traffic Ops API responses, the “Long Description” fields of a Delivery Service are “0-indexed” - hence the names differing slightly from the ones displayed in user-friendly UIs.
[3](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.
[4](1, 2) These regular expression types can only appear in the Match List of HTTP-Routed Delivery Services.