Citrix ADC 拡張モジュールの API リファレンス

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

TCP クライアントの動作

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

• ctxt -TCPクライアント処理コンテキスト
• payload ：イベントペイロード
  • payload.d ata-受信したTCPデータ。バイトストリームとして利用できます。

TCP サーバの動作

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

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

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

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

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

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

• ctxt：Hold（データ） -将来の処理のためにデータを格納する関数。データで保留を呼び出すと、データはコンテキストに格納されます。後で、同じコンテキストでより多くのデータが受信されると、新しく受信したデータが以前に格納されたデータに追加され、結合されたデータストリームがon_dataコールバック関数に渡されます。保留を呼び出した後、データ参照は使用できなくなり、使用時にエラーが発生します。

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

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

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

TCP サーバコンテキスト

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

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

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

• ctxt：Hold（データ） -将来の処理のためにデータを格納する関数。データで保留を呼び出すと、データはコンテキストに格納されます。後で、同じコンテキストでより多くのデータが受信されると、新しく受信したデータが以前に格納されたデータに追加され、結合されたデータストリームがon_dataコールバック関数に渡されます。保留を呼び出した後、データ参照は使用できなくなり、使用時にエラーが発生します。

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

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

• ctxt：reuse_server_connection（） -このAPIは、サーバー接続がサーバーコンテキスト内の他のクライアント接続に対してのみ再利用できるようにするために使用されます。この API は、クライアントコンテキストでデータを送信するために (ns.send () API で) EOM イベントが使用されている場合にのみ使用できます。それ以外の場合、ADC アプライアンスはエラーをスローします。

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

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

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

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

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

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

• vserver: counter_increment (カウンタ_name) -引数として渡された仮想サーバカウンタの値をインクリメントします。現在、次の組み込みカウンタがサポートされています。
  • -invalid_messages — この仮想サーバー上の無効な要求/応答の数。
  • -invalid_messages_drop — この仮想サーバによって削除された無効な要求/応答の数。
• vserver.params -ユーザー仮想サーバー用に構成されたパラメータ。パラメーターは、拡張機能の設定機能を提供します。拡張コードは、CLI で指定されたパラメータにアクセスして、ユーザ仮想サーバを追加できます。

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

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

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

サーバ接続コンテキスト

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

• server.ssl – SSL コンテキスト
• server.tcp – TCP コンテキスト
• server.is_ssl — サーバー接続がSSLベースの場合はTrue

TCP コンテキスト

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

• tcp.srcport — 数値の送信元ポート
• tcp.dstport -番号としての宛先ポート

IP コンテキスト

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

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

注：このAPIは、Citrix ADC 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は、Citrix ADC 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 証明書コンテキスト

• Cert.version ：証明書のバージョン番号。接続が 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 -BLOB としての権限キー識別子のシリアル番号フィールド。
• cert.pk_algorithm -証明書で使用される公開鍵アルゴリズムの名前。
• cert.pk_size -証明書で使用される公開キーのサイズ。
• cert.serialnumber -クライアント証明書のシリアル番号。これが 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

Citrix ADC ライブラリ

• ns.tcp.stream -TCPデータをバイトストリームとして処理するためのライブラリのような文字列。これらの API が動作できる TCP ストリームデータの最大サイズは 128 KB です。ns.tcp.streamライブラリ関数は、通常の拡張オブジェクト指向の呼び出しスタイルでも呼び出すことができます。たとえば、データ:len () は、ns.tcp.stream.len (データ) と同じです。
  • ns.tcp.stream.len(data) -Luaのstring.lenに似たバイト単位のデータの長さを返します
  • ns.tcp.stream.find(data, pattern [, init])-Luaの文字列.matchに似た機能。また、データの最後に部分一致も行います。部分一致すると、開始インデックスが返され、終了インデックスがnilになります。
  • ns.tcp.stream.split(data, length) -データを2つのチャンクに分割します。最初のチャンクは指定された長さです。分割が成功すると、元のデータは TCP データストリームとして使用できなくなります。そのように使用しようとすると、エラーが発生します。
  • ns.tcp.stream.byte(data[, i [, j]]) -Luaのstring.byteに似た機能。文字データ[i]、データ[i+1]、…、データ[J]の内部数値コードを返します。
  • ns.tcp.stream.sub(data, i [, j]) -Luaのstring.subに似た機能。iから始まり、jまで続くsの部分文字列を返します。
  • ns.tcp.stream.match(data, pattern, [, init])-Luaのstring.matchに似た機能。文字列 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(number) -指定されたネットワークバイトオーダーをホストバイトオーダーに変換します。入力が2 ^ 16-1より大きい場合、エラーがスローされます。
  • ns.inet.htons(number) -指定されたホストのバイト順序をネットワークのバイト順序に変換します。入力が2 ^ 16-1より大きい場合、エラーがスローされます。
  • ns.inet.ntohl(number) -指定されたネットワークバイトオーダーをホストバイトオーダーに変換します。入力が2 ^ 32-1より大きい場合、エラーがスローされます。
  • ns.inet.htonl(number) -指定されたホストのバイト順序をネットワークのバイト順序に変換します。入力が2 ^ 32-1より大きい場合、エラーがスローされます。
  • ns.inet.subnet(address_str, subnet_value) –指定されたサブネットを適用した後、サブネットアドレス文字列を返します。