NetScalerの拡張 - APIリファレンス

動作とは、NetScalerアプライアンスで使用できる一般的なプログラム可能なパターンを形式化したものです。たとえば、TCP 仮想サーバーは TCP クライアントの動作と TCP サーバーの動作をサポートします。動作とは、あらかじめ定義されたコールバック関数のセットです。コールバック関数を提供することで動作を実装できます。たとえば、TCP クライアントの動作は TCP データストリームを処理する on_data 関数で構成できます。

TCP クライアントの動作

on_data -TCP クライアントデータイベントの関数コールバック。コールバックは次の 2 つの引数を取ります。

• ctxt -TCP クライアント処理コンテキスト
• ペイロード — イベントペイロード
  • payload.data -受信した TCP データ、バイトストリームとして利用可能

TCP サーバーの動作

on_data -TCPサーバーデータイベントの関数コールバック。コールバックは2つの引数を取ります。

• ctxt -TCP サーバ処理コンテキスト
• ペイロード — イベントペイロード
  • payload.data -受信した TCP データ、バイトストリームとして利用可能

TCP クライアントコンテキスト

TCP クライアントイベントコールバックに渡されるコンテキスト:

• ctxt.output -パイプライン内の次の処理コンテキスト。拡張コールバックハンドラーは、イベント DATA（メッセージの一部）またはプロトコルメッセージの終了を意味する EOM を使用して、ns.tcp.stream タイプのデータを ctxt.output に送信できます。EOM イベントには TCP データが含まれている場合と含まれていない場合があります。TCP データを含む EOM イベントを先に DATA イベントなしで送信すると、プロトコルメッセージデータ全体を送信してメッセージの終了を知らせることができます。負荷分散の決定は、最初に受信したデータに基づいて、負荷分散仮想サーバーによって下流で行われます。EOM メッセージの受信後に、新しい負荷分散の決定が行われます。そのため、プロトコルメッセージデータをストリーミングするには、最後のイベントを EOM として複数の DATA イベントを送信します。連続するすべての DATA イベントと次の EOM イベントは、シーケンスの最初の DATA イベントの負荷分散決定によって選択された同じサーバー接続に送信されます。

• ctxt.input -TCPストリームデータの送信元であるパイプライン内の以前の処理コンテキスト。

• ctx: hold (データ) -将来の処理に備えてデータを保存する関数。データで hold を呼び出すと、データはコンテキストに保存されます。その後、同じコンテキストでさらにデータを受信すると、新しく受信したデータが以前に保存されたデータに追加され、結合されたデータストリームが on_data コールバック関数に渡されます。保留を呼び出すと、データ参照は使用できなくなり、どの使用でもエラーになります。

• ctxt.vserver-仮想サーバーのコンテキスト 。

• ctxt.client — クライアント接続処理コンテキスト 。この処理コンテキストを使用して、クライアントにデータを送信したり、IPアドレス、送信元、宛先ポートなどの接続関連情報を取得したりできます。

• ctx: close () — FIN をクライアントに送信してクライアント接続を閉じます。この API を呼び出すと、クライアント処理コンテキストは使用できなくなり、どのような使用でもエラーが発生します。

TCP サーバーコンテキスト

TCP サーバーのイベントコールバックに渡されるコンテキスト:

• ctxt.output — パイプライン内の次の処理コンテキスト。拡張コールバックハンドラーは、イベント DATA（メッセージの一部）またはプロトコルメッセージの終了を意味する EOM を使用して、ns.tcp.stream タイプのデータを ctxt.output に送信できます。

• ctxt.input -TCPストリームデータの送信元であるパイプライン内の以前の処理コンテキスト。

• ctx: hold (データ) -将来の処理に備えてデータを保存する関数。データで hold を呼び出すと、データはコンテキストに保存されます。その後、同じコンテキストでさらにデータを受信すると、新しく受信したデータが以前に保存されたデータに追加され、結合されたデータストリームが on_data コールバック関数に渡されます。保留を呼び出すと、データ参照は使用できなくなり、どの使用でもエラーになります。

