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