.. .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. .. You may obtain a copy of the License at .. .. http://www.apache.org/licenses/LICENSE-2.0 .. .. Unless required by applicable law or agreed to in writing, software .. distributed under the License is distributed on an "AS IS" BASIS, .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. .. See the License for the specific language governing permissions and .. limitations under the License. .. ***************************** Traffic Server Administration ***************************** Installing Traffic Server ========================= #. Build the Traffic Server RPM. The best way to do this is to follow the `Apache Traffic Server documentation `_. #. 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. #. Install Traffic Server and astats .. code-block:: bash :caption: Apache Traffic Server Installation Using :manpage:`yum(8)` yum -y install trafficserver-*.rpm astats_over_http*.rpm #. Add the server using the Traffic Portal UI: #. Go to :menuselection:`Configure --> Servers` #. Click on the :guilabel:`+` button at the top of the page. #. 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 :ref:`health-proto`, set 'Status' to 'REPORTED'. #. Click on the :guilabel:`Create` button to submit the form. #. Verify that the server status is now listed as **Reported** #. Install the :term:`t3c` script and run it in 'badass' mode to create the initial configuration .. seealso:: `Configuring Traffic Server`_ #. Start :abbr:`ATS (Apache Traffic Server)` .. code-block:: bash :caption: Starting :abbr:`ATS (Apache Traffic Server)` with :manpage:`systemd(1)` systemctl start trafficserver #. (Optional) Configure :abbr:`ATS (Apache Traffic Server)` to start automatically when the system powers on .. code-block:: bash :caption: Configuring :abbr:`ATS (Apache Traffic Server)` to Start Automatically Using :manpage:`systemd(1)` systemctl enable trafficserver #. Verify that the installation is working #. Make sure that the service is running .. code-block:: bash :caption: Checking that :abbr:`ATS (Apache Traffic Server)` is Running Using :manpage:`systemd(1)` systemctl status trafficserver #. Assuming a Traffic Monitor is already installed somewhere, check the "Cache States" table in its Web UI to verify that the :abbr:`ATS (Apache Traffic Server)` server appears. Configuring Traffic Server ========================== All of the :abbr:`ATS (Apache Traffic Server)` application configuration files are generated by Traffic Ops and installed by :term:`t3c`. The :file:`t3c` file should be installed on all :term:`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 :term:`cache server` is being deployed, and to keep the configuration files up-to-date when the :term:`cache server` is already in service. .. _config-generation: 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-t3c: Installing the Cache Config Tool -------------------------------- #. Build the RPM by following the instructions in :ref:`dev-building` and install it with :manpage:`rpm(8)` or :manpage:`yum(8)`. #. Install modules required by the RPM if needed #. For initial configuration or when major changes (like a :term:`Profile` change) need to be made, run the script in "badass" mode. All required RPM packages will be installed, all :abbr:`ATS (Apache Traffic Server)` configuration files will be fetched and installed, and (if needed) the :abbr:`ATS (Apache Traffic Server)` 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 :term:`t3c` are actually information messages. Do not panic. We are in the process of converting legacy "ERROR" messages to informational logs. #. Create a :manpage:`cron(8)` entry for running :term:`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 :term:`t3c` on an Edge-tier :term:`cache server` will cause it to first wait for its parents (usually Mid-tier :term:`cache server` s) to download their configuration before downloading its own configuration. Because of this, scheduling :term:`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 :term:`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 :term:`cache servers` will **not** wait for their parents to download their configuration before downloading their own. .. Note:: In "syncds" mode, the :term:`t3c` app updates only configurations that might be changed as part of normal operations, such as: * :term:`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 :term:`t3c`) #. If "Rapid Revalidate" is enabled in Traffic Ops, create a second :manpage:`cron(8)` job for revalidation checks by running :term:`t3c` in "revalidate" mode. :term:`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. .. _t3c-special-strings: Strings with Special Meaning to ``t3c`` """"""""""""""""""""""""""""""""""""""" When processing configuration files, if ``traffic_ops_ort`` encounters any of the strings in the :ref:`Replacement Strings ` table it will perform the indicated replacement. This means that these strings can be used to create templates in :term:`Profile` :term:`Parameters` and certain :term:`Delivery Service` configuration fields. .. _t3c-replacement-strings: .. table:: Replacement Strings +-------------------------+--------------------------------------------------------------------+ | String | Replaced With | +=========================+====================================================================+ | ``__CACHE_IPV4__`` | The IPv4 address of the :term:`cache server` on which ``t3c`` is | | | running. | +-------------------------+--------------------------------------------------------------------+ | ``__FULL_HOSTNAME__`` | The full hostname (i.e. including the full domain to which it | | | belongs) of the :term:`cache server` on which ``t3c`` is running. | +-------------------------+--------------------------------------------------------------------+ | ``__HOSTNAME__`` | The (short) hostname of the :term:`cache server` on which ``t3c`` | | | is running. | +-------------------------+--------------------------------------------------------------------+ | ``__RETURN__`` | A newline character (``\\n``). | +-------------------------+--------------------------------------------------------------------+ | ``__SERVER_TCP_PORT__`` | If the :term:`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:: 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. .. _t3c-remap-override: 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 :term:`Delivery Service` :ref:`ds-raw-remap` field to override to fully override the :term:`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 :term:`Delivery Service` that will have the plugin, ensuring it is assigned to a subset of the :term:`cache servers` that serve the :term:`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 :term:`cache servers` that serve the original :term:`Delivery Service`'s content, the "override :term:`Delivery Service`" can be deleted and the original can use a non-``##OVERRIDE##`` :ref:`ds-raw-remap` to add the plugin. .. code-block:: text :caption: 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 :abbr:`ATS (Apache Traffic Server)` may fail to initialize or reload while processing :file:`remap.config`. .. tip:: To assist in troubleshooting, it is strongly recommended that any ``##OVERRIDE##`` rules in use should be documented on the original :term:`Delivery Service`.