Profiles and Parameters

Profiles are a collection of configuration options, defined partially by the Profile’s Type (not to be confused with the more general “Type” used by many other things in Traffic Control) and partially by the Parameters set on them. Mainly, Profiles and Parameters are used to configure cache servers, but they can also be used to configure parts of (nearly) any Traffic Control component, and can even be linked with more abstract concepts like Delivery Services and Cache Groups. The vast majority of configuration done within a Traffic Control CDN must be done through Profiles and Parameters, which can be achieved either through the Traffic Ops API or in the Profiles view of Traffic Portal. For ease of use, Traffic Portal allows for duplication, comparison, import and export of Profiles including all of their associated Parameters.

See also

For Delivery Service Profile Parameters, see Delivery Service Parameters.

Profiles

Properties

Profile objects as represented in e.g. the Traffic Ops API or in the Traffic Portal Profiles view have several properties that describe their general operation. In certain contexts, the Parameters assigned to a Profile (and/or the integral, unique identifiers thereof) may appear as properties of the Profile, but that will not appear in this section as a description of Parameters is provided in the section of that name.

CDN

A Profile is restricted to operate within a single CDN. Often, “CDN” (or “cdn”) refers to the integral, unique identifier of the CDN, but occasionally it refers to the name of said CDN. It may also appear as e.g. cdnId or cdnName in Traffic Ops API payloads and responses. A Profile may only be assigned to a server, Delivery Service, or Cache Group within the same CDN as the Profile itself.

Description

Profiles may have a description provided by the creating user (or Traffic Control itself in the case of the Default Profiles). The Traffic Ops API does not enforce length requirements on the description (though Traffic Portal does), and so it’s possible for Profiles to have empty descriptions, though it is strongly recommended that Profiles have meaningful descriptions.

ID

An integral, unique identifier for the Profile.

Name

Ostensibly this is simply the Profile’s name. However, the name of a Profile has drastic consequences for how Traffic Control treats it. Particularly, the name of a Profile is heavily conflated with its Type. These relationships are discussed further in the Type section, on a Type-by-Type basis.

The Name of a Profile may not contain spaces.

Changed in version ATCv6: In older versions of ATC, Profile Names were allowed to contain spaces. The Traffic Ops API will reject creation or update of Profiles that have spaces in their Names as of ATC version 6, so legacy Profiles will need to be updated to meet this constraint before they can be modified.

Routing Disabled

This property can - and in fact must - exist on a Profile of any Type, but it only has any meaning on a Profile that has a name matching the constraints placed on the names of ATS_PROFILE-Type Profiles. This means that it will also have meaning on Profiles of Type UNK_PROFILE that for whatever reason have names beginning with EDGE or MID. When this field is defined as 1 (may be displayed as true in e.g. Traffic Portal), Traffic Router will not be informed of any Delivery Services to which the cache server using this Profile may be assigned. Effectively, this means that client traffic cannot be routed to them, although existing connections would be uninterrupted.

Type

A Profile’s Type determines how its configured Parameters are treated by various components, and often even determine how the object using the Profile is treated (particularly when it is a server). Unlike the more general “Type” employed by Traffic Control, the allowed Types of Profiles are set in stone, and they are as follows.

Danger

Nearly all of these Profile Types have strict naming requirements, and it may be noted that some of said requirements are prefixes ending with _, while others are either not prefixes or do not end with _. This is exactly true; some requirements need that _ and some may or may not have it. It is our suggestion, therefore, that for the time being all prefixes use the _ notation to separate words, so as to avoid causing headaches remembering when that matters and when it does not.

ATS_PROFILE

A Profile that can be used with either an Edge-tier or Mid-tier cache server (but not both, in general). This is the only Profile type that will ultimately pass its Parameters on to ORT in the form of generated configuration files. For this reason, it can make use of the Strings with Special Meaning to t3c in the values of some of its Parameters.

Warning

For legacy reasons, the names of Profiles of this type must begin with EDGE or MID. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise! This includes caches/stats.

DS_PROFILE

A Profile that, rather than applying to a server, is instead used by a Delivery Service.

ES_PROFILE

A Profile for ElasticSearch servers. This has no known special meaning to any component of Traffic Control, but if ElasticSearch is in use the use of this Profile Type is suggested regardless.

Warning

For legacy reasons, the names of Profiles of this type must begin with ELASTICSEARCH. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise!

GROVE_PROFILE

A Profile for use with the experimental Grove HTTP caching proxy.

INFLUXDB_PROFILE

A Profile used with InfluxDB, which is used by Traffic Stats.

Warning

For legacy reasons, the names of Profiles of this type must begin with INFLUXDB. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise!

KAFKA_PROFILE

A Profile for Kafka servers. This has no known special meaning to any component of Traffic Control, but if Kafka is in use the use of this Profile Type is suggested regardless.

Warning

For legacy reasons, the names of Profiles of this type must begin with KAFKA. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise!

LOGSTASH_PROFILE

A Profile for Logstash servers. This has no known special meaning to any component of Traffic Control, but if Logstash is in use the use of this Profile Type is suggested regardless.

Warning

For legacy reasons, the names of Profiles of this type must begin with LOGSTASH_. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise!

ORG_PROFILE

A Profile that may be used by either origin servers or Origins (no, they aren’t the same thing).

Warning

For legacy reasons, the names of Profiles of this type must begin with MSO, or contain either ORG or ORIGIN anywhere in the name. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise!

RIAK_PROFILE

A Profile used for each Riak server in a Traffic Stats cluster.

Warning

For legacy reasons, the names of Profiles of this type must begin with RIAK. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise!

SPLUNK_PROFILE

A Profile meant to be used with Splunk servers. This has no known special meaning to any component of Traffic Control, but if Splunk is in use the use of this Profile Type is suggested regardless.

Warning

For legacy reasons, the names of Profiles of this type must begin with SPLUNK. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise!

TM_PROFILE

A Traffic Monitor Profile.

Warning

For legacy reasons, the names of Profiles of this type must begin with RASCAL_. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise!

TP_PROFILE

A Traffic Portal Profile. This has no known special meaning to any Traffic Control component(s) (not even Traffic Portal itself), but its use is suggested for the profiles used by any and all Traffic Portal servers anyway.

