Traffic Server Administration

Installing Traffic Server

  1. Build the Traffic Server RPM. The best way to do this is to follow the Apache Traffic Server documentation.

  2. Build the astats RPM using the appropriate version number - ours are built here

    Note

    The astats plugin is bundled as a part of Apache Traffic Server as of version 7.2.

  3. Install Traffic Server and astats

    #62 Apache Traffic Server Installation Using yum(8)
    yum -y install trafficserver-*.rpm astats_over_http*.rpm

  4. Add the server using the Traffic Portal UI:

    1. Go to Configure ‣ Servers

    2. Click on the + button at the top of the page.

    3. Complete the form. Be sure to fill out all fields marked ‘Required’

      • Set ‘Interface Name’ to the name of the network interface device from which Apache Traffic Server delivers content.

      • Set ‘Type’ to ‘MID’ or ‘EDGE’.

      • If you wish for the server to immediately be polled by the Health Protocol, set ‘Status’ to ‘REPORTED’.

    4. Click on the Create button to submit the form.

    5. Verify that the server status is now listed as Reported

  5. Install the t3c script and run it in ‘badass’ mode to create the initial configuration

  6. Start ATS

    #63 Starting ATS with systemd(1)
    systemctl start trafficserver

  7. (Optional) Configure ATS to start automatically when the system powers on

    #64 Configuring ATS to Start Automatically Using systemd(1)
    systemctl enable trafficserver

  8. Verify that the installation is working

    1. Make sure that the service is running

      #65 Checking that ATS is Running Using systemd(1)
      systemctl status trafficserver

    2. Assuming a Traffic Monitor is already installed somewhere, check the “Cache States” table in its Web UI to verify that the ATS server appears.

Configuring Traffic Server

All of the ATS application configuration files are generated by Traffic Ops and installed by t3c. The t3c file should be installed on all cache servers (See Installing the Cache Config Tool), usually in /opt/ort. It is used to do the initial install of the configuration files when the cache server is being deployed, and to keep the configuration files up-to-date when the cache server is already in service.

Cache Config File Generation

In the past, ATS config files were generated by Traffic Ops. Cache config generation is now performed on cache servers themselves, via a library for generic use, and an application which uses the library and resides on the cache server. That application, t3c, is in the process of being rewritten as many small POSIX-style applications which will behave similar to the git ecosystem.

The library, lib/go-atscfg, allows users to write their own applications and servers, if they wish to generate ATS configuration files and deploy them to caches via other means. For example, if you wish to generate config files with an additional service, or continue generating config files on Traffic Ops itself via a plugin or local service.

The app atstccfg is installed by the cache config RPM alongside t3c. This app is a helper to t3c and does not have a stable interface, and should never need to be called directly by Traffic Control administrators.

The cache-side config generation provides several benefits. Primarily, it reduces the overhead and risk of the monolithic Traffic Ops installation and upgrade process, and allows operators to canary-test config changes one cache at a time, and in the event of an error, only rolling back a few canary caches rather than the entire Traffic Ops instance.

Installing the Cache Config Tool

  1. Build the RPM by following the instructions in Building Traffic Control and install it with rpm(8) or yum(8).

  2. Install modules required by the RPM if needed

  3. For initial configuration or when major changes (like a Profile change) need to be made, run the script in “badass” mode. All required RPM packages will be installed, all ATS configuration files will be fetched and installed, and (if needed) the ATS service will be restarted.

    Note

    The first run gives a lot of state errors that are expected. The “badass” mode fixes these issues. If you run it a second time, this should be cleaner. Also, note that many “ERROR” messages emitted by t3c are actually information messages. Do not panic. We are in the process of converting legacy “ERROR” messages to informational logs.

  4. Create a cron(8) entry for running t3c in “syncds” mode every 15 minutes. This makes Traffic Control check periodically if the server has updates pending, and if so get the updated configuration.

    Note

    By default, running t3c on an Edge-tier cache server will cause it to first wait for its parents (usually Mid-tier cache server s) to download their configuration before downloading its own configuration. Because of this, scheduling t3c for running every 15 minutes (with 5 minutes default dispersion) means that it might take up to ~35 minutes for queued updates to affect all cache server s. To customize this dispersion time, use the command line option --dispersion=x where x is the number of seconds for the dispersion period. Servers will select a random number from within this dispersion period to being downloading configuration files from Traffic Ops. Another option, --login_dispersion=x can be used to create a dispersion period after the job begins during which t3c will wait before logging in and checking Traffic Ops for updates to the server. This defaults to 0. If use_reval_pending, a.k.a. “Rapid Revalidate” is enabled, Edge-tier cache servers will not wait for their parents to download their configuration before downloading their own.

    Note

    In “syncds” mode, the t3c app updates only configurations that might be changed as part of normal operations, such as:

    • Delivery Services

    • SSL certificates

    • Traffic Monitor IP addresses

    • Logging configuration

    • Revalidation requests (By default - if “Rapid Revalidate” is enabled, this will only be checked by using a separate revalidate command in t3c)

  5. If “Rapid Revalidate” is enabled in Traffic Ops, create a second cron(8) job for revalidation checks by running t3c in “revalidate” mode. t3c will not check revalidation files if “Rapid Revalidate” is enabled. This setting allows for a separate check to be performed every 60 seconds to verify if a revalidation update has been made.