• ctxt.vserver-仮想サーバーのコンテキスト 。

• ctxt.server-サーバー接続処理コンテキスト 。この処理コンテキストを使用して、データをサーバーに送信したり、IPアドレス、送信元ポート、宛先ポートなどの接続関連情報を取得したりできます。

• ctx: reuse_server_connection () -この API を使用すると、サーバー接続をサーバーコンテキスト内の他のクライアント接続にのみ再利用できます。この API は、(ns.send () API で) EOM イベントを使用してクライアントコンテキストでデータを送信する場合にのみ使用できます。そうしないと、ADC アプライアンスはエラーを投げます。

  サーバー接続を他のクライアントが再利用できるようにするには、各応答メッセージの最後にこの API を呼び出す必要があります。この API を呼び出した後、このサーバー接続でさらにデータを受信した場合、これはエラーとして扱われ、サーバー接続は閉じられます。この API を使用しない場合、サーバー接続は、その接続が開かれたクライアントでのみ使用できます。また、そのクライアントに対して別の負荷分散を決定するために同じサーバーを選択した場合、同じサーバー接続を使用してクライアントデータを送信します。この API を使用すると、サーバー接続は開かれたクライアント接続に関連付けられなくなり、他のクライアント接続の新しい負荷分散の決定に再利用できます。この API を呼び出すと、サーバーコンテキストは使用できなくなり、使用するとエラーが発生します。

  注：このAPIはNetScaler 12.1ビルド49.xx以降で使用できます。

• ctx: close () — FIN をサーバーに送信してサーバー接続を閉じます。この API を呼び出すと、クライアント処理コンテキストは使用できなくなり、どのような使用でもエラーが表示されます。

  注：このAPIは、NetScaler 12.1ビルド50.xx以降で使用できます。

仮想サーバーコンテキスト

コールバックに渡されるコンテキストを介して利用可能なユーザー仮想サーバーコンテキスト:

• vserver: counter_increment (counter_name) -引数として渡された仮想サーバーカウンターの値をインクリメントします。現在、以下の組み込みカウンターがサポートされています。
  • -invalid_messages — この仮想サーバー上の無効なリクエスト/レスポンスの数。
  • -invalid_messages_dropped — この仮想サーバーによってドロップされた無効なリクエスト/レスポンスの数。
• vserver.params-ユーザー仮想サーバーに設定されたパラメーター 。パラメータは拡張の設定を可能にします。拡張コードは、CLI で指定されたパラメータにアクセスして、ユーザー仮想サーバーを追加できます。

クライアント接続コンテキスト

接続関連情報を取得するためのクライアント接続処理コンテキスト。

• クライアント.ssl — SSL コンテキスト
• クライアント.tcp — TCP コンテキスト
• client.is_ssl — クライアント接続が SSL ベースの場合は True

サーバー接続コンテキスト

接続関連情報を取得するためのサーバー接続処理コンテキスト。

• server.ssl – SSL context
• server.tcp – TCP context
• server.is_ssl — サーバー接続が SSL ベースの場合は True

TCP コンテキスト

TCP コンテキストは TCP プロトコルで動作します。

• tcp.srcport — 送信元ポートを数値で表したもの
• tcp.dstport-宛先ポートを数値で表したもの

IP コンテキスト

IP コンテキストは IP または IPv6 プロトコルデータで機能します。

• ip.src -送信元 IP アドレスコンテキスト。
• ip.dst -宛先 IP アドレスコンテキスト。

注：このAPIはNetScaler 12.1ビルド51.xx以降で使用できます。

IP アドレスコンテキスト

IP アドレスコンテキストは IP または IPv6 アドレスデータで機能します。