TR_PROFILE

A Traffic Router Profile.

Warning

For legacy reasons, the names of Profiles of this type must begin with CCR_ or TR_. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise!

TS_PROFILE

A Traffic Stats Profile.

Caution

For legacy reasons, the names of Profiles of this type must be TRAFFIC_STATS. This is not enforced by the Traffic Ops API or Traffic Portal, but certain Traffic Control operations/components expect this and will fail to work otherwise! Furthermore, because Profile names must be unique, this means that only one TS_PROFILE-Type Profile can exist at a time.

UNK_PROFILE

A catch-all type that can be assigned to anything without imbuing it with any special meaning or behavior.

Tip

A Profile of the wrong type assigned to a Traffic Control component will (in general) cause it to function incorrectly, regardless of the Parameters assigned to it.

Default Profiles

Traffic Control comes with some pre-installed Profiles for its basic components, but users are free to define their own as needed. Additionally, these default Profiles can be modified or even removed completely. One of these Profiles is The GLOBAL Profile, which has a dedicated section.

INFLUXDB

A Profile used by InfluxDB servers that store Traffic Stats information. It has a Type of UNK_PROFILE and is assigned to the special “ALL” CDN.

RIAK_ALL

This Profile is used by Traffic Vault, which is, generally speaking, the only instance in Traffic Control as it can store keys for an arbitrary number of CDNs. It has a Type of UNK_PROFILE and is assigned to the special “ALL” CDN.

TRAFFIC_ANALYTICS

A default Profile that was intended for use with the now-unplanned “Traffic Analytics” ATC component. It has a Type of UNK_PROFILE and is assigned to the special “ALL” CDN.

TRAFFIC_OPS

A Profile used by the Traffic Ops server itself. It’s suggested that any and all “mirrors” of Traffic Ops for a given Traffic Control instance be recorded separately and all assigned to this Profile for record-keeping purposes. It has a Type of UNK_PROFILE and is assigned to the special “ALL” CDN.

TRAFFIC_OPS_DB

A Profile used by the PostgreSQL database server that stores all of the data needed by Traffic Ops. It has a Type of UNK_PROFILE and is assigned to the special “ALL” CDN.

TRAFFIC_PORTAL

A Profile used by Traffic Portal servers. This profile name has no known special meaning to any Traffic Control components (not even Traffic Portal itself), but its use is suggested for Traffic Portal servers anyway. It has a Type of UNK_PROFILE and is assigned to the special “ALL” CDN.

TRAFFIC_STATS

This is the only Profile used by Traffic Stats (though InfluxDB servers have their own Profile(s)). It has a Type of UNK_PROFILE and is assigned to the special “ALL” CDN.

In addition to these Profiles, each release of Apache Traffic Control is accompanied by a set of suggested Profiles suitable for import in the Profiles view of Traffic Portal. They may be found on the Profiles Downloads Index page. These Profiles are typically built from production Profiles by a company using Traffic Control, and as such are typically highly specific to the hardware and network infrastructure available to them. None of the Profiles bundled with a release are suitable for immediate use without modification, and in fact many of them cannot actually be imported directly into a new Traffic Control environment, because Profiles with the same Names already exist (as above).

Administrators may alternatively wish to consult the Profiles and Parameters available in the CDN in a Box environment, as they might be more familiar with them. Furthermore, those Profiles are built with a minimum running Traffic Control system in mind, and thus may be easier to look through. The Profiles and their associated Parameters may be found within the infrastructure/cdn-in-a-box/traffic_ops_data/profiles/ directory.

The GLOBAL Profile

There is a special Profile of Type UNK_PROFILE that holds global configuration information - its Name is “GLOBAL”, its Type is UNK_PROFILE and it is assigned to the special “ALL” CDN. The Parameters that may be configured on this Profile are laid out in the Global Profile Parameters Table.

Table 47 Global Profile Parameters

Name

Config File

Value

tm.url

global

The URL at which this Traffic Ops instance services requests.

tm.rev_proxy.url

global

Not required. The URL where a caching proxy for configuration files generated by Traffic Ops may be found. Requires a minimum ORT version of 2.1. When configured, ORT will request configuration files via this FQDN, which should be set up as a reverse proxy to the Traffic Ops server(s). The suggested cache lifetime for these files is 3 minutes or less. This setting allows for greater scalability of a CDN maintained by Traffic Ops by caching configuration files of profile and CDN scope, as generating these is a very computationally expensive process.

tm.toolname

global

The name of the Traffic Ops tool. Usually “Traffic Ops” - this will appear in the comment headers of generated configuration files.

tm.infourl

global

This is the “for more information go here” URL, which used to be visible in the “About” page of the now-deprecated Traffic Ops UI.

tm.instance_name

global

The name of the Traffic Ops instance - typically to distinguish instances when multiple are active.

tm.traffic_mon_fwd_proxy

global

When collecting stats from Traffic Monitor, Traffic Ops will use this forward proxy instead of the actual Traffic Monitor host. Setting this Parameter can significantly lighten the load on the Traffic Monitor system and it is therefore recommended that this be set on a production system.

use_reval_pending

global

When this Parameter is present and its Value is exactly “1”, Traffic Ops will separately keep track of cache servers’ updates and pending Content Invalidation Jobs. This behavior should be enabled by default, and disabling it, while still possible is EXTREMELY DISCOURAGED.

geolocation.polling.url

CRConfig.json

The location of a geographic IP mapping database for Traffic Router instances to use.

geolocation6.polling.url

CRConfig.json

The location of a geographic IPv6 mapping database for Traffic Router instances to use.

maxmind.default.override

CRConfig.json

The destination geographic coordinates to use for client location when the geographic IP mapping database returns a default location that matches the country code. This parameter can be specified multiple times with different values to support default overrides for multiple countries. The reason for the name “maxmind” is because the default geographic IP mapping database used by Traffic Control is MaxMind’s GeoIP2 database. The format of this Parameter’s Value is: Country Code;Latitude,Longitude, e.g. US;37.751,-97.822

maxRevalDurationDays

regex_revalidate.config

