TSAPI

Introduction to the Apache Traffic Server API.

Synopsis

#include <ts/ts.h>
#include <ts/remap.h>

Description

The Apache Traffic Server API enables you to create plugins, using the C programming language, that customize the behavior of your Traffic Server installation.

Traffic Server enables sophisticated caching and processing of web-related traffic, such as DNS and HTTP requests and responses. Traffic Server itself consists of an event-driven loop that can be simplified as follows:

for (;;) {
    event = get_next_event();
    handle_event (event);
}

You compile your plugin source code to create a shared library that Traffic Server loads when it is started. Your plugin contains callback functions that are registered for specific Traffic Server events. When Traffic Server needs to process an event, it invokes any and all call-back functions you’ve registered for that event type.

Possible uses for plugins include the following:

  • HTTP processing plugins can filter, denylist, authorize users or transform content.

  • Protocol plugins can enable Traffic Server to proxy-cache new protocol content.

  • A denylisting plugin denies attempts to access web sites that are off-limits.

  • Append transform plugins add data to HTTP response content.

  • An image conversion plugin transforms JPEG images to GIF images.

  • Compression plugins send response content to a compression server that compresses the data (alternatively, a compression library local to the Traffic Server host machine could do the compression).

  • Authorization plugins check a user’s permissions to access particular web sites. The plugin could consult a local authorization program or send queries to an authorization server.

  • A plugin that gathers client information from request headers and enters this information in a database.

  • A protocol plugin listen for specific protocol requests on a designated port and then uses Traffic Server’s proxy server and cache to serve client requests.

Naming Conventions

The Traffic Server API adheres to the following naming conventions:

  • The TS prefix is used for all function and variable names defined in the Traffic Server API. For example, TS_EVENT_NONE, TSMutex, and TSContCreate().

  • Enumerated values are always written in all uppercase letters. For example, TS_EVENT_NONE and TS_VC_CLOSE_ABORT.

  • Constant values are all uppercase; enumerated values can be seen as a subset of constants. For example, TS_URL_SCHEME_FILE and TS_MIME_FIELD_ACCEPT.

  • The names of defined types are mixed-case. For example, TSHttpSsn and TSHttpTxn. TSContCreate()

  • Function names are mixed-case. For example, TSUrlCreate() and TSContDestroy().

  • Function names use the following subject-verb naming style: TS-<subject>-<verb>, where <subject> goes from general to specific. This makes it easier to determine what a function does by reading its name. For example, the function to retrieve the password field (the specific subject) from a URL (the general subject) is TSUrlPasswordGet().

  • Common verbs like Create, Destroy, Get, Set, Copy, Find, Retrieve, Insert, Remove, and Delete are used only when appropriate.

Plugin Loading and Configuration

When Traffic Server is first started, it consults the plugin.config file to determine the names of all shared plugin libraries that need to be loaded. The plugin.config file also defines arguments that are to be passed to each plugin’s initialization function, TSPluginInit(). The records.yaml file defines the path to each plugin shared library.

The sample plugin.config file below contains a comment line, a blank line, and two plugin configurations:

# This is a comment line.
my-plugin.so www.junk.com www.trash.com www.garbage.com
some-plugin.so arg1 arg2 $proxy.config.http.cache.on

Each plugin configuration in the plugin.config file resembles a UNIX or DOS shell command; each line in plugin.config cannot exceed 1023 characters.

The first plugin configuration is for a plugin named my-plugin.so. It contains three arguments that are to be passed to that plugin’s initialization routine. The second configuration is for a plugin named some-plugin.so; it contains three arguments. The last argument, $proxy.config.http.cache.on, is actually a configuration variable. Traffic Server will look up the specified configuration variable and substitute its value.

Plugins are loaded and initialized by Traffic Server in the order they appear in the plugin.config file.

Plugin Initialization

Each plugin must define an initialization function named TSPluginInit() that Traffic Server invokes when the plugin is loaded. TSPluginInit() is commonly used to read configuration information and register hooks for event notification.

Files

plugin.config, records.yaml

See Also

TSPluginInit(3ts)