Strings with Special Meaning to t3c

When processing configuration files, if traffic_ops_ort encounters any of the strings in the Replacement Strings table it will perform the indicated replacement. This means that these strings can be used to create templates in Profile Parameters and certain Delivery Service configuration fields.

Table 72 Replacement Strings

String

Replaced With

__CACHE_IPV4__

The IPv4 address of the cache server on which t3c is running.

__FULL_HOSTNAME__

The full hostname (i.e. including the full domain to which it belongs) of the cache server on which t3c is running.

__HOSTNAME__

The (short) hostname of the cache server on which t3c is running.

__RETURN__

A newline character (\\n).

__SERVER_TCP_PORT__

If the cache server on which t3c is being run has a TCP port configured to something besides 80, this will be replaced with that TCP port value. If it is set to 80, this string will simply be removed, NOT replaced with ANYTHING.

##OVERRIDE##

This string is only valid in the content of files named “remap.config”. It is further described in Remap Override

Deprecated since version ATCv4.0: The use of __RETURN__ in lieu of a true newline character is (finally) no longer necessary, and the ability to do so will be removed in the future.

Note

There is currently no way to indicate that a server’s IPv6 address should be inserted - only IPv4 is supported.

Remap Override

Warning

The ANY_MAP ##OVERRIDE## special string is a temporary solution and will be deprecated once Delivery Service Versioning is implemented. For this reason it is suggested that it not be used unless absolutely necessary.

The ##OVERRIDE## template string allows the Delivery Service Raw Remap Text field to override to fully override the Delivery Service’s line in the remap.config ATS configuration file, generated by Traffic Ops. The end result is the original, generated line commented out, prepended with ##OVERRIDDEN## and the ##OVERRIDE## rule is activated in its place. This behavior is used to incrementally deploy plugins used in this configuration file. Normally, this entails cloning the Delivery Service that will have the plugin, ensuring it is assigned to a subset of the cache servers that serve the Delivery Service content, then using this ##OVERRIDE## rule to create a remap.config rule that will use the plugin, overriding the normal rule. Simply grow the subset over time at the desired rate to slowly deploy the plugin. When it encompasses all cache servers that serve the original Delivery Service’s content, the “override Delivery Service” can be deleted and the original can use a non-##OVERRIDE## Raw Remap Text to add the plugin.

#66 Example of Remap Override
# This is the original line as generated by Traffic Ops
map http://from.example.com/ http://to.example.com/

# This is the raw remap text as configured on the delivery service
##OVERRIDE## map http://from.example.com/ http://to.example.com/ some_plugin.so

# The resulting content is what actually winds up in the remap.config file:
##OVERRIDE##
map http://from.example.com/ http://to.example.com/ some_plugin.so
##OVERRIDDEN## map http://from.example.com/ http://to.example.com/

Warning

The “from” URL must exactly match for this to properly work (e.g. including trailing URL ‘/’), otherwise ATS may fail to initialize or reload while processing remap.config.

Tip

To assist in troubleshooting, it is strongly recommended that any ##OVERRIDE## rules in use should be documented on the original Delivery Service.