plucky (3) TSAPI.3ts.gz

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