This Parameter sets the maximum duration, in days, for which a Content Invalidation Job may run. Furthermore, while there is no restriction placed on creating multiple Parameters with this Name and Config File - potentially with differing Values - this is EXTREMELY DISCOURAGED as any Parameter that has both that Name and Config File might be used when generating any given regex_revalidate.config file for any given cache server and whenever such Parameters exist, the actual maximum duration for Content Invalidation Jobs is undefined, and CAN and WILL differ from server to server, and configuration file to configuration file.

Some of these Parameters have the Config File value global, while others have CRConfig.json. This is not a typo, and the distinction is that those that use global are typically configuration options relating to Traffic Control as a whole or to Traffic Ops itself, whereas CRConfig.json is used by configuration options that are set globally, but pertain mainly to routing and are thus communicated to Traffic Routers through CDN Snapshots (which historically were called “CRConfig Snapshots” or simply “the CRConfig”). When a Parameter has a Config File value that isn’t one of global or CRConfig.json, it refers to the global configuration of said Config File across all servers that use it across all CDNs configured in Traffic Control. This can be used to easily apply extremely common configuration to a great many servers in one place.

Parameters

A Parameter is usually a way to set a line in a configuration file that will appear on the servers using Profiles that have said Parameter. More generally, though, a Parameter merely describes some kind of configuration for some aspect of some thing. There are many Parameters that must exist for Traffic Control to work properly, such as those on The GLOBAL Profile or the Default Profiles. Some Traffic Control components can be associated with Profiles that only have a few allowed (or actually just meaningful - others are ignored and don’t cause problems) but some can have any number of Parameters to describe custom configuration of things of which Traffic Control itself may not even be aware (most notably cache servers). For most Parameters, the meaning of each Parameter’s various properties are very heavily tied to the allowed contents of Apache Traffic Server configuration files.

Properties

When represented in Traffic Portal (in the Parameters view) or in Traffic Ops API request and/or response payloads, a Parameter has several properties that define it. In some of these contexts, the Profiles to which a Parameter is assigned (and/or the integral, unique identifiers thereof) are represented as a property of the Parameter. However, an explanation of this “property” is not provided here, as the Profiles section exists for the purpose of explaining those.

Config File

This (usually) names the configuration file to which the Parameter belongs. Note that it is only the name of the file and not the full path to the file - e.g. remap.config not /opt/trafficserver/etc/trafficserver/remap.config. To define the full path to any given configuration file, Traffic Ops relies on a reserved Name value: “location”.

See also

This section is only meant to cover the special handling of Parameters assigned to specific Config File values. It is not meant to be a primer on Apache Traffic Server configuration files, nor is it intended to be exhaustive of the manners in which said files may be manipulated by Traffic Control. For more information, consult the documentation for Apache Traffic Server configuration files.

Certain Config Files are handled specially by Traffic Ops’s configuration file generation. Specifically, the format of the configuration is tailored to be correct when the syntax of a configuration file is known. However, these configuration files must have “location” Parameters on the Profile of servers, or they will not be generated. The Config File values that are special in this way are detailed within this section. When a Config File is none of these special values, each Parameter assigned to given server’s Profile with the same Config File value will create a single line in the resulting configuration file (with the possible exception being when the Name is “header”)

12M_facts

This legacy file is generated entirely from a Profile’s metadata, and cannot be affected by Parameters.

Tip

This Config File serves an unknown and likely historical purpose, so most users/administrators/developers don’t need to worry about it.

50-ats.rules

Parameters have no meaning when assigned to this Config File (except “location”), but it is affected by Parameters that are on the same Profile with the Config File storage.config - NOT this Config File. For each letter in the special “Drive Letters” Parameter, a line will be added of the form KERNEL=="PrefixLetter", OWNER="ats" where Prefix is the Value of the Parameter with the Name “Drive Prefix” and the Config File storage.config - but with the first instance of /dev/ removed - , and Letter is the drive letter. Also, if the Parameter with the Name “RAM Drive Prefix” exists on the same Profile assigned to the server, a line will be inserted for each letter in the special “RAM Drive Letters” Parameter of the form KERNEL=="PrefixLetter", OWNER="ats" where Prefix is the Value of the “RAM Drive Prefix” Parameter - but with the first instance of /dev/ removed -, and Letter is the drive letter.

Tip

This Config File serves an unknown and likely historical purpose, so most users/administrators/developers don’t need to worry about it.

astats.config

This configuration file will be generated with a line for each Parameter with this Config File value on the cache server’s Profile in the form Name=Value where Name is the Parameter’s Name with trailing characters that match __\d+$ stripped, and Value is its Value.

bg_fetch.config

This configuration file always generates static contents besides the header, and cannot be affected by any Parameters (besides its “location” Parameter).

See also

For an explanation of the contents of this file, consult the Background Fetch Apache Traffic Server plugin’s official documentation.

cache.config

This configuration is built entirely from Delivery Service configuration, and cannot be affected by Parameters.

cacheurlanything.config

Config Files that match this pattern - where anything is a string of zero or more characters - can only be generated by providing a location and their contents will be fully determined by properties of Delivery Services.

Deprecated since version ATCv3.0: This configuration file is only used by Apache Traffic Server version 6.x, whose use is deprecated both by that project and Traffic Control. These Config Files will have no special meaning at some point in the future.

chkconfig

This actually isn’t a configuration file at all, kind of. Specifically, it is a valid configuration file for the legacy chkconfig utility - but it is never written to disk on any cache server. Though all Traffic Control-supported systems are now using systemd(8), ORT still uses chkconfig-style configuration to set the status of services on its host system(s). This means that any Parameter with this Config File value should have a Name that is the name of a service on the cache servers using the Profile to which the Parameter is assigned, and it’s Value should be a valid chkconfig configuration line for that service.

CRConfig.json

In general, the term “CRConfig” refers to CDN Snapshots, which historically were called “CRConfig Snapshots” or simply “the CRConfig”. Parameters with this Config File should be only be on either The GLOBAL Profile where they will affect global routing configuration, or on a Traffic Router’s Profile where they will affect routing configuration for that Traffic Router only.

See also

For the available configuration Parameters for a Traffic Router Profile, see The Traffic Router Profile.

drop_qstring.config

