本主题将详细介绍 DataScript 实用程序函数的规范。
DataScript 中提供了以下实用程序函数：
函数 |
描述 |
|---|---|
解码内容 |
|
编码内容 |
|
用于提取地理位置数据库信息 |
|
接受 IP 地址和网络掩码并返回网络地址 |
|
avi.utils.murmur_hash ( string)、avi.utils.sha1_hash (string)、avi.utils.md5_hash (string) |
对内容执行哈希处理 |
生成加密的安全随机字节 |
|
用于检查给定 IP 地址的 IP 信誉 |
|
avi.utils.ip_in_subnet |
用于求值 IP 地址网络掩码。 |
DataScript 可以使用支持相应命名哈希方法的三个函数之一对任意数据进行哈希处理：MurmurHash、SHA-1 和 MD5。有关更多信息，请参阅 DataScript：avi.utils.murmur_hash ( string)、avi.utils.sha1_hash (string) 和 avi.utils.md5_hash (string)。
avi.utils.base64_decode
函数 |
avi.utils.base64_decode( string ) |
描述 |
DataScript 可以使用 base64 对任意数据进行编码和解码。这可用于修改通过线路发送的数据，或者用于检查和安全用例。 |
事件 |
|
参数 |
string 是要解码的字符串。 |
返回 |
已解码的字符串 |
相关 |
avi.utils.base64_encode() |
示例 |
以下示例将获取 HTTP 基本身份验证用户名，并将其作为用户 ID 标记添加到 VMware NSX Advanced Load Balancer 中，可用于日志搜索、持久性或访问控制。 if string.beginswith(avi.http.get_header("Authorization"), "Basic ") then
auth = string.sub(avi.http.get_header("Authorization"), 7)
decoded = avi.utils.base64_decode(auth)
username = string.sub(decoded, 0, string.find(decoded, ":") - 1)
avi.http.set_userid(username)
end |
avi.utils.base64_encode
函数 |
avi.utils.base64_encode( string ) |
描述 |
DataScript 可以使用 base64 对任意数据进行编码和解码。这可用于修改通过线路发送的数据，或者用于检查和安全用例。 |
事件 |
|
参数 |
string 是要编码的字符串。 |
返回 |
已编码的字符串 |
相关 |
avi.utils.base64_decode() |
avi.utils.get_geo_from_ip
NSX Advanced Load Balancer 包括一个地理位置数据库以确定客户端的来源。此固定数据库基于 MaxMind IP-country 和 IP-autonomous system 编号 (ASN) 数据。该数据库是在 NSX Advanced Load Balancer 控制器 上维护的，并在升级控制器时合并数据库更新。
DataScript 函数 avi.utils.get_geo_from_ip 用于检索所查询 IP 地址的地理位置信息、自治系统 (autonomous system, AS) 编号、国家/地区代码以及位置（纬度、经度、区域和城市）。
用于此 API 的数据库相当于 NSX Advanced Load Balancer 控制器 上维护的默认数据库，无法使用 IP 组进行覆盖或扩充，如“地理位置数据库”中所述。
必须将 System-GeoDB 配置文件附加到使用函数 get_geo_from_ip 的虚拟服务 Datascript。
包含使用此函数的 DataScript 的 VSDataScriptSet 必须引用地理位置数据库。
函数 |
|
描述 |
对于给定的 IP 地址，将根据标记返回给定 IPv4/v6 地址 ip_string 的地理位置值。此值从地理位置数据库中检索。 |
必备条件 |
服务引擎中至少具有 4GB RAM 必须在使用它的服务引擎组上配置至少 100 MB 的额外共享内存。此内存量可以通过 SE 组中的 extra_shared_config_memory 参数进行设置，如下所示： [admin:example-ctrl]: > configure serviceenginegroup Default-Group extra_shared_config_memory 100 [admin:example-ctrl]: serviceenginegroup > save 需要重新启动此组中的 SE 才能使内存更改生效。 如果未设置此内存，则配置了使用此函数的 DataScript 的任何虚拟服务都将被置于故障状态。在 NSX Advanced Load Balancer UI 中，错误消息如下所示：  |
事件 |
所有 HTTP 事件 |
参数 |
|
返回 |
注：
用于此函数的数据库相当于 NSX Advanced Load Balancer 控制器 上维护的默认数据库。如地理位置数据库文章中所述，无法使用 IP 组进行覆盖或扩充。 |
示例 1 |
下面的 DataScript 将添加类似于以下内容的地理标头：
client_ip = avi.vs.client_ip()
asn = avi.utils.get_geo_from_ip(client_ip, "ASN")
geo_header = "not found"
if asn ~= nil then
geo_header = asn
end
avi.http.add_header("Geo", geo_header) |
示例 2 |
{ [“ATTRIBUTE_COUNTRY_CODE“] = “US“,
[“ATTRIBUTE_COUNTRY_NAME“] = “United States“,
[“ATTRIBUTE_CONTINENT_NAME“] = “North America“,
[“ATTRIBUTE_CONTINENT_CODE“] = “NA“,
[“ATTRIBUTE_LATITUDE“] = “37.3583“,
[“ATTRIBUTE_LONGITUDE“] = “-122.1081“,
[“ATTRIBUTE_USER_DEFINED_MAPPING“] = { [1] = “Example Mapping 1“, [2] = “Example Mapping 2", etc. }
} 国家/地区代码的长度精确限制为 2 个字符，区域/城市的上限分别为 36 个字符。 |
avi.utils.ip.netaddr
函数 |
avi.utils.ip.netaddr(ip_addr, netmask)) |
描述 |
接受 IPv4 或 IPv6 IP 地址和网络掩码，并返回网络地址。 |
事件 |
|
参数 |
|
返回 |
If
则函数返回 NIL 否则，函数会返回网络的 IPv6 或 IPv4 地址。 |
示例 |
avi.utils.ip.netaddr ("43.225.52.40", 24) 将返回 43.225.52.0 avi.utils.ip.netaddr ("2001:0db8:85a3:0000:0000:8a2e:0370:7334", 53) 将返回 1:2001:db8:85a3:: |
avi.utils.murmur_hash ()、avi.utils.sha1_hash () 和 avi.utils.md5_hash ()
函数 |
|
描述 |
DataScript 可以使用支持相应命名哈希方法的三个函数之一对任意数据进行哈希处理： |
事件 |
|
参数 |
|
返回 |
已哈希的字符串 |
示例 |
请考虑以下 5 行代码片段： if avi.http.get_path() == "/echo_listen_port" then
avi.vs.log("Murmur-hash = " .. avi.utils.murmur_hash("How is the weather?"))
avi.vs.log("SHA1-hash = " .. avi.utils.sha1_hash("How is the weather?"))
avi.vs.log("MD5-hash = " .. avi.utils.md5_hash("How is the weather?"))
end
[string "DS1"]:2: Murmur-hash = 2050936584 [string "DS1"]:3: SHA1-hash = 0171e8d98bf187af83fe7a9dbbb34ebc6629dcbe [string "DS1"]:4: MD5-hash = c4150a2ad26a0c6345041f11ba914661 |
avi.utils.rand_bytes
函数 |
|
描述 |
允许用户生成加密安全的随机数据字节。 |
事件 |
全部 |
参数 |
num_bytes 是介于 0 和 1024 之间的整数。 |
返回 |
包含 num_bytes 随机数据字节的字符串。
注：
Lua 将字符串定义为字节序列。因此，对 ASCII 范围内字节有效的操作同样对 ASCII 范围之外的字节有效。打印这些随机字节很可能会显示无法识别的字符。不能依赖诸如 math.random 之类的替代方法来返回加密安全的随机值，例如在创建 UUID 时可能需要的随机值。 |
示例 |
在 VS 应用程序日志中记录 8 个随机字节： random_bytes = avi.utils.rand_bytes(8) avi.vs.log(random_bytes) |
avi.utils.get_ip_reputation
可以通过 Lua 函数在 L7 DataScript 中使用 Webroot 数据库进行 IP 信誉检查。
is_good, reputation_type = avi.utils.get_ip_reputation(ip_addr)
is_good 的第一个返回值为 true/false。此值指示给定 IP 的信誉是否良好。
第二个返回的值为 IP 信誉类型的位图，只有在 is_good 为 false 才有效。例如，值 1 表示垃圾邮件源（第 0 位集合），值 17 表示 Spam Source and Scanner（第 0 位和第 4 位集合）。
有关更多信息，请参阅《VMware NSX Advanced Load BalancerWAF 指南》中的“IP 信誉”主题。
该函数将使用为 VSDataScriptSet 配置的 IP 信誉数据库。
您可以使用 API 或 CLI 将 VSDataScriptSet 配置为使用 IPReputationDB。
Lua 函数同时接受 IPv4 和 IPv6 地址。但是，它将始终为 IPv6 地址返回 true，因为 IP 信誉数据库当前仅包含 IPv4 地址信息。
ip_addr 参数的格式应为 avi.vs.client_ip() 返回的格式，这是一种表示格式，例如，1.2.3.4。
message VSDataScriptSet {
...
optional string ip_reputation_db_uuid = 58 [
(refers_to) = "IPReputationDB",
...
]
...
}
配置工作流
当脚本使用新的 avi.utils.get_ip_reputation(ip_addr) 函数时，应该在 VSDataScriptSet 级别配置 IPReputationDB。
