Apache Traffic Server

Traffic Server is a high-performance building block for cloud services. It's more than just a caching proxy server; it also has support for plugins to build large scale web applications.

Important notice to ATS developers

AS of version 10, ATS has transitioned to cmake as its build system. Below is a quick-start guide to building ATS with cmake:

Step 1: Configuration

With cmake, you definitely want to create an out-of-source build. You will give that directory to every cmake command. For these examples, it will just be build.

$ cmake -B build

This will configure the project with defaults.

If you want to customize the build, you can pass values for variables on the command line. Or, you can interactively change them using the ccmake program.

$ cmake -B build -DCMAKE_INSTALL_PREFIX=/tmp/ats -DBUILD_EXPERIMENTAL_PLUGINS=ON

-- or --

$ ccmake build

Specifying locations of dependencies

To specify the location of a dependency (like --with-* for autotools builds), you generally set a variable with the ROOT. The big exception to this is for openssl. This variable is called OPENSSL_ROOT_DIR

$ cmake -B build -Djemalloc_ROOT=/opt/jemalloc -DOPENSSL_ROOT_DIR=/opt/boringssl

Using presets to configure the build

cmake has a feature for grouping configurations together to make configuration and reproduction easier. The file CMakePresets.json declares presets that you can use from the command line. You can provide your own CMakeUserPresets.json and further refine those via inheritance:

$ cmake --preset dev

You can start out your user presets by just copying CMakePresets.json and removing everything in configurePresets

Here is an example user preset:

    {
      "name": "clang",
      "hidden": true,
      "environment": {
        "LDFLAGS": "-L/opt/homebrew/opt/llvm/lib -L/opt/homebrew/opt/llvm/lib/c++ -Wl,-rpath,/opt/homebrew/opt/llvm/lib/c++ -fuse-ld=/opt/homebrew/opt/llvm/bin/ld64.lld",
        "CPPFLAGS": "-I/opt/homebrew/opt/llvm/include",
        "CXXFLAGS": "-stdlib=libc++",
        "CC": "/opt/homebrew/opt/llvm/bin/clang",
        "CXX": "/opt/homebrew/opt/llvm/bin/clang++"
      }
    },
    {
      "name": "mydev",
      "displayName": "my development",
      "description": "My Development Presets",
      "binaryDir": "${sourceDir}/build-dev-clang",
      "inherits": ["clang", "dev"],
      "cacheVariables": {
        "CMAKE_INSTALL_PREFIX": "/opt/ats-cmake",
        "jemalloc_ROOT": "/opt/homebrew",
        "ENABLE_LUAJIT": false,
        "ENABLE_JEMALLOC": true,
        "ENABLE_MIMALLOC": false,
        "ENABLE_MALLOC_ALLOCATOR": true,
        "BUILD_EXPERIMENTAL_PLUGINS": true,
        "BUILD_REGRESSION_TESTING": true
      }
    },

And then use it like:

cmake --preset mydev

Building the project

$ cmake --build build

$ cmake --build build -t traffic_server

running tests

$ cd build
$ ctest

installing

$ cmake --install build

DIRECTORY STRUCTURE

trafficserver ............. Top src dir
├── ci .................... Quality assurance and other CI tools and configs
├── cmake ................. CMake build system files
├── configs ............... Configurations
├── contrib ............... Various contributed auxiliary pieces
├── doc ................... Documentation for Traffic Server
│   ├── admin-guide ....... Admin guide documentations
│   ├── appendices ........ Appendices of Traffic Server
│   ├── developer-guide ... Documentation for developers
│   ├── dot ............... Graphviz source files for docs pictures
│   ├── static ............ Static resources
│   └── uml ............... Documentation in UML
├── example ............... Example plugins
├── ext ................... External dependencies and extensions
├── include ............... Header files
├── lib ................... Third-party libraries
│   ├── Catch2 ............ Unit testing framework
│   ├── fastlz ............ Fast compression library
│   ├── ls-hpack .......... HPACK compression for HTTP/2
│   ├── swoc .............. Solid Wall of Code utility library
│   ├── systemtap ......... SystemTap integration
│   └── yamlcpp ........... YAML parser library
├── memory-bank ........... AI assistant context documentation
├── plugins ............... Stable core plugins
│   └── experimental ...... Experimental core plugins
├── rc .................... Installation programs and scripts
├── src ................... Source for all the main binaries / applications
│   ├── api ............... C Plugin API implementation
│   ├── cripts ............ Cripts scripting framework
│   ├── iocore ............ I/O core subsystem
│   │   ├── aio ........... Asynchronous I/O core
│   │   ├── cache ......... Disk and RAM cache
│   │   ├── dns ........... DNS (asynchronous)
│   │   ├── eventsystem ... Event Driven Engine
│   │   ├── hostdb ........ Internal DNS cache
│   │   ├── io_uring ...... io_uring support (Linux)
│   │   ├── net ........... Network I/O
│   │   │   └── quic ...... QUIC implementation
│   │   └── utils ......... I/O utilities
│   ├── mgmt .............. JSONRPC server/management and tools
│   ├── proxy ............. HTTP proxy logic
│   │   ├── hdrs .......... Headers parsing and management
│   │   ├── http .......... HTTP/1.x implementation
│   │   ├── http2 ......... HTTP/2 implementation
│   │   ├── http3 ......... HTTP/3 implementation
│   │   ├── logging ....... Flexible logging
│   │   └── shared ........ Shared proxy files
│   ├── records ........... Configuration records library
│   ├── shared ............ Shared utilities and RPC
│   ├── traffic_cache_tool  Tool to interact with the Traffic Server cache
│   ├── traffic_crashlog .. Helper process that catches Traffic Server crashes
│   ├── traffic_ctl ....... Command line management tool
│   ├── traffic_layout .... Display information on the build and runtime directory structure
│   ├── traffic_logcat .... Convert binary log file to plain text
│   ├── traffic_logstats .. Log parsing and metrics calculation utility
│   ├── traffic_quic ...... QUIC client tool
│   ├── traffic_server .... Main proxy server
│   ├── traffic_top ....... Top like tool for viewing Traffic Server statistics
│   ├── traffic_via ....... Tool for decoding the Traffic Server Via header codes
│   ├── tscore ............ Base / core library
│   ├── tscpp ............. C++ api wrapper for plugin developers
│   └── tsutil ............ Core utilities (metrics, debugging, regex, etc.)
├── tests ................. Different tests for Traffic Server
├── tools ................. Directory of various tools
├── CONTRIBUTING.md ....... How to contribute to the project
├── INSTALL ............... Build and installation guide
├── LICENSE ............... Full license text
├── NOTICE ................ Copyright notices
├── README.md ............. This file: intro, links, build info
├── README-EC2 ............ Info on EC2 support
├── SECURITY.md ........... Security policy and vulnerability reporting
└── STATUS ................ Release history and information

REQUIREMENTS

This section outlines build requirements for different OS distributions. This may be out of date compared to the on-line requirements at

https://cwiki.apache.org/confluence/display/TS/Building.

As of ATS v9.0.0 and later, gcc 7 or later is required, since we now use and require the C++17 standard.

Fedora / CentOS / RHEL:

cmake
ninja
pkgconfig
gcc/g++ or clang/clang++
opens