This configuration file will be generated with a single line that is exactly: /([^?]+) $s://$t/$1n unless a Parameter exists on the Profile with this Config File value, and the Name “content”. In the latter case, the contents of the file will be exactly the Parameter’s Value (with terminating newline appended).

global

In general, this Config File isn’t actually handled specially by Traffic Ops when generating server configuration files. However, this is the Config File value typically used for Parameters assigned to The GLOBAL Profile for truly “global” configuration options, and it is suggested that this precedent be maintained - i.e. don’t create Parameters with this Config File.

hdr_rw_anything.config

Config Files that match this pattern - where anything is zero or more characters - are written specially by Traffic Ops to accommodate the DSCP setting of Delivery Services.

Tip

The anything in those file names is typically a Delivery Service’s xml_id - though the inability to affect the file’s contents is utterly independent of whether or not a Delivery Service with that xml_id actually exists.

See also

For information on the contents of files like this, consult the Header Rewrite Apache Traffic Server plugin’s documentation

hosting.config

This configuration file is mainly generated based on the assignments of cache servers to Delivery Services and the Cache Group hierarchy, but there are a couple of Parameter Names that can affect it when assigned to this Config File. When a Parameter assigned to the storage.config Config File - NOT this Config File - with the Name “RAM_Drive_Prefix” exists, it will cause lines to be generated in this configuration file for each Delivery Service that is of on of the Types DNS_LIVE (only if the server is an Edge-tier cache server), HTTP_LIVE (only if the server is an Edge-tier cache server), DNS_LIVE_NATNL, or HTTP_LIVE_NATNL to which the cache server to which the Profile containing that Parameter belongs is assigned. Specifically, it will cause each of them to use volume=1 UNLESS the Parameter with the Name “Drive_Prefix” associated with Config File storage.config - again, NOT this Config File - also exists, in which case they will use volume=2.

Caution

If a Parameter with Config File storage.config and Name “RAM_Drive_Prefix” does not exist on a Profile, then the cache servers using that Profile will be incapable of serving traffic for Delivery Services of the aforementioned Types, even when a “location” Parameter exists.

See also

For an explanation of the syntax of this configuration file, refer to the Apache Traffic Server hosting.config documentation.

ip_allow.config

This configuration file is mostly generated from various server data, but can be affected by a Parameter that has a Name of “purge_allow_ip”, which will cause the insertion of a line with src_ip=VALUE action=ip_allow method=ALL where VALUE is the Parameter’s Value. Additionally, Parameters with Names like coalesce_masklen|number_v4|6 cause Traffic Ops to generate coalesced IP ranges in different ways. In the case that number was used, the Parameter’s Value sets the the maximum number of IP address that may be coalesced into a single range. If masklen was used, the lines that are generated are coalesced into CIDR ranges using mask lengths determined by the Value of the parameter (using ‘4’ sets the mask length of IPv4 address coalescing while using ‘6’ sets the mask length to use when coalescing IPv6 addresses). This is not recommended, as the default mask lengths allow for maximum coalescence. Furthermore, if two Parameters on the same Profile assigned to a server having Config File values of ip_allow.config and Names that are both “coalesce_masklen_v4” but each has a different Value, then the actual mask length used to coalesce IPv4 addresses is undefined (but will be one of the two). All forms of the “coalescence Parameters” have this problem.

Implementation Detail

At the time of this writing, coalescence is implemented through the the NetAddr::IP Perl library.

See also

The Apache Traffic Server ip_allow.config documentation explains the syntax and meaning of lines in that file.

logging.config

This configuration file can only be affected by Parameters with specific Names. Specifically, for each Parameter assigned to this Config File on the Profile used by the cache server with the name LogFormatN.Name where N is either the empty string or a natural number on the interval [1,9] the text in Log Format Snippet will be inserted. In that snippet, NAME is the Value of the Parameter with the Name LogFormatN.Name, and FORMAT is the Value of the Parameter with the Name LogFormatN.Format for the same value of N2.

#9 Log Format Snippet
NAME = format {
    Format = 'FORMAT '
}

Tip

The order in which these Parameters are considered is exactly the numerical ordering implied by N (starting with it being empty). However, each section is generated for all values of N before moving on to the next.

Furthermore, for a given value of N - as before restricted to either the empty string or a natural number on the interval [1,9] -, if a Parameter exists on the cache server’s Profile having this Config File value with the Name LogFilterN.Name, a line of the format NAME = filter.TYPE.('FILTER') will be inserted, where NAME is the Value of the Parameter with the Name LogFilterN.Name, TYPE is the Value of the Parameter with the Name LogFilterN.Type, and FILTER is the Value of the Parameter with the name LogFilterN.Filter3.

Note

When, for a given value of N, a Parameter with the Name LogFilterN.Name exists, but a Parameter with the Name LogFilterN.Type does not exist, the value of TYPE will be accept.

Finally, for a given value of N, if a Parameter exists on the cache server’s Profile having this Config File value with the Name LogObjectN.Filename, the text in Log Object Snippet will be inserted. In that snippet, TYPE is the Value of the Parameter with the Name LogObjectN.Type

#10 Log Object Snippet
log.TYPE {
  Format = FORMAT,
  Filename = 'FILENAME',

Note

When, for a given value of N a Parameter with the Name LogObjectN.Filename exists, but a Parameter with the Name LogObjectN.Type does not exist, the value of TYPE in Log Object Snippet will be ascii.

At this point, if the Value of the Parameter with the Name LogObjectN.Type is exactly pipe, a line of the format Filters = FILTERS will be inserted where FILTERS is the Value of the Parameter with the Name LogObjectN.Filters, followed by a line containing only a closing “curly brace” (}) - if and only if said Parameter is not empty. If, however, the Value of the Parameter with the Name LogObjectN.Type is not exactly pipe, then the text in Log Object (not a “pipe”) Snippet is inserted.

#11 Log Object (not a “pipe”) Snippet
  RollingEnabled = ROLLING,
  RollingIntervalSec = INTERVAL,
  RollingOffsetHr = OFFSET,
  RollingSizeMb = SIZE
}