• <address>.to_s -適切な ASCII 表記のアドレス文字列。
• <address>.to_n -ネットワーク順のバイト列で表したアドレスの数値 (IPv4は4バイト、IPv6は16バイト)。
• <address>.version -IPv4 の場合は 4、IPv6 の場合は 6 を返します。
• <address>:subnet(<prefix value>) -プレフィックス番号を適用した後のサブネットアドレス文字列を返します。
  • IPv4 アドレスの場合、値は 0 から 32 の間でなければなりません
  • IPv6 アドレスの場合、値は 0 から 128 の間でなければなりません。
• <address>:apply_mask(<mask string>) -マスク文字列を適用した後のアドレス文字列を返します。API は引数のバージョンを検証し、適切なエラーチェックを行います。
• address>:eq(<address string>) -引数がアドレスオブジェクトと等しいかどうかに基づいて true または false を返します。API は引数のバージョンを検証します。

注：このAPIはNetScaler 12.1ビルド51.xx以降で使用できます。

SSL コンテキスト

SSL コンテキストは、フロントエンド SSL 接続に関連する情報を提供します。

• ssl.cert — SSL 証明書コンテキスト。クライアント接続の場合はクライアント証明書コンテキストを提供し、サーバー接続の場合はサーバー証明書コンテキストを提供します。

• ssl.version -現在のトランザクションの SSL プロトコルバージョンを表す数値。次のようになります。

  • - 0: The transaction is not SSL-based
  • - 0x002: The transaction is SSLv2
  • - 0x300: The transaction is SSLv3
  • - 0x301: The transaction is TLSv1
  • - 0x302: The transaction is TLSv1.1
  • - 0x303: The transaction is TLSv1.2
• ssl.cipher_name -SSL 接続から呼び出された場合は SSL 暗号名を文字列とし、それ以外の場合は NULL 文字列を返します。
• ssl.cipher_bits — 暗号化キーのビット数。

SSL 証明書コンテキスト

• 証明書バージョン — 証明書のバージョン番号。接続が SSL ベースでない場合は、0 を返します。
• Cert.Valid_not_Before — 文字列形式の日付で、それより前の証明書は無効です。
• Cert.valid_not_After — 文字列形式の日付。この日付を過ぎると証明書は無効になります。
• Cert.days_to_Expire — 証明書が有効になるまでの日数。期限切れの証明書の場合は -1 を返します。
• cert.to_PEM — バイナリ形式の証明書。

• cert.issuer -証明書内の発行者の識別名 (DN) を名前/値リストとして表示します。等号 (「=」) は名前と値の区切り文字で、スラッシュ (「/」) は名前と値のペアを区切る区切り文字です。

  返される DN の例を以下に示します。 /C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

• cert.auth_keyid — X.509 V3 証明書のオーソリティキー識別子エクステンションのコンテキスト。

  • auth_keyid.exists -証明書にオーソリティキー識別子の拡張子が含まれている場合は TRUE。

  • auth_keyid.issuer_name-証明書内の発行者識別名を名前/値リストとして指定します 。 等号 (「=」) は名前と値の区切り文字で、スラッシュ (「/」) は名前と値のペアを区切る区切り文字です。

  以下は例です: /C =us/o=mycompany/ou=www.mycompany.com/cn=www.mycompany.com/emailAddress= myuserid@mycompany.com

  • auth_keyid.keyid-ブロブとしてのオーソリティキー識別子のキー識別子フィールド
  • auth_keyid.cert_serialnumber-ブロブ形式のオーソリティキー識別子のシリアル番号フィールド 。
• cert.pk_algorithm -証明書で使用される公開鍵アルゴリズムの名前。
• cert.pk_size -証明書で使用されるパブリックキーのサイズ。
• cert.シリアル番号-クライアント証明書のシリアル番号 。これがSSL以外のトランザクションであるか、証明書にエラーがある場合は、空の文字列が返されます。
• cert.signature_algorithm -CA がこの証明書に署名するために使用する暗号化アルゴリズムの名前。
• cert.subject_keyid-クライアント証明書のサブジェクトキーID 。Subject KeyID がない場合は、長さ 0 のテキストオブジェクトになります。
• cert.subject-サブジェクトの識別名を名前/値として指定します 。等号 (「=」) は名前と値を区切り、スラッシュ (「/」) は名前と値のペアを区切ります。

