NetScaler 扩展 API 参考

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

TCP 客户端行为

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

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

TCP 服务器行为

on_data -TCP 服务器数据事件的函数回调，该回调采用两个参数：

• ctxt -TCP 服务器处理上下文
• 有效载荷 -事件负载
  • payload.data-收到的 tcp 数据，以字节流的形式提供

TCP 客户端上下文

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

• ctxt.output -管道中的下一个处理上下文。扩展回调处理程序可以使用事件数据（表示部分消息）或 EOM（表示协议消息结束）向 ctxt.output 发送 ns.tcp.stream 类型的数据。EOM 事件可能带有 TCP 数据，也可能没有 TCP 数据。带有 TCP 数据的 EOM 事件可以在没有先前的 DATA 事件的情况下发送，以发送整个协议消息数据并标记消息结束。负载平衡决策是在下游由负载平衡虚拟服务器根据接收到的第一批数据做出的。在收到 EOM 消息后做出新的负载平衡决策。因此，要流式传输协议消息数据，请发送多个 DATA 事件，最后一个事件为 EOM。所有连续的 DATA 事件和以下 EOM 事件都发送到序列中第一个 DATA 事件的负载平衡决策所选择的同一个服务器连接。

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

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

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

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

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

TCP 服务器上下文

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

• ctxt.output — 管道中的下一个处理上下文。扩展回调处理程序可以使用事件数据（表示部分消息）或 EOM（表示协议消息结束）向 ctxt.output 发送 ns.tcp.stream 类型的数据。

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

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

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

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

• ctxt: reuse_server_connection () -此 API 用于仅在服务器上下文中将服务器连接重用于其他客户端连接。只有在使用 EOM 事件（在 ns.send () API 中）在客户端上下文中发送数据时，才能使用此 API。否则，ADC 设备会引发错误。

  要允许其他客户端重用服务器连接，必须在每条响应消息的末尾调用此 API。调用此 API 后，如果在此服务器连接上接收到更多数据，则将其视为错误并关闭服务器连接。如果不使用此 API，则服务器连接只能用于为其打开的客户端。此外，如果为该客户机的另一项负载平衡决策选择了同一台服务器，则使用相同的服务器连接来发送客户机数据。使用此 API 后，服务器连接不再绑定到为其打开的客户端连接，并且可以重复用于为任何其他客户端连接做出新的负载平衡决策。调用此 API 后，服务器上下文不再可用，任何使用都会引发错误。

  注意：此 API 在 NetScaler 12.1 版本 49.xx 及更高版本中可用。

• ctxt: 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 则为真

服务器连接上下文

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

• 服务器.ssl — SSL 上下文
• 服务器.tcp — TCP 上下文
• server.is_ssl — 如果服务器连接基于 SSL 则为真

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_nam e-如果从 SSL 连接调用，则 SSL 密码名称为字符串，否则会给出空字符串。
• ssl.cipher_bits — 加密密钥中的位 数。

SSL 证书上下文

• cert.vers ion — 证书的版本号。如果连接不是基于 SSL，则返回 0。
• cert.valid_not_Before — 字符串格式的日期，在此日期之前 的证书无效。
• cert.valid_not_A fter — 字符串格式的日期，之后证书将不再有效。
• cert.days_to_Expire — 证书有效期 之前的天数。对于过期的证书，返回 -1。
• cert.to_pem — 二进制格式的证书。

• cert.issu are-作为名称值列表的证书中颁发者的专有名称 (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-权限密钥 标识符的密钥标识符字段为 blob
  • auth_keyid.cert_serialnumber-权限密钥标识符的序列号字段为一个bl ob。
• cert.pk_al thorigh-证书使用的公钥算法的名称。
• cert.pk_siz e-证书中使用的公钥的大小。
• cert.serial number-客户证书的序列号。如果这是非 SSL 交易或证书中有错误，则会给出一个空字符串。
• cert.signature_al thorigh-CA 用来签署此证书的加密算法的名称。
• cert.subject_keyid-客户端证书的主体 keyID 。如果没有 Subject keyID，则会生成长度为零的文本对象。
• cert.subj ect-作为名称值的主题的专有名称。等号 (“=”) 分隔名称和值，斜杠 (“/”) 分隔名称-值对。

以下是示例： /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 的 string.len
  • ns.tcp.stream.find(data, pattern [, init]) - 类似于 Lua 的 string.find 的函数。此外，它还会在数据末尾进行部分匹配。部分匹配后，返回起始索引，结束索引变为 nil。
  • ns.tcp.stream.split（数据，长度） -将数据分成两个块，第一个块具有指定的长度。成功拆分后，原始数据将无法再用作 TCP 数据流。任何以这种方式使用它的尝试都会导致错误。
  • ns.tcp.stream.byte（数据 [，i [，j]]） -类似于 Lua 的 string.byte 的函数。返回字符数据 [i]、数据 [i+1]、…、数据 [j] 的内部数字代码。
  • ns.tcp.stream.sub（数据，i [，j]） -类似于 Lua 的 string.sub 的函数。返回 s 的子字符串，该子字符串从 i 开始一直持续到 j。
  • 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，扩展代码可以将源上下文连接到目标上下文。调用管道后，从源上下文发送到管道中下一个模块的所有事件都直接进入目标上下文。调用 pipe() 的模块通常使用此 API 将自身从管道中移除。

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