In this snippet, ROLLING is the Value of the Parameter with the Name LogObjectN.RollingEnabled, INTERVAL is the Value of the Parameter with the Name LogObjectN.RollingIntervalSec, OFFSET is the Value of the Parameter with the Name LogObjectN.RollingOffsetHr, and SIZE is the Value of the Parameter with the Name LogObjectN.SizeMb - all still having the same value of N, and the Config File value logging.config, of course.

Warning

The contents of these fields are not validated by Traffic Control - handle with care!

logging.yaml

This is a YAML-format configuration file used by cache servers that use Apache Traffic Server version 8 or higher - for lower versions, users/administrators/developers should instead be configuring logging.config. This configuration always starts with (after the header) the single line: format:. Afterward, for every Parameter assigned to this Config File with a Name like LogFormatN.Name where N is either the empty string or a natural number on the interval [1,9], the YAML fragment shown in Log Format Snippet will be inserted. In this snippet, NAME is the Value of the Parameter with the Name LogFormatN.Name, and for the same value of N FORMAT is the Value of the Parameter with the Name LogFormatN.Format.

#12 Log Format Snippet
 - name: NAME
   format: 'FORMAT'

Tip

The order in which these Parameters are considered is exactly the numerical ordering implied by N (starting with it being empty). However, each section is generated for all values of N before moving on to the next.

After this, a single line containing only filters: is inserted. Then, for each Parameter on the cache server’s Profile with a Name like LogFilterN.Name where N is either the empty string or a natural number on the interval [1,9], the YAML fragment in Log Filter Snippet will be inserted. In that snippet, NAME is the Value of the Parameter with the Name LogFilterN.Name, TYPE is the Value of the Parameter with the Name LogFilterN.Type for the same value of N, and FILTER is the Value of the Parameter with the Name LogFilterN.Filter for the same value of N.

#13 Log Filter Snippet
- name: NAME
  action: TYPE
  condition: FILTER

Note

When, for a given value of N, a Parameter with the Name LogFilterN.Name exists, but a Parameter with the Name LogFilterN.Type does not exist, the value of TYPE in Log Filter Snippet will be accept.

At this point, a single line containing only logs: is inserted. Finally, for each Parameter on the cache server’s Profile assigned to this Config File with a Name like LogObjectN.Filename where N is once again either an empty string or a natural number on the interval [1,9] the YAML fragment in Log Object Snippet will be inserted. In this snippet, for a given value of N TYPE is the Value of the Parameter with the Name LogObjectN.Type, FILENAME is the Value of the Parameter with the Name LogObjectN.Filename, FORMAT is the Value of the Parameter with the Name LogObjectN.Format.

#14 Log Object Snippet
- mode: TYPE
  filename: FILENAME
  format: FORMAT
  ROLLING_OR_FILTERS

Note

When, for a given value of N a Parameter with the Name LogObjectN.Filename exists, but a Parameter with the Name LogObjectN.Type does not exist, the value of TYPE in Log Object Snippet will be ascii.

ROLLING_OR_FILTERS will be one of two YAML fragments based on the Value of the Parameter with the name LogObjectN.Type. In particular, if it is exactly pipe, then ROLLING_OR_FILTERS will be filters: [FILTERS] where FILTERS is the Value of the Parameter assigned to this Config File with the Name LogObjectN.Filters for the same value of N. If, however, the Value of the Parameter with the Name LogObjectN.Type is not exactly pipe, ROLLING_OR_FILTERS will have the format given by Log Object (not a “pipe”) Snippet. In that snippet, ROLLING is the Value of the Parameter with the Name LogObjectN.RollingEnabled, INTERVAL is the Value of the Parameter with the Name LogObjectN.RollingIntervalSec, OFFSET is the Value of the Parameter with the Name LogObjectN.RollingOffsetHr, and SIZE is the Value of the Parameter with the Name LogObjectN.RollingSizeMb - all for the same value of N and assigned to the logging.yaml Config File, obviously.

#15 Log Object (not a “pipe”) Snippet
  rolling_enabled: ROLLING
  rolling_interval_sec: INTERVAL
  rolling_offset_hr: OFFSET
  rolling_size_mb: SIZE

See also

For an explanation of YAML syntax, refer to the official specification thereof. For an explanation of the syntax of a valid Apache Traffic Server logging.yaml configuration file, refer to that project’s dedicated documentation.

logs_xml.config

This configuration file is somewhat more complex than most Config Files, in that it generates XML document tree segments1 for each Parameter on the cache server’s Profile rather than simply a plain-text line. Specifically, up to ten of the document fragment shown in LogFormat Snippet will be inserted, one for each Parameter with this Config File value on the cache server’s Profile that has a Name like LogFormatN.Name where N is either the empty string or a natural number on the range [1,9]. In that snippet, the string NAME is actually the Value of the Parameter with the Name LogFormatN.Name" FORMAT is the Value of the Parameter with the Name LogFormatN.Format2, where again N is either the empty string or a natural number on the interval [1,9] - same-valued N Parameters are associated.

#16 LogFormat Snippet
<LogFormat>
    <Name = "NAME"/>
    <Format = "FORMAT"/>
</LogFormat>

Tip

The order in which these Parameters are considered is exactly the numerical ordering implied by N (starting with it being empty).

Furthermore, for a given value of N, if a Parameter exists on the cache server’s Profile having this Config File value with the Name LogObjectN.Filename, the document fragment shown in LogObject Snippet will be inserted. In that snippet, OBJ_FORMAT is the Value of the Parameter with the Name LogObjectN.Format, FILENAME is the Value of the Parameter with the Name LogObjectN.Filename, ROLLING is the Value of the Parameter with the Name LogObjectN.RollingEnabled, INTERVAL is the Value of the Parameter with the Name LogObjectN.RollingIntervalSec, OFFSET is the Value of the Parameter with the Name LogObjectN.RollingOffsetHr, SIZE is the Value of the Parameter with the Name LogObjectN.RollingSizeMb, and HEADER is the Value of the Parameter with the Name LogObjectN.Header - all having the same value of N, and the Config File value logs_xml.config, of course.

#17 LogObject Snippet
<LogObject>
    <Format = "OBJ_FORMAT"/>
    <Filename = "FILENAME"/>
    <RollingEnabled = ROLLING/>
    <RollingInterval = INTERVAL/>
    <RollingOffsetHr = OFFSET/>
    <RollingSizeMb = SIZE/>
    <Header = "HEADER"/>
