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-管道中的下一个处理上下文。扩展回调处理程序可以将ns.tcp.stream类型的数据发送到ctxt。使用事件DATA输出，这意味着部分消息或EOM，这意味着协议消息的结束。EOM事件可能包含TCP数据，也可能没有。一个带有TCP数据的EOM事件可以在没有前面的data事件的情况下发送，以发送整个协议消息数据，并标志消息的结束。负载均衡决策由负载均衡虚拟服务器在接收到的第一个数据时做出。在收到EOM消息后，将做出新的负载均衡决策。因此，为了流协议消息数据，发送多个data事件，最后一个事件作为EOM。所有连续的DATA事件和下面的EOM事件被发送到由负载平衡决策在序列中第一个DATA事件上选择的相同服务器连接。

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

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

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

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

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

TCP服务器上下文

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

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

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

• ctxt:持有(数据)-存储数据以供将来处理的函数。在调用数据保持时，数据存储在上下文中。稍后，当在同一上下文中接收到更多数据时，新接收到的数据将附加到先前存储的数据中，然后将合并的数据流传递给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在Citrix ADC 12.1 build 49中可用。Xx及以后。

• ctxt: close ()—通过向服务器发送FIN关闭服务器连接。调用此API后，客户端处理上下文将不再可用，并在任何使用时显示错误。

  请注意:此API在Citrix ADC 12.1 build 50中可用。Xx及以后。

Vserver上下文

通过传递给回调函数的上下文可用的用户虚拟服务器上下文:

• vserver: counter_increment (counter_name)-增加作为参数传递的虚拟服务器计数器的值。目前支持以下内置计数器。
  • ——invalid_messages-该虚拟服务器上无效请求/响应的个数。
  • ——invalid_messages_dropped-该虚拟服务器丢弃的无效请求/响应数。
• 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 build 51中可用。Xx及以后。

IP地址上下文

IP地址上下文处理IP或IPv6地址数据。

• <地址> .to_s-适当ASCII符号的地址字符串。
• <地址> .to_n-地址的数字值为网络顺序的字节字符串(IPv4为4字节，IPv6为16字节)。
• <地址> .version—IPv4返回4,IPv6返回6。
• (< <地址>:子网前缀值>)—应用前缀编号后返回子网地址字符串。
  • 对于IPv4地址，取值范围为0 ~ 32
  • 对于IPv6地址，取值范围为0 ~ 128。
• 面具<地址>:apply_mask(<字符串>)—应用掩码字符串后返回地址字符串。API验证参数的版本并进行适当的错误检查。
• 解决>:情商(<地址字符串>)-根据参数是否等价于地址对象，返回true或false。API验证参数的版本。

请注意:该API在Citrix ADC 12.1 build 51中可用。Xx及以后。

SSL上下文

SSL上下文提供与前端SSL连接相关的信息。

• ssl.cert—SSL证书上下文。对于客户机连接，它提供客户机证书上下文，对于服务器连接，它提供服务器证书上下文。

• ssl.version—表示当前事务的SSL协议版本的数字，如下所示:

  • —0:非ssl事务
  • —0x002:事务是SSLv2
  • —0x300:事务是SSLv3
  • —0x301:事务为TLSv1
  • —0x302:事务为TLSv1.1
  • —0x303:事务为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 (Distinguished Name)，以名称-值列表的形式显示。等号(“=”)是名称和值的分隔符，斜杠(“/”)是分隔名称-值对的分隔符。

  返回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-授权密钥标识符的KeyIdentifier字段为一个blob
  • auth_keyid.cert_serialnumber—授权密钥标识符的SerialNumber字段为blob。
• cert.pk_algorithm—证书使用的公钥算法名称。
• cert.pk_size—证书中使用的公钥大小。
• cert.serialnumber—客户端证书序列号。如果这是非ssl事务，或者证书中有错误，则会给出一个空字符串。
• cert.signature_algorithm—CA用于签署此证书的加密算法的名称。
• cert.subject_keyid—客户端证书的Subject KeyID。如果没有Subject KeyID，这将给出一个零长度的文本对象。
• 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。stream库函数也可以用通常的面向扩展对象的调用方式调用。例如，data:len()与ns.tcp.stream.len(data)相同。
  • ns.tcp.stream.len(数据)-返回以字节为单位的数据长度，类似于Lua的string.len
  • ns.tcp.stream。Find (data, pattern [， init])-函数类似于Lua的string.find。此外，它还在数据的末尾进行部分匹配。在部分匹配时，返回开始索引，结束索引为nil。
  • ns.tcp.stream。分割(数据长度)—将数据分成两个chunk，第一个chunk为指定长度的chunk。成功拆分后，原始数据不再可用作TCP数据流。任何以这种方式使用它的尝试都会导致错误。
  • ns.tcp.stream。字节(data[， I [， j]])-函数类似于Lua的string.byte。返回字符data[i]， data[i+1]，…，data[j]的内部数值代码。
  • ns.tcp.stream。Sub (data, I [， j])-函数类似于Lua的string.sub。返回s的子字符串，从i开始，一直到j。
  • ns.tcp.stream。匹配(data, pattern, [, init])-函数类似于Lua的string.match。寻找第一个匹配字符串s的模式。

• ns。发送(processing_ctxt, event_name, event_data)将事件发送到处理上下文的通用函数。事件数据是一个可以包含任何内容的Lua表。内容取决于事件。在调用ns.send() API之后，数据引用就不再可用了。任何使用它的尝试都会导致错误。

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