以下は例です: /C =us/o=mycompany/ou=www.mycompany.com/cn=www.mycompany.com/emailAddress= myuserid@mycompany.com

NetScaler ライブラリ

• ns.tcp.stream -TCPデータをバイトストリームとして処理するための文字列のようなライブラリ。これらの API が動作できる TCP ストリームデータの最大サイズは 128 KB です。ns.tcp.stream ライブラリ関数は、通常の拡張オブジェクト指向の呼び出し方法で呼び出すこともできます。たとえば、data: len () は ns.tcp.stream.len (データ) と同じです
  • ns.tcp.stream.len (データ) -Lua の文字列.len と同様に、データの長さをバイト単位で返します
  • ns.tcp.stream.find (data, pattern [, init])-Lua の文字列.find に似た関数さらに、データの最後で部分的なマッチングも行います。部分的に一致すると、開始インデックスが返され、終了インデックスは nil になります。
  • ns.tcp.stream.split (データ、長さ)-データを 2 つのチャンクに分割します。最初のチャンクは指定された長さになります。分割が成功すると、元のデータは TCP データストリームとして使用できなくなります。その方法で使用しようとするとエラーが発生します。
  • ns.tcp.stream.byte (data [, i [, j]])-Lua の文字列.byte に似た関数。データ [i]、データ [i+1]、…、データ [j] の内部数値コードを返します。
  • ns.tcp.stream.sub (data, i [, j])-Lua の string.sub に似た関数。i から始まり j まで続く s の部分文字列を返します。
  • ns.tcp.stream.match (データ、パターン、[, init])-Lua の文字列マッチに似た関数。文字列 s のパターンに最初に一致するものを探します 。

• ns.send (processing_ctxt、event_name、event_data )-処理コンテキストにイベントを送信する汎用関数。イベントデータは、どのような内容でも含めることができる Lua テーブルです。内容はイベントによって異なります。ns.send () API が呼び出されると、データ参照は使用できなくなります。これを使用しようとするとエラーが発生します。

• ns.pipe (src_ctxt、dest_ctxt)-pipe () API の呼び出しを使用して、拡張コードはソースコンテキストを宛先コンテキストに接続できます。パイプを呼び出すと、ソースコンテキストからパイプライン内の次のモジュールに送信されるすべてのイベントは、宛先コンテキストに直接送信されます。この API は通常、pipe () 呼び出しを行うモジュールがパイプラインから自身を削除するために使用されます。

• ns.inet — インターネットアドレス用ライブラリ。

  • ns.inet.apply_mask (address_str, mask_str)-マスク文字列を適用した後のアドレス文字列を返します 。
  • ns.inet.aton (address_str) -アドレスの数値をネットワーク順のバイト列として返します (IPv4の場合は4バイト、IPv6の場合は16バイト)。
  • ns.inet.ntoa (byte_str)-数値バイト値をバイト文字列としてアドレス文字列に変換します 。
  • ns.inet.ntohs (数値) -指定されたネットワークのバイトオーダーをホストのバイトオーダーに変換します。入力が 2^16-1 より大きい場合、エラーが発生します。
  • ns.inet.htons (数値) -指定されたホストのバイトオーダーをネットワークのバイトオーダーに変換します。入力が 2^16-1 より大きい場合、エラーが発生します。
  • ns.inet.ntohl (数値) -指定されたネットワークバイトオーダーをホストのバイトオーダーに変換します。入力が 2^32-1 より大きい場合、エラーが発生します。
  • ns.inet.htonl (数値) -指定されたホストのバイトオーダーをネットワークのバイトオーダーに変換します。入力が 2^32-1 より大きい場合、エラーが発生します。
  • ns.inet.subnet (address_str、subnet_value) — 指定されたサブネットを適用した後のサブネットアドレス文字列を返します 。