</LogObject>

Warning

The contents of these fields are not validated by Traffic Control - handle with care!

Deprecated since version ATCv3.0: This file is only used by Apache Traffic Server version 6.x. The use of Apache Traffic Server version < 7.1 has been deprecated, and will not be supported in the future. Developers are encouraged to instead configure the logging.config configuration file.

package

This is a special, reserved Config File that isn’t a file at all. When a Parameter’s Config File is package, then its name is interpreted as the name of a package. ORT on the server using the Profile that has this Parameter will attempt to install a package by that name, interpreting the Parameter’s Value as a version string if it is not empty. The package manager used will be yum(8), regardless of system (though the Python version of ORT will attempt to use the host system’s package manager - yum(8), apt(8) and pacman are supported) but that shouldn’t be a problem because only CentOS 7 and CentOS 8 are supported.

The current implementation of ORT will expect Parameters to exist on a cache server’s Profile with the Names astats_over_http and trafficserver before being run the first time, as both of these are required for a cache server to operate within a Traffic Control CDN. It is possible to install these outside of ORT - and indeed even outside of yum(8) - but such configuration is not officially supported.

packages

This Config File is reserved, and is used by ORT to pull bulk information about all of the Parameters with Config File values of package. It doesn’t actually correspond to any configuration file.

parent.config

This configuration file is generated entirely from Cache Group relationships, as well as Delivery Service configuration. This file can be affected by Parameters on the server’s Profile if and only if its Name is one of the following:

  • algorithm

  • qstring

  • psel.qstring_handling

  • not_a_parent - unlike the other Parameters listed (which have a 1:1 correspondence with Apache Traffic Server configuration options), this Parameter affects the generation of parent relationships between cache servers. When a Parameter with this Name and Config File exists on a Profile used by a cache server, it will not be added as a parent of any other cache server, regardless of Cache Group hierarchy. Under ordinary circumstances, there’s no real reason for this Parameter to exist.

Additionally, Delivery Service Profiles can have special Parameters with the Name “mso.parent_retry” to Configure Multi-Site Origin.

See also

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

plugin.config

For each Parameter with this Config File value on the same Profile, a line in the resulting configuration file is produced in the format NAME VALUE where NAME is the Parameter’s Name with trailing characters matching the regular expression __\d+$ stripped out and VALUE is the Parameter’s Value.

Caution

In order for Parameters for Config Files relating to Apache Traffic Server plugins - e.g. regex_revalidate.config - to have any effect, a Parameter must exist with this Config File value to instruct Apache Traffic Server to load the plugin. Typically, this is more easily achieved by assigning these Parameters to The GLOBAL Profile than on a server-by-server basis.

See also

The Apache Traffic server documentation on the plugin.config configuration file explains what Value and Name a Parameter should have to be valid.

rascal.properties

This Config File is meant to be on Parameters assigned to either Traffic Monitor Profiles or cache server Profiles. Its allowed Parameter Names are all configuration options for Traffic Monitor. The Names with meaning are as follows.

See also

Health Protocol

health.polling.format

The Value of this Parameter should be the name of a parsing format supported by Traffic Monitor, used to decode statistics when polling for health and statistics. If this Parameter does not exist on a cache server’s Profile, the default format (astats) will be used. The only supported values are

For more information on Traffic Monitor plug-ins that can expand the parsed formats, refer to Extensions.

health.polling.url

The Value of this Parameter sets the URL requested when Traffic Monitor polls cache servers that have this Parameter in their Profiles. Specifically, the Value is interpreted as a template - in a format reminiscent of variable interpolation in double-quoted strings in Bash -, that offers the following substitutions:

  • ${hostname} Replaced by the IP Address of the cache server being polled, and not its (short) hostname. The IP address used will be its IPv4 service address if it has one, otherwise its IPv6 service address. IPv6 addresses are properly formatted when inserted into the template, so the template need not include “square brackets” ([ and ]) around ${hostname}s even when they anticipate they will be IPv6 addresses.

  • ${interface_name} Replaced by the name of the network interface that contains the cache server’s service address(es). For most cache servers (specifically those using the stats_over_http ATS plugin to report their health and statistics) using this in a template won’t be necessary.

If the template doesn’t include a specific port number, the cache server’s TCP port will be inserted if the URL uses the HTTP scheme, or its HTTPS Port if the cache server uses the the HTTPS scheme.

Table health.polling.url Value Examples gives some examples of templates, inputs, and outputs.

Table 48 health.polling.url Value Examples

Template

Chosen Service IP

TCP Port

HTTPS Port

Interface Name

Output

http://${hostname}/_astats?inf.name=${interface_name}

192.0.2.42

8080

8443

eth0

http://192.0.2.42:8080/_astats?inf.name=eth0

https://${hostname}/_stats

2001:DB8:0:0:1::1

8080

8443

eth0

https://[2001:DB8:0:0:1::1]/_stats

http://${hostname}:80/custom/stats/path/${interface_name}

192.0.2.42

8080

8443

eth0

http://192.0.2.42:80/custom/stats/path/eth0

health.threshold.loadavg

The Value of this Parameter sets the “load average” above which the associated Profile’s cache server will be considered “unhealthy”.

See also

The definition of a “load average” can be found in the documentation for the Linux/Unix command uptime(1).

Caution

If more than one Parameter with this Name and Config File exist on the same Profile with different Values, the actual Value used by any given Traffic Monitor instance is undefined (though it will be the Value of one of those Parameters).

health.threshold.availableBandwidthInKbps

The Value of this Parameter sets the amount of bandwidth (in kilobits per second) that Traffic Control will try to keep available on the cache server - for all network interfaces. For example a Value of “>1500000” indicates that the cache server will be marked “unhealthy” if its available remaining bandwidth across all of the network interfaces used by the caching proxy fall below 1.5Gbps.

Caution

If more than one Parameter with this Name and Config File exist on the same Profile with different Values, the actual Value used by any given Traffic Monitor instance is undefined (though it will be the Value of one of those Parameters).

history.count

