NAME

       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(). TSDebug()

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

SEE ALSO

       TSPluginInit(3ts)

COPYRIGHT

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                                        TSAPI(3ts)