Home

Traffic Server Software Developers Kit

Preface — Next

Traffic Server Software Developers Kit

Programmers Guide

In progress

Abstract

The Traffic Server Software Developers Kit shows you how to create plugins using the Traffic Server SDK.

This documentation is a work in progress. It was originally written for a previous, commercially-available version of Traffic Server that supported different operating systems and more functions than the current version. As a result, some of the sections may refer to functionality that no longer exists.

Table of Contents

Preface
Audience
How to Use This Book
Typographical Conventions
1. Getting Started
Understanding Traffic Server Plugins
The Role of Plugins
Possible Uses for Plugins
Plugin Loading
Plugin Configuration
Configuration File Rules
Plugin Initialization
A Simple Plugin
Compile Your Plugin
Unix Example
HPUX Example
Compiling for Windows NT
Update the plugin.config File
Specify the Plugin’s Location
Restart Traffic Server
Plugin Registration and Version Checking
Naming Conventions
2. How to Create Traffic Server Plugins
The Asynchronous Event Model
Traffic Server HTTP State Machine
HTTP Transaction
Types of Hooks
Roadmap for Creating Plugins
Index
3. Remap Plugin
Why Use a Remap Plugin?
Remap.API.h
Functions You Need to Implement
Examples
4. Header-Based Plugin Examples
Overview
The Blacklist Plugin
Creating the Parent Continuation
Setting a Global Hook
Setting Up UI Update Callbacks
Accessing the Transaction Being Processed
Setting Up a Transaction Hook
Working with HTTP Header Functions
The Basic Authorization Plugin
Creating the Plugin's Parent Continuation and Global Hook
Implementing the Handler and Getting a Handle to the Transaction
Working With HTTP Headers
Setting a Transaction Hook
5. HTTP Transformation Plugins
Writing Content Transform Plugins
Transformations
VIOs
IO Buffers
The Sample Null Transform Plugin
The Append-Transform Plugin
The Sample Buffered Null Transform Plugin
6. New Protocol Plugins
About the Sample Protocol
Protocol Plugin Structure
Continuations in the Protocol Plugin
Event Flow
One Way to Implement a Transaction State Machine
Processing a Typical Transaction
7. Cache Plugin
Getting Started
Reads and Writes
State Diagram
Sample Plugin
Cache Events
8. HTTP Hooks and Transactions
The Set of Hooks
Adding Hooks
HTTP Sessions
HTTP Transactions
Intercepting HTTP Transactions
Initiate HTTP Connection
HTTP Alternate Selection
9. Miscellaneous Interface Guide
Debugging Functions
The INKfopen Family
Memory Allocation
Thread Functions
10. HTTP Headers
About HTTP Headers
Guide to Traffic Server HTTP Header System
No Null-Terminated Strings
Duplicate MIME Fields Are Not Coalesced
MIME Fields Always Belong to an Associated MIME Header
Release Marshal Buffer Handles
Deprecated Functions
Marshal Buffers
HTTP Headers
URLs
MIME Headers
11. Mutex Guide
Mutexes
Locking Global Data
Protecting a Continuation’s Data
How to Associate a Continuation to Every HTTP Transaction
How to Add the New Continuation
How to Store Data Specific to Each HTTP Transaction
Using Locks
Special Case: Continuations Created for HTTP Transactions
12. Continuations
Mutexes and Data
How to Activate Continuations
Writing Handler Functions
13. Plugin Configurations
Plugin Configurations
14. Actions Guide
Actions
Hosts Lookup API
15. IO Guide
Vconnections
The vconnection user’s view
Net Vconnections
Transformations
The Vconnection Implementor’s View
Transformation VConnection
VIOs
IO Buffers
Guide to the Cache API
How to Do a Cache Read
How to Do a Cache Write
How to Do a Cache Remove
Errors
Example
16. Plugin Management
Setting Up a Plugin Management Interface
Reading Traffic Server Settings and Statistics
Accessing Installed Plugin Files
Licensing Your Plugin
Format of plugin.db
Setting Up Licensing
Example
Generating a License Key
Guide to the Logging API
17. Adding Statistics
Uncoupled Statistics
Coupled Statistics
Example Using the redirect-1.c Sample Plugin
Viewing Statistics Using Traffic Line
18. Function Reference
List of Function Groups
Initialization Functions
INKPluginInit
INKPluginRegister
INKTrafficServerVersionGet
Debugging Functions
INKDebug
INKIsDebugTagSet
INKError
INKAssert
INKReleaseAssert
The INKfopen Family
INKfclose
INKfflush
INKfgets
INKfopen
INKfread
INKfwrite
Memory Allocation
INKfree
INKmalloc
INKrealloc
INKstrdup
INKstrndup
Thread Functions
INKThreadCreate
INKThreadDestroy
INKThreadInit
INKThreadSelf
HTTP Functions
Hook Functions
INKHttpHookAdd
Session Functions
INKHttpSsnHookAdd
INKHttpSsnReenable
HTTP Transaction Functions
INKHttpTxnCacheLookupStatusGet
INKHttpTxnCachedReqGet
INKHttpTxnCachedRespGet
INKHttpTxnClientIncomingPortGet
INKHttpTxnClientIPGet
INKHttpTxnClientRemotePortGet
INKHttpTxnClientReqGet
INKHttpTxnClientRespGet
INKHttpTxnErrorBodySet
INKHttpTxnHookAdd
INKHttpTxnNextHopIPGet
INKHttpTxnParentProxyGet
INKHttpTxnParentProxySet
INKHttpTxnReenable
INKHttpTxnServerIPGet
INKHttpTxnServerReqGet
INKHttpTxnServerRespGet
INKHttpTxnSsnGet
INKHttpTxnTransformedRespCache
INKHttpTxnTransformRespGet
INKHttpTxnUntransformedRespCache
Initiate Connection
INKHttpConnect
Intercepting HTTP Transaction Functions
INKHttpTxnIntercept
INKHttpTxnServerIntercept
Alternate Selection Functions
INKHttpAltInfoCachedReqGet
INKHttpAltInfoCachedRespGet
INKHttpAltInfoClientReqGet
INKHttpAltInfoQualitySet
Handle Release Functions
INKHandleMLocRelease
INKHandleStringRelease
Marshal Buffers
INKMBufferCreate
INKMBufferDestroy
HTTP Header Functions
INKHttpHdrClone
INKHttpHdrCopy
INKHttpHdrCreate
INKHttpHdrDestroy
INKHttpHdrLengthGet
INKHttpHdrMethodGet
INKHttpHdrMethodSet
INKHttpHdrPrint
INKHttpHdrReasonGet
INKHttpHdrReasonLookup
INKHttpHdrReasonSet
INKHttpHdrStatusGet
INKHttpHdrStatusSet
INKHttpHdrTypeGet
INKHttpHdrTypeSet
INKHttpHdrUrlGet
INKHttpHdrUrlSet
INKHttpHdrVersionGet
INKHttpHdrVersionSet
INKHttpParserClear
INKHttpParserCreate
INKHttpParserDestroy
INKHttpHdrParseReq
INKHttpHdrParseResp
URL Functions
INKUrlClone
INKUrlCopy
INKUrlCreate
INKUrlDestroy
INKUrlPrint
INKUrlFtpTypeGet
INKUrlFtpTypeSet
INKUrlHostGet
INKUrlHostSet
INKUrlHttpFragmentGet
INKUrlHttpFragmentSet
INKUrlHttpParamsGet
INKUrlHttpParamsSet
INKUrlHttpQueryGet
INKUrlHttpQuerySet
INKUrlLengthGet
INKUrlParse
INKUrlPasswordGet
INKUrlPasswordSet
INKUrlPathGet
INKUrlPathSet
INKUrlPortGet
INKUrlPortSet
INKUrlSchemeGet
INKUrlSchemeSet
INKUrlStringGet
INKUrlUserGet
INKUrlUserSet
MIIME Headers
INKMimeHdrFieldAppend
INKMimeHdrFieldClone
INKMimeHdrFieldCopy
INKMimeHdrFieldCopyValues
INKMimeHdrFieldCreate
INKMimeHdrFieldDestroy
INKMimeHdrFieldLengthGet
INKMimeHdrFieldNameGet
INKMimeHdrFieldNameSet
INKMimeHdrFieldNext
INKMimeHdrFieldNextDup
INKMimeHdrFieldValueAppend
INKMimeHdrFieldValueDateGet
INKMimeHdrFieldValueDateInsert
INKMimeHdrFieldValueDateSet
INKMimeHdrFieldValueDelete
INKMimeHdrFieldValueIntGet
INKMimeHdrFieldValueIntInsert
INKMimeHdrFieldValueIntSet
INKMimeHdrFieldValueStringGet
INKMimeHdrFieldValueStringInsert
INKMimeHdrFieldValueStringSet
INKMimeHdrFieldValueUintGet
INKMimeHdrFieldValueUIntInsert
INKMimeHdrFieldValueUintSet
INKMimeHdrFieldValuesClear
INKMimeHdrFieldValuesCount
INKMimeHdrClone
INKMimeHdrCopy
INKMimeHdrCreate
INKMimeHdrDestroy
INKMimeHdrFieldFind
INKMimeHdrFieldGet
INKMimeHdrFieldRemove
INKMimeHdrFieldsClear
INKMimeHdrFieldsCount
INKMimeHdrLengthGet
INKMimeHdrParse
INKMimeParserClear
INKMimeParserCreate
INKMimeParserDestroy
INKMimeHdrPrint
Mutex Functions
INKMutexCreate
INKMutexLock
INKMutexLockTry
INKMutexUnlock
Continuation Functions
INKContCall
INKContCreate
INKContDataGet
INKContDataSet
INKContDestroy
INKContMutexGet
INKContSchedule
Plugin Configuration Functions
INKConfigDataGet
INKConfigGet
INKConfigRelease
INKConfigSet
Action Functions
INKActionCancel
INKActionDone
Host Lookup Functions
INKHostLookup
INKHostLookupResultIPGet
Vconnection Functions
INKVConnAbort
INKVConnClose
INKVConnClosedGet
INKVConnRead
INKVConnReadVIOGet
INKVConnShutdown
INKVConnWrite
INKVConnWriteVIOGet
Netvconnection Functions
INKNetAccept
INKNetConnect
INKNetVConnRemoteIPGet
INKNetVConnRemotePortGet
Cache Interface Functions
INKCacheKeyCreate
INKCacheKeyDigestSet
INKCacheKeyHostNameSet
INKCacheKeyDestroy
INKCacheRead
INKCacheReady
INKCacheWrite
INKCacheRemove
INKCacheKeyPinnedSet
INKVConnCacheObjectSizeGet
Transformation Functions
INKTransformCreate
INKTransformOutputVConnGet
VIO Functions
INKVIOBufferGet
INKVIOVConnGet
INKVIOContGet
INKVIOMutexGet
INKVIONBytesGet
INKVIONBytesSet
INKVIONDoneGet
INKVIONDoneSet
INKVIONTodoGet
INKVIOReaderGet
INKVIOReenable
IO Buffer Interface
INKIOBufferBlockNext
INKIOBufferBlockReadAvail
INKIOBufferBlockReadStart
INKIOBufferBlockWriteAvail
INKIOBufferBlockWriteStart
INKIOBufferCopy
INKIOBufferCreate
INKIOBufferDestroy
INKIOBufferProduce
INKIOBufferReaderAlloc
INKIOBufferReaderAvail
INKIOBufferReaderClone
INKIOBufferReaderConsume
INKIOBufferReaderFree
INKIOBufferReaderStart
INKIOBufferSizedCreate
INKIOBufferStart
INKIOBufferWaterMarkGet
INKIOBufferWaterMarkSet
INKIOBufferWrite
Management Interface Functions
INKMgmtUpdateRegister
Traffic Server Configuration Read Functions
INKMgmtCounterGet
INKMgmtFloatGet
INKMgmtIntGet
INKMgmtStringGet
Customer Installation and Licensing Functions
INKInstallDirGet
INKPluginDirGet
INKPluginLicenseRequired
Statistics Functions
Uncoupled Statistics
INKStatFloatGet
INKStatIntGet
INKStatFloatAddTo
INKStatIntAddTo
INKStatCreate
INKStatDecrement
INKStatIncrement
INKStatFloatSet
INKStatIntSet
Coupled Statistics
INKStatCoupledGlobalAdd
INKStatCoupledLocalAdd
INKStatCoupledGlobalCategoryCreate
INKStatCoupledLocalCopyCreate
INKStatCoupledLocalCopyDestroy
INKStatsCoupledUpdate
Logging Functions
INKTextLogObjectCreate
INKTextLogObjectHeaderSet
INKTextLogObjectRollingEnabledSet
INKTextLogObjectRollingIntervalSecSet
INKTextLogObjectRollingOffsetHrSet
INKTextLogObjectWrite
INKTextLogObjectFlush
INKTextLogObjectDestroy
A. Sample Source Code
blacklist-1.c
B. Deprecated Functions
Deprecated MIME Header Functions
INKMimeFieldCopy
INKMimeFieldCopyValues
INKMimeFieldCreate
INKMimeFieldDestroy
INKMimeFieldLengthGet
INKMimeFieldNameGet
INKMimeFieldNameSet
INKMimeFieldNext
INKMimeFieldValueAppend
INKMimeFieldValueDelete
INKMimeFieldValueGet
INKMimeFieldValueGetDate
INKMimeFieldValueGetInt
INKMimeFieldValueGetUint
INKMimeFieldValueInsertDate
INKMimeFieldValueInsertInt
INKMimeFieldValueInsertUint
INKMimeFieldValuesClear
INKMimeFieldValuesCount
INKMimeFieldValueSet
INKMimeFieldValueSetDate
INKMimeFieldValueSetInt
INKMimeFieldValueSetUint
INKMimeHdrFieldValueGet
INKMimeHdrFieldValueGetDate
INKMimeHdrFieldValueGetInt
INKMimeHdrFieldValueGetUInt
INKMimeHdrFieldValueInsert
INKMimeHdrFieldValueInsertDate
INKMimeHdrFieldValueInsertInt
INKMimeHdrFieldValueInsertUInt
INKMimeHdrFieldValueSet
INKMimeHdrFieldValueSetDate
INKMimeHdrFieldValueSetInt
INKMimeHdrFieldValueSetUInt
INKMimeHdrFieldDelete
INKMimeHdrFieldInsert
INKMimeHdrFieldRetrieve
Other Deprecated Functions
Statistic Functions
INKStatFloatRead
INKStatIntRead
IO Buffer Interface
INKIOBufferAppend
INKIOBufferBlockCreate
INKIOBufferDataCreate
Mutex Function
InkMutexTryLock
C. Troubleshooting Tips
Unable to Compile Plugins
Unix Example
HPUX Example
Compiling For Windows NT
Unable to Load Plugins
Using Debug Tags
Other Useful Internal Debug Tags
Using a Debugger
Debugging Tips:
Debugging Memory Leaks
D. Function Index
E. Type Index
Index

List of Figures

1.1. Plugin Process
1.2. Possible Traffic Server Plugins
2.1. Traffic Server Internals
2.2. Traffic Server with Plugins
2.3. Simplified HTTP Transaction
2.4. API Hooks Corresponding to States Listed in the “Simplified HTTP Transaction” Figure
2.5. Blacklist Plugin
5.1. A Transformation and its VIOs
5.2. Passing Data Through a Transformation
5.3. Ending the Transformation
5.4. Reading Data Into the Buffer (the STATE_BUFFER_DATA State)
5.5. Writing the Buffered Data to the Output Vconnection
6.1. Sample Protocol State Diagram
6.2. Protocol Plugin Overview
6.3. Protocol Plugin Flow of Events
6.4. How Transaction State Machines are Implemented in the Protocol Plugin
8.1. HTTP Transaction State Diagram
10.1. HTTP Request/Response and Header Structure
10.2. Examples of HTTP Request and Response Headers
10.3. Marshal Buffers and Header Locations

List of Tables

1. Typographical Conventions
8.1. INKHttpHookID Values