The Value of this Parameter sets the maximum number of collected statistics will retain at a time. For example, if this is “30”, then Traffic Monitor will keep up to the past 30 collected statistics runs for the cache servers using the Profile that has this Parameter. The minimum history size is 1, and if this Parameter’s Value is set below that, it will be treated as though it were 1.

Caution

This must be an integer. What happens when the Value of this Parameter is not an integer is not known to this author; at a guess, in all likelihood it would be treated as though it were 1 and warnings/errors would be logged by Traffic Monitor and/or Traffic Ops. However, this is not known and setting it improperly is potentially dangerous, so please ensure it is always an integer.

records.config

For each Parameter with this Config File value on the same Profile, a line in the resulting configuration file is produced in the format NAME VALUE where NAME is the Parameter’s Name with trailing characters matching the regular expression __\d+$ stripped out and VALUE is the Parameter’s Value.

regex_remap_anything.config

Config Files matching this pattern - where anything is zero or more characters - are generated entirely from Delivery Service configuration, which cannot be affected by any Parameters (except “location”).

See also

For the syntax of configuration files for the “Regex Remap” plugin, see the Regex Remap plugin’s official documentation. For instructions on how to enable a plugin, consult, the plugin.config documentation.

regex_revalidate.config

This configuration file can only be affected by the special maxRevalDurationDays, which is discussed in the The GLOBAL Profile section.

See also

For the syntax of configuration files for the “Regex Revalidate” plugin, see the Regex Revalidate plugin’s official documentation. For instructions on how to enable a plugin, consult, the plugin.config documentation.

remap.config

This configuration file can only be affected by Parameters on a Profile assigned to a Delivery Service. Then, for every Parameter assigned to that Profile that has the Config File value “remap.config” -, a parameter will be added to the line for that Delivery Service of the form @pparam=Value where Value is the Parameter’s Value. Each argument should have its own Parameter. Repeated arguments are allowed, but a warning is issued by t3c when processing configuration for cache servers that serve content for the Delivery Service with a Profile that includes duplicate arguments.

For backwards compatibility, a special case exists for the cachekey.config Config File for Parameters on Delivery Service Profiles that can also affect this configuration file. This is of the form: pparam=--Name=Value where Name is the Parameter’s Name, and Value is its Value. A warning will be issued by t3c when processing configuration for cache servers that serve content for the Delivery Service with a Profile that uses a Parameter with the Config File cachekey.config as well as at least one with the Config File cachekey.pparam.

The following plugins have support for adding args with following parameter Config File values.

  • background_fetch.pparam Note the --config=bg_fetch.conf argument is already added to remap.config by t3c.

  • cachekey.pparam

  • cache_range_requests.pparam

  • slice.pparam Note the --blocksize=val plugin parameter is specifiable directly on Delivery Services by setting their Range Slice Request Block Size property.

  • url_sig.pparam Note the configuration file for this plugin is already added by t3c.

Deprecated since version ATCv6: cachekey.config is deprecated but available for backwards compatibility. cachekey.config Parameters will be converted by t3c to the “pparam” syntax with -- added as a prefix to the Name. Any “empty” param value (i.e. separator) will add an extra = to the key.

Table 49 Equivalent cachekey.config/cachekey.pparam entries

Name

Config File

Value

Result

remove-all-params

cachekey.config

true

@pparam=--remove-all-params=true

cachekey.pparam

remap.config

--remove-all-params=true

@pparam=--remove-all-params=true

separator

cachekey.config

(empty value)

@pparam=--separator=

cachekey.pparam

remap.config

--separator=

@pparam=--separator=

cachekey.pparam

cachekey.pparam

-o

@pparam=-o

See also

For an explanation of the syntax of this configuration file, refer to the Apache Traffic Server remap.config documentation.

set_dscp_anything.config

Configuration files matching this pattern - where anything is a string of zero or more characters is generated entirely from a “location” Parameter.

Tip

anything in that Config File name only has meaning if it is a natural number - specifically, one of each value of DSCP on every Delivery Service to which the cache server using the Profile on which the Parameter(s) exist(s).

ssl_multicert.config

This configuration file is generated from the SSL keys of Delivery Services, and is unaffected by any Parameters (except “location”)

storage.config

This configuration file can only be affected by a handful of Parameters. If a Parameter with the Name “Drive Prefix” exists the generated configuration file will have a line inserted in the format PREFIXLETTER volume=1 for each letter in the comma-delimited list that is the Value of the Parameter on the same Profile with the Name “Drive Letters”, where PREFIX is the Value of the Parameter with the Name “Drive Prefix”, and LETTER is each of the aforementioned letters in turn. Additionally, if a Parameter on the same Profile exists with the Name “RAM Drive Prefix” then for each letter in the comma-delimited list that is the Value of the Parameter on the same Profile with the Name “RAM Drive Letters”, a line will be generated in the format PREFIXLETTER volume=i where PREFIX is the Value of the Parameter with the Name “RAM Drive Prefix”, LETTER is each of the aforementioned letters in turn, and i is 1 if and only if a Parameter does not exist on the same Profile with the Name “Drive Prefix” and is 2 otherwise. Finally, if a Parameter exists on the same Profile with the Name “SSD Drive Prefix”, then a line is inserted for each letter in the comma-delimited list that is the Value of the Parameter on the same Profile with the Name “SSD Drive Letters” in the format PREFIXLETTER volume=i where PREFIX is the Value of the Parameter with the Name “SSD Drive Prefix”, LETTER is each of the aforementioned letters in turn, and i is 1 if and only if both a Parameter with the Name “Drive Prefix” and a Parameter with the Name “RAM Drive Prefix” don’t exist on the same Profile, or 2 if only one of them exists, or otherwise 3.

traffic_stats.config

This Config File value is only handled specially when the Profile to which it is assigned is of the special TRAFFIC_STATS Type. In that case, the Name of any Parameters with this Config File is restrained to one of “CacheStats” or “DsStats”. When it is “Cache Stats”, the Value is interpreted specially based on whether or not it starts with “ats.”. If it does, then what follows must be the name of one of the core Apache Traffic Server statistics. This signifies to Traffic Stats that it should store that statistic for cache servers within Traffic Control. Additionally, the special statistics “bandwidth”, “maxKbps” are supported as Names - and in fact it is suggested that they exist in every Traffic Control deployment.

