TSAPI

Introduction to the Apache Traffic Server API.

概要

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

解説

Apache Traffic Server API は C 言語を使ってインストール済みの Traffic Server の振る舞いをカスタマイズするプラグインの作成を可能にします。

Traffic Server は洗練されたキャッシュと DNS や HTTP のリクエストやレスポンスのような Web 関連トラフィックの処理を可能とします。Traffic Server 自体は次のように簡素化されたイベントドリブンループから成っています。

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

Traffic Server が動作を開始するときに読み込まれる共有ライブラリを作るためにプラグインのソースをコンパイルします。プラグインは特定の Traffic Server イベントに登録されるコールバック関数を含んでいます。Traffic Server がイベントの処理を必要とすると、そのイベントタイプに登録したあらゆるコールバック関数が呼び出されます。

プラグインは次の使い方ができます。

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

  • プロトコルプラグインは Traffic Server が新しいプロトコルコンテンツをプロキシーキャッシュできるようにします。

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

  • 追加変換プラグインは HTTP レスポンスコンテンツにデータを追加します。

  • 画像変換プラグインは JPEG 画像を GIF 画像に変換します。

  • 圧縮プラグインはデータを圧縮する圧縮サーバーにレスポンスデータを送信します (もしくは、Traffic Server のホストマシンにある圧縮ライブラリが圧縮を行うかもしれません) 。

  • 認証プラグインは特定の Web サイトにアクセスするためのユーザーの権限を確認します。このプラグインはローカルの認証プログラムに問い合わせたり、認証サーバーに問い合わせを送信したりするかもしれません。

  • リクエストヘッダーからクライアントの情報を収集しその情報をデータベースに入力するプラグイン。

  • プロトコルプラグインは指定されたポートへの特定のプロトコルのリクエストを受け、クライアントのリクエストに応えるために Traffic Server のプロキシーサーバーとキャッシュを使用します。

Naming Conventions

Traffic Server API は次の命名規則に従います。

  • 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()

  • 関数名は混在になります。例えば、TSUrlCreate() や TSContDestroy() となります。

  • 関数名は次の 主語-動詞 命名スタイルを使用します。TS-<主語>-<動詞> 、<主語> の部分は一般的なものから限定的なものにしていきます。これはその名前を読むことで関数が何をするのかを分かりやすくします。例えば、URL (一般的な主語) からパスワードフィールド (限定的な主語) を取得する関数は TSUrlPasswordGet() となります。

  • Create 、Destroy 、Get 、Set 、Copy 、Find 、Retrieve 、Insert 、Remove 、Delete のような一般的な動詞はそれが適切な場合にのみ使用されます。

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.

以下の plugin.config ファイルのサンプルはコメント行、空行、二つのプラグインの設定から成っています。

# 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

plugin.config ファイル内の個々のプラグインの設定は UNIX または DOS のシェルコマンドに似ています。plugin.config 内の各行は 1023 文字を超えることはできません。

最初のプラグインの設定は my-plugin.so と名付けられたプラグインのためのものです。これはそのプラグインの初期化ルーチンに渡される三つの引数を含んでいます。二番目の設定は some-plugin.so と名付けられたプラグインのためのものです。これは三つの引数を含んでいます。その最後の引数である $proxy.config.http.cache.on は実は設定変数です。Traffic Server は指定された設定変数を参照し、その値で置き換えます。

プラグインは plugin.config ファイルに出てくる順番で Traffic Server に読み込まれ初期化されます。

Plugin Initialization

各プラグインはプラグインが読み込まれたときに Traffic Server が呼び出す TSPluginInit() という初期化関数を定義していなければなりません。TSPluginInit() は一般的に設定情報を読み込みイベント通知のフックを登録するために使用されます。

ファイル

plugin.config, records.yaml

参照

TSPluginInit(3ts)