Citrix ADC 扩展 API 参考

行为是 Citrix ADC 设备上可用的常见可编程模式的正式化。例如，TCP 虚拟服务器支持 TCP 客户端行为和 TCP 服务器行为。行为是一组预定义的回调函数。您可以通过提供回调函数来实现行为。例如，TCP 客户端行为可以包含处理 TCP 数据流的 on_data 函数。

TCP 客户端行为

on_data -TCP 客户端数据事件的函数回调。回调需要两个参数：

• ctxt -TCP 客户端处理上下文
• 有效负载 — 事件有效负载
  • payload.data -接收到的 TCP 数据，作为字节流提供

TCP 服务器行为

on_data -TCP 服务器数据事件的函数回调，回调需要两个参数：

• ctxt -TCP 服务器处理上下文
• 有效负载 — 事件有效负载
  • payload.data -接收到的 tcp 数据，作为字节流可用

TCP 客户端上下文

传递给 TCP 客户端事件回调的上下文：

• ctxt.output -管道中的下一个处理上下文。扩展回调处理程序可以使用事件 DATA 将 ns.tCP.stream 类型的数据发送到 ctxt.output，这意味着部分消息或 EOM，意味着协议消息的结束。EOM 事件可能具有也可能不具有 TCP 数据。包含 TCP 数据的 EOM 事件可以在没有前面的 DATA 事件的情况下发送，以发送整个协议消息数据并标记消息结束。负载平衡决策由负载平衡虚拟服务器根据收到的第一个数据进行下游。在收到 EOM 消息后，将做出新的负载平衡决策。因此，要流式传输协议消息数据，请发送多个 DATA 事件，最后一个事件作为 EOM。所有连续的 DATA 事件和以下 EOM 事件都会发送到序列中第一个 DATA 事件的负载平衡决策所选的相同服务器连接。

• ctxt.input -TCP 流数据来自的管道中之前的处理上下文。

• ctxt:hold（数据） -存储数据以供将来处理的功能。使用数据调用保持时，数据存储在上下文中。之后，在同一上下文中接收更多数据时，新接收的数据会附加到先前存储的数据，然后将组合的数据流传递给 on_data 回调函数。调用保留后，数据引用不再可用，并在任何使用情况下都会出现错误。

• ctxt.vserver -虚拟服务器上下文。

• ctxt.client — 客户端 连接处理上下文。此处理上下文可用于将数据发送到客户端，并获取一些与连接相关的信息，如 IP 地址、源端口和目标端口。

• ctxt: close () -通过向客户端发送 FIN 来 关闭客户端连接。调用此 API 后，客户端处理上下文不再可用，并在任何使用情况下都会出现错误。

TCP 服务器上下文

传递给 TCP 服务器事件回调的上下文：

• ctxt.output — 管道中的下一个处理上下文。扩展回调处理程序可以使用事件 DATA 将 ns.tCP.stream 类型的数据发送到 ctxt.output，这意味着部分消息或 EOM，意味着协议消息的结束。

• ctxt.input -TCP 流数据来自的管道中之前的处理上下文。

• ctxt:hold（数据） -存储数据以供将来处理的功能。使用数据调用保持时，数据存储在上下文中。之后，在同一上下文中接收更多数据时，新接收的数据会附加到先前存储的数据，然后将组合的数据流传递给 on_data 回调函数。调用保留后，数据引用不再可用，并在任何使用情况下都会出现错误。

• ctxt.vserver -虚拟服务器上下文。

• ctxt.server-服务器 连接处理上下文。此处理上下文可用于将数据发送到服务器，并获取一些与连接相关的信息，如 IP 地址、源端口和目标端口。

• ctxt:reuse_server_connection () -此 API 用于允许服务器连接仅用于服务器上下文中的其他客户端连接。只有在使用 EOM 事件（在 ns.send () API 中）在客户端上下文中发送数据时，才能使用此 API。否则，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(counter_name) -增加作为参数传递的虚拟服务器计数器的值。目前支持以下内置计数器。
  • - invalid_messages — 此虚拟服务器上的无效请求/响应数量。
  • - invalid_messages_dropped -此虚拟服务器丢弃的无效请求/响应数量。
• 虚拟服务器.params -为用户虚拟服务器配置的参数。参数提供扩展的可配置性。扩展代码可以访问 CLI 中指定的参数以添加用户虚拟服务器。

客户端连接上下文

用于获取连接相关信息的客户端连接处理上下文。

• 客户端 .ssl -SSL 上下文
• 客户端 .tcp -TCP 上下文
• client.is_ssl — 如果客户端连接是基于 SSL 的，则为 true

服务器连接上下文

用于获取连接相关信息的服务器连接处理上下文。

• 服务器 .ssl -SSL 上下文
• 服务器 .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 Build 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 Build 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_bit — 加密密钥中的位数。

SSL 证书上下文

• 证书。版本 — 证书的版本号。如果连接不基于 SSL，则返回 0。
• Cert.valid_not_before — 在字符串格式之前证书无效的日期。
• Cert.valid_not_after — 日期为字符串格式，在该日期之后证书不再有效。
• Cert.days_to_expire - 证书有效之前的天数。返回-1 表示过期证书。
• Cert.to_pem — 二进制格式的证书。

• cert.颁发 者-证书中的颁发者的可分辨名称 (DN) 作为名称-值列表。等号 (“=”) 是名称和值的分隔符，斜杠 (“/”) 是分隔名称-值对的分隔符。

  下面是返回 DN 的示例： /C = 我的公司/我的公司/我的公司/我的公司/我的公司/电子邮件地址 = 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 -作为 Blob 的权限密钥标识符字段
  • Auth_keyid.cert_序列号 -作为 Blob 的授权密钥标识符的序列号字段。
• cert.pk_algorithm -证书使用的公钥算法的名称。
• cert.pk_size -证书中使用的公钥的大小。
• cert.序列号- 客户端证书的序列号。如果这是一个非 SSL 事务或证书中存在错误，则会给出一个空字符串。
• cert.signature_algorithm -CA 用于签署此证书的加密算法的名称。
• cert.subject_keyid -客户端证书的主题密钥 ID。如果没有主题键 ID，则会给出一个零长度的文本对象。
• cert.主题 -作为名称值的主题的可分辨名称。等号 (“=”) 分隔名称和值，斜杠 (“/”) 分隔名称-值对。

以下是一个例子： /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（数据） -以字节为单位返回数据的长度，类似于 Lua 的字符串。len
  • ns.tcp.stream.find（数据，模式 [，init]）-类似于 Lua 的字符串。查找功能。此外，它还在数据末尾执行部分匹配。部分匹配后，返回起始索引，结束索引变为零。
  • ns.tcp.stream.split（数据，长度） -将数据拆分成两个块，第一个块是指定长度的。成功拆分后，原始数据不再用作 TCP 数据流。任何尝试以这种方式使用它都会导致错误。
  • ns.tcp.stream.byte（数据[，i [，j]]）-类似于 Lua 的字符串。返回字符 data[i], data[i+1], …, data[j] 的内部数字代码。
  • n.tcp.stream.sub（数据，i [，j]）-函数类似于 Lua 的字符串。返回从 i 开始并持续到 j 的子字符串。
  • 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 — 图书馆的 Internet 地址。

  • 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) — 应用给定子网后返回子网地址字符串。