When the Parameter Name is “DSStats”, the allowed Values are:

  • kbps

  • status_4xx

  • status_5xx

  • tps_2xx

  • tps_3xx

  • tps_4xx

  • tps_5xx

  • tps_total

See also

For more information on the statistics gathered by Traffic Stats, see Traffic Stats Administration. For information about how these statics are gathered, consult the only known documentation of the “astats_over_http” Apache Traffic Server plugin: traffic_server/plugins/astats_over_http/README.md.

sysctl.config

For each Parameter with this Config File value on the same Profile, a line in the resulting configuration file is produced in the format NAME = VALUE where NAME is the Parameter’s Name with trailing characters matching the regular expression __\d+$ stripped out and VALUE is the Parameter’s Value.

uri_signing_anything.config

Config Files matching this pattern - where anything is zero or more characters - are generated entirely from the URI Signing Keys configured on a Delivery Service through either the Traffic Ops API or the Delivery Services view in Traffic Portal.

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_anything.config

Config Files that match this pattern - where anything is zero or more characters - are mostly generated using the URL Signature Keys as configured either through the Traffic Ops API or the Delivery Services view in Traffic Portal. However, if no such keys have been configured, they may be provided by fall-back Parameters. In this case, for each Parameter on assigned to this Config File on the same Profile a line is inserted into the resulting configuration file in the format NAME = VALUE where NAME is the Parameter’s Name and VALUE is the Parameter’s Value.

volume.config

This Config File is peculiar in that it depends only on the existence of Parameters, and not each Parameter’s actual Value. The Parameters that affect the generated configuration file are the Parameters with the Names “Drive Prefix”, “RAM Drive Prefix”, and “SSD Drive Prefix”. Each of these Parameters must be assigned to the storage.config Config File - NOT this Config File - and, of course, be on the same Profile. The contents of the generated Config File will be between zero and three lines (excluding headers) where the number of lines is equal to the number of the aforementioned Parameters that actually exist on the same Profile. Each line has the format volume=i scheme=http size=SIZE% where i is a natural number that ranges from 1 to the number of those Parameters that exist. SIZE is \(100 / N\) - where \(N\) is the number of those special Parameters that exist - truncated to the nearest natural number, e.g. \(100 / 3 = 33\).

ID

An integral, unique identifier for a Parameter. Note that Parameters must have a unique combination of Config File, Name, and Value, and so those should be used for identifying a unique Parameter whenever possible.

Implementation Detail

If two Profiles have been assigned Parameters that have the same values for Config File, Name, and Value then Traffic Ops actually only stores one Parameter object and merely links it to both Profiles. This can be seen by inspecting the Parameters’ IDs, as they will be the same. There are many cases where a user or developer must rely on this implementation detail, but both are encouraged to do so only when absolutely necessary.

Name

The Name of a Parameter has different meanings depending on the type of any and all Profiles to which it is assigned, as well as the Config File to which the Parameter belongs, but most generally it is used in Apache Traffic Server configuration files as the name of a configuration option in a name/value pair. Traffic Ops interprets the Name and Value of a Parameter in intelligent ways depending on the type of object to which the Profile using the Parameter is assigned. For example, if Config File is records.config and the Parameter’s Profile is assigned to a cache server, then a single line is placed in the configuration file specified by Config File, and that line will have the contents Name Value. However, if the Config File of the Parameter is something without special meaning to Traffic Ops e.g. “foo”, then a line containing only the Parameter’s Value would be inserted into that file (presuming it also has a Parameter with a Name of “location” and a Config File of “foo”). Additionally, there are a few Names that are treated specially by Traffic Control.

location

The Value of this Parameter is to be interpreted as a path under which the configuration file specified by Config File shall be found (or written, if not found). Any configuration file that is to exist on a server must have an associated “location” Parameter, even if the contents of the file cannot be affected by Parameters.

Caution

If a single Profile has multiple “location” Parameters for the same Config File with different Values, the actual location of the generated configuration file is undefined (but will be one of those Parameters’ Values).

header

If the Profile containing this Parameter is assigned to a server, and if the Config File is not one of the special values that Traffic Ops uses to determine special syntax formatting, then the Value of this Parameter will be used instead of the typical Traffic Ops header - unless it is the special string “none”, in which case no header will be inserted at all.

Caution

If a single Profile has multiple “header” Parameters for the same Config File with different Values, the actual header is undefined (but will be one of those Parameters’ Values).

refetch_enabled

When a Parameter by this Name exists, and has the Config File value of exactly “global”, then its Value may be used by Traffic Ops to decide whether or not the “REFETCH” Invalidation Type of Content Invalidation Jobs are allowed to be created. The Value “true” (case-insensitive) indicates that such Content Invalidation Jobs should be allowed, while all other Values indicate they should not.

Note

Any leading or trailing whitespace in the Value of these Parameters is ignored.

Caution

There is no limit to the number of these Parameters that may exist, and no association to any existing Profiles is considered when choosing which Parameter to use. If more than one Parameter with the Name refetch_enabled exists with the Config File “global”, then the actual Value used to determine if “REFETCH” Invalidation Type of Content Invalidation Jobs are allowed to be created is undefined (but will be the Value of one of said Parameters). In particular, there is no special handling when any of these Parameters is assigned to The GLOBAL Profile, and being thusly assigned in no way means that the assigned Parameter will have any kind of priority over others that collide with it in Name and Config File.

Secure

When this is ‘true’, a user requesting to see this Parameter will see the value ******** instead of its actual value if the user’s permission Role isn’t ‘admin’.

Value

In general, a Parameter’s Value can be anything, and in the vast majority of cases the Value is in no way validated by Traffic Control. Usually, though, the Value has a special meaning depending on the values of the Parameter’s Config File and/or Name.

1

The contents of this file are not valid XML, but are rather XML-like so developers writing procedures that will consume and parse it should be aware of this, and note the actual syntax as specified in the Apache Traffic Server documentation for logs_xml.config

2(1,2)

This Value may safely contain double quotes (") as they will be backslash-escaped in the generated output.

3

This Value may safely contain backslashes (\) and single quotes ('), as they will be backslash-escaped in the generated output.