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.

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

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 7 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 8 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 9 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 10 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 11 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 12 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 13 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 14 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 ORT.

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

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

Long Description 2

Free text field that has no strictly defined purpose.

Name

Use(s)

Type(s)

longDesc12

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)

longDesc22

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

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.

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.

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 16 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 17 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 18 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 19 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)

3

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

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

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

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

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 22 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 23 Aliases

Name

Use(s)

Type(s)

TenantID

Go code and Traffic Ops API requests/responses

Integral, unique identifier (bigint, int etc.)

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 24 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 25 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_LIVE3

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_LIVE3

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_CACHE3

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 26 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 27 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 28 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

UNKNOWN - 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/hyphens1.

Table 29 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.