set-misc: NGINX Set-Misc 模块

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

RedHat Enterprise Linux 7、8、9 和 10
CentOS 7、8、9
AlmaLinux 8、9
Rocky Linux 8、9
Amazon Linux 2 和 Amazon Linux 2023

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-set-misc

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-set-misc

通过在 /etc/nginx/nginx.conf 的顶部添加以下内容来启用该模块：

load_module modules/ngx_http_set_misc_module.so;

本文档描述了 nginx-module-set-misc v0.33，于 2021 年 9 月 6 日发布。

概述

 location /foo {
     set $a $arg_a;
     set_if_empty $a 56;

     # GET /foo?a=32 将返回 $a == 32
     # 而 GET /foo 和 GET /foo?a= 将
     # 返回 $a == 56。
 }

 location /bar {
     set $foo "hello\n\n'\"\\";
     set_quote_sql_str $foo $foo; # 用于 mysql

     # 或者就地编辑：
     #   set_quote_sql_str $foo;

     # 现在 $foo 是： 'hello\n\n\'\"\\'
 }

 location /bar {
     set $foo "hello\n\n'\"\\";
     set_quote_pgsql_str $foo;  # 用于 PostgreSQL

     # 现在 $foo 是： E'hello\n\n\'\"\\'
 }

 location /json {
     set $foo "hello\n\n'\"\\";
     set_quote_json_str $foo $foo;

     # 或者就地编辑：
     #   set_quote_json_str $foo;

     # 现在 $foo 是： "hello\n\n'\"\\"
 }

 location /baz {
     set $foo "hello%20world";
     set_unescape_uri $foo $foo;

     # 或者就地编辑：
     #   set_unescape_uri $foo;

     # 现在 $foo 是： hello world
 }

 upstream_list universe moon sun earth;
 upstream moon { ... }
 upstream sun { ... }
 upstream earth { ... }
 location /foo {
     set_hashed_upstream $backend universe $arg_id;
     drizzle_pass $backend; # 与 ngx_drizzle 一起使用
 }

 location /base32 {
     set $a 'abcde';
     set_encode_base32 $a;
     set_decode_base32 $b $a;

     # 现在 $a == 'c5h66p35' 并且
     # $b == 'abcde'
 }

 location /base64 {
     set $a 'abcde';
     set_encode_base64 $a;
     set_decode_base64 $b $a;

     # 现在 $a == 'YWJjZGU=' 并且
     # $b == 'abcde'
 }

 location /hex {
     set $a 'abcde';
     set_encode_hex $a;
     set_decode_hex $b $a;

     # 现在 $a == '6162636465' 并且
     # $b == 'abcde'
 }

 # GET /sha1 返回的输出为
 #   aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
 location /sha1 {
     set_sha1 $a hello;
     echo $a;
 }

 # 同上
 location /sha1 {
     set $a hello;
     set_sha1 $a;
     echo $a;
 }

 # GET /today 返回今天的日期，格式为 'yyyy-mm-dd'
 location /today {
     set_local_today $today;
     echo $today;
 }

 # GET /signature 返回 hmac-sha-1 签名
 # 给定一个密钥和一个待签名的字符串
 # 此示例返回的 base64 编码签名为
 # "HkADYytcoQQzqbjQX33k/ZBB/DQ="
 location /signature {
     set $secret_key 'secret-key';
     set $string_to_sign "some-string-to-sign";
     set_hmac_sha1 $signature $secret_key $string_to_sign;
     set_encode_base64 $signature $signature;
     echo $signature;
 }

 location = /rand {
     set $from 3;
     set $to 15;
     set_random $rand $from $to;

     # 或者直接写
     #   set_random $rand 3 15;

     echo $rand;  # 将打印范围 [3, 15] 内的随机整数
 }

描述

此模块扩展了标准 HttpRewriteModule 的指令集，以提供更多功能，如 URI 转义和解转义、JSON 引号、十六进制/MD5/SHA1/Base32/Base64 摘要编码和解码、随机数生成等！

此模块提供的每个指令可以与其他 ngx_http_rewrite_module 的指令自由混合，如 if 和 set。（感谢 Nginx Devel Kit！）

指令

set_if_empty

语法： set_if_empty $dst <src>

默认值： 无

上下文： location, location if

阶段： rewrite

仅当变量 $dst 为空（即未找到或具有空字符串值）时，才将参数 <src> 的值分配给它。

在以下示例中，

 set $a 32;
 set_if_empty $a 56;

变量 $dst 最终将取值 32。但在示例中

 set $a '';
 set $value "hello, world"
 set_if_empty $a $value;

$a 最终将取值为 "hello, world"。

set_quote_sql_str

语法： set_quote_sql_str $dst <src>

语法： set_quote_sql_str $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

当接受两个参数时，此指令将根据 MySQL 的字符串值引用规则对第二个参数 <src> 的值进行引用，并将结果分配给第一个参数，即变量 $dst。例如，

 location /test {
     set $value "hello\n\r'\"\\";
     set_quote_sql_str $quoted $value;

     echo $quoted;
 }

然后请求 GET /test 将产生以下输出

 'hello\n\r\'\"\\'

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

当接受一个参数时，此指令将对参数变量进行就地修改。例如，

 location /test {
     set $value "hello\n\r'\"\\";
     set_quote_sql_str $value;

     echo $value;
 }

然后请求 GET /test 将给出与前一个示例完全相同的输出。

此指令通常用于防止 SQL 注入。

此指令可以通过 lua-nginx-module 的 ndk.set_var.DIRECTIVE 接口和 array-var-nginx-module 的 array_map_op 指令调用。

set_quote_pgsql_str

语法： set_quote_pgsql_str $dst <src>

语法： set_quote_pgsql_str $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

与 set_quote_sql_str 非常相似，但使用 PostgreSQL 的 SQL 字符串文字引用规则。

set_quote_json_str

语法： set_quote_json_str $dst <src>

语法： set_quote_json_str $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

当接受两个参数时，此指令将根据 JSON 字符串值引用规则对第二个参数 <src> 的值进行引用，并将结果分配给第一个参数，即变量 $dst。例如，

 location /test {
     set $value "hello\n\r'\"\\";
     set_quote_json_str $quoted $value;

     echo $quoted;
 }

然后请求 GET /test 将产生以下输出

 "hello\n\r'\"\\"

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

当接受一个参数时，此指令将对参数变量进行就地修改。例如，

 location /test {
     set $value "hello\n\r'\"\\";
     set_quote_json_str $value;

     echo $value;
 }

然后请求 GET /test 将给出与前一个示例完全相同的输出。

此指令可以通过 lua-nginx-module 的 ndk.set_var.DIRECTIVE 接口和 array-var-nginx-module 的 array_map_op 指令调用。

set_unescape_uri

语法： set_unescape_uri $dst <src>

语法： set_unescape_uri $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

当接受两个参数时，此指令将对第二个参数 <src> 的值进行 URI 组件解转义，并将结果分配给第一个参数，即变量 $dst。例如，

 location /test {
     set_unescape_uri $key $arg_key;
     echo $key;
 }

然后请求 GET /test?key=hello+world%21 将产生以下输出

hello world!

nginx 标准的 $arg_PARAMETER 变量保存了 URI 参数的原始（转义）值。因此，我们需要首先使用 set_unescape_uri 指令进行解转义。

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

当接受一个参数时，此指令将对参数变量进行就地修改。例如，

 location /test {
     set $key $arg_key;
     set_unescape_uri $key;

     echo $key;
 }

然后请求 GET /test?key=hello+world%21 将给出与前一个示例完全相同的输出。

此指令可以通过 lua-nginx-module 的 ndk.set_var.DIRECTIVE 接口和 array-var-nginx-module 的 array_map_op 指令调用。

set_escape_uri

语法： set_escape_uri $dst <src>

语法： set_escape_uri $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

与 set_unescape_uri 指令非常相似，但进行相反的转换，即 URL 组件转义。

set_hashed_upstream

语法： set_hashed_upstream $dst <upstream_list_name> <src>

默认值： 无

上下文： location, location if

阶段： rewrite

将字符串参数 <src> 哈希到包含在名为 <upstream_list_name> 的上游列表中的一个上游名称。使用的哈希函数是简单的取模。

以下是一个示例，

 upstream moon { ... }
 upstream sun { ... }
 upstream earth { ... }

 upstream_list universe moon sun earth;

 location /test {
     set_unescape_uri $key $arg_key;
     set $list_name universe;
     set_hashed_upstream $backend $list_name $key;

     echo $backend;
 }

然后 GET /test?key=blah 将输出 "moon"、"sun" 或 "earth"，具体取决于 key 查询参数的实际值。

此指令通常用于计算要传递给 memc-nginx-module 的 memc_pass 指令、redis2-nginx-module 的 [[HttpRedis2Module#redis2_pass]] 指令，以及 ngx_http_proxy_module 的 proxy_pass 指令等。

set_encode_base32

语法： set_encode_base32 $dst <src>

语法： set_encode_base32 $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

当接受两个参数时，此指令将第二个参数 <src> 的值编码为其 base32(hex) 摘要，并将结果分配给第一个参数，即变量 $dst。例如，

 location /test {
     set $raw "abcde";
     set_encode_base32 $digest $raw;

     echo $digest;
 }

然后请求 GET /test 将产生以下输出

c5h66p35

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

RFC 强制使用 [A-Z2-7] 的 RFC-3548 兼容编码，但我们默认使用 "base32hex" 编码（[0-9a-v]）。set_base32_alphabet 指令（首次在 v0.28 中引入）允许您更改用于编码/解码的字母表，因此仍然可以通过自定义配置实现 RFC-3548 兼容编码。

默认情况下，= 字符用于填充由于对齐而剩余的字节。但是，通过将 set_base32_padding 设置为 off，可以完全禁用填充行为。

当接受一个参数时，此指令将对参数变量进行就地修改。例如，

 location /test {
     set $value "abcde";
     set_encode_base32 $value;

     echo $value;
 }

然后请求 GET /test 将给出与前一个示例完全相同的输出。

此指令可以通过 lua-nginx-module 的 ndk.set_var.DIRECTIVE 接口和 array-var-nginx-module 的 array_map_op 指令调用。

set_base32_padding

语法： set_base32_padding on|off

默认值： on

上下文： http, server, server if, location, location if

阶段： 无

此指令可以控制在通过 set_encode_base32 指令编码 base32 摘要时，是否用 "=" 字符填充剩余字节。

此指令首次在 v0.28 中引入。如果您使用该模块的早期版本，则应使用 set_misc_base32_padding。

set_misc_base32_padding

语法： set_misc_base32_padding on|off

默认值： on

上下文： http, server, server if, location, location if

阶段： 无

此指令自 v0.28 起已被弃用。如果您使用 v0.28+，请改用 set_base32_padding。

set_base32_alphabet

语法： set_base32_alphabet <alphabet>

默认值： "0123456789abcdefghijklmnopqrstuv"

上下文： http, server, server if, location, location if

阶段： 无

此指令控制用于编码/解码 base32 摘要的字母表。它接受一个包含所需字母表的字符串，例如 "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567" 用于标准字母表。

默认使用扩展（base32hex）字母表。

此指令首次在 v0.28 中引入。

set_decode_base32

语法： set_decode_base32 $dst <src>

语法： set_decode_base32 $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

类似于 set_encode_base32 指令，但执行完全相反的操作，即将 base32(hex) 摘要解码为其原始形式。

set_encode_base64

语法： set_encode_base64 $dst <src>

语法： set_encode_base64 $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

当接受两个参数时，此指令将第二个参数 <src> 的值编码为其 base64 摘要，并将结果分配给第一个参数，即变量 $dst。例如，

 location /test {
     set $raw "abcde";
     set_encode_base64 $digest $raw;

     echo $digest;
 }

然后请求 GET /test 将产生以下输出

YWJjZGU=

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

当接受一个参数时，此指令将对参数变量进行就地修改。例如，

 location /test {
     set $value "abcde";
     set_encode_base64 $value;

     echo $value;
 }

然后请求 GET /test 将给出与前一个示例完全相同的输出。

此指令可以通过 lua-nginx-module 的 ndk.set_var.DIRECTIVE 接口和 array-var-nginx-module 的 array_map_op 指令调用。

set_encode_base64url

语法： set_encode_base64url $dst <src>

语法： set_encode_base64url $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

当接受两个参数时，此指令将第二个参数 <src> 的值编码为其 base64 URL 安全摘要，并将结果分配给第一个参数，即变量 $dst。例如，

 location /test {
     set $raw "abcde";
     set_encode_base64url $digest $raw;

     echo $digest;
 }

然后请求 GET /test 将产生以下输出

YWJjZGU=

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

当接受一个参数时，此指令将对参数变量进行就地修改。例如，

 location /test {
     set $value "abcde";
     set_encode_base64url $value;

     echo $value;
 }

然后请求 GET /test 将给出与前一个示例完全相同的输出。

此指令可以通过 lua-nginx-module 的 ndk.set_var.DIRECTIVE 接口和 array-var-nginx-module 的 array_map_op 指令调用。

set_decode_base64

语法： set_decode_base64 $dst <src>

语法： set_decode_base64 $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

类似于 set_encode_base64 指令，但执行完全相反的操作，即将 base64 摘要解码为其原始形式。

set_decode_base64url

语法： set_decode_base64url $dst <src>

语法： set_decode_base64url $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

类似于 set_encode_base64url 指令，但执行完全相反的操作，即将 base64 URL 安全摘要解码为其原始形式。

set_encode_hex

语法： set_encode_hex $dst <src>

语法： set_encode_hex $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

当接受两个参数时，此指令将第二个参数 <src> 的值编码为其十六进制摘要，并将结果分配给第一个参数，即变量 $dst。例如，

 location /test {
     set $raw "章亦春";
     set_encode_hex $digest $raw;

     echo $digest;
 }

然后请求 GET /test 将产生以下输出

e7aba0e4baa6e698a5

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

当接受一个参数时，此指令将对参数变量进行就地修改。例如，

 location /test {
     set $value "章亦春";
     set_encode_hex $value;

     echo $value;
 }

然后请求 GET /test 将给出与前一个示例完全相同的输出。

此指令可以通过 lua-nginx-module 的 ndk.set_var.DIRECTIVE 接口和 array-var-nginx-module 的 array_map_op 指令调用。

set_decode_hex

语法： set_decode_hex $dst <src>

语法： set_decode_hex $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

类似于 set_encode_hex 指令，但执行完全相反的操作，即将十六进制摘要解码为其原始形式。

set_sha1

语法： set_sha1 $dst <src>

语法： set_sha1 $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

当接受两个参数时，此指令将第二个参数 <src> 的值编码为其 SHA-1 摘要，并将结果分配给第一个参数，即变量 $dst。SHA-1 摘要的十六进制形式将自动生成，如果您想要 SHA-1 摘要的二进制形式，请使用 set_decode_hex 解码结果。

例如，

 location /test {
     set $raw "hello";
     set_sha1 $digest $raw;

     echo $digest;
 }

然后请求 GET /test 将产生以下输出

aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

当接受一个参数时，此指令将对参数变量进行就地修改。例如，

 location /test {
     set $value "hello";
     set_sha1 $value;

     echo $value;
 }

然后请求 GET /test 将给出与前一个示例完全相同的输出。

此指令可以通过 lua-nginx-module 的 ndk.set_var.DIRECTIVE 接口和 array-var-nginx-module 的 array_map_op 指令调用。

set_md5

语法： set_md5 $dst <src>

语法： set_md5 $dst

默认值： 无

上下文： location, location if

阶段： rewrite

类别： ndk_set_var_value

当接受两个参数时，此指令将第二个参数 <src> 的值编码为其 MD5 摘要，并将结果分配给第一个参数，即变量 $dst。MD5 摘要的十六进制形式将自动生成，如果您想要 MD5 摘要的二进制形式，请使用 set_decode_hex 解码结果。

例如，

 location /test {
     set $raw "hello";
     set_md5 $digest $raw;

     echo $digest;
 }

然后请求 GET /test 将产生以下输出

5d41402abc4b2a76b9719d911017c592

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

当接受一个参数时，此指令将对参数变量进行就地修改。例如，

 location /test {
     set $value "hello";
     set_md5 $value;

     echo $value;
 }

然后请求 GET /test 将给出与前一个示例完全相同的输出。

此指令可以通过 lua-nginx-module 的 ndk.set_var.DIRECTIVE 接口和 array-var-nginx-module 的 array_map_op 指令调用。

set_hmac_sha1

语法： set_hmac_sha1 $dst <secret_key> <src>

语法： set_hmac_sha1 $dst

默认值： 无

上下文： location, location if

阶段： rewrite

计算参数 <src> 的 HMAC-SHA1 摘要，并将结果分配给参数变量 $dst，使用的密钥为 <secret_key>。

将生成 HMAC-SHA1 摘要的原始二进制形式，如果需要，可以使用 set_encode_base64 将结果编码为文本表示形式。

例如，

 location /test {
     set $secret 'thisisverysecretstuff';
     set $string_to_sign 'some string we want to sign';
     set_hmac_sha1 $signature $secret $string_to_sign;
     set_encode_base64 $signature $signature;
     echo $signature;
 }

然后请求 GET /test 将产生以下输出

R/pvxzHC4NLtj7S+kXFg/NePTmk=

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

此指令要求在您的 Nginx 构建中启用 OpenSSL 库（通常通过将 --with-http_ssl_module 选项传递给 ./configure 脚本）。

set_hmac_sha256

语法： set_hmac_sha256 $dst <secret_key> <src>

语法： set_hmac_sha256 $dst

默认值： 无

上下文： location, location if

阶段： rewrite

计算参数 <src> 的 HMAC-SHA256 摘要，并将结果分配给参数变量 $dst，使用的密钥为 <secret_key>。

将生成 HMAC-SHA256 摘要的原始二进制形式，如果需要，可以使用 set_encode_base64 将结果编码为文本表示形式。

例如，

 location /test {
     set $secret 'thisisverysecretstuff';
     set $string_to_sign 'some string we want to sign';
     set_hmac_sha256 $signature $secret $string_to_sign;
     set_encode_base64 $signature $signature;
     echo $signature;
 }

然后请求 GET /test 将产生以下输出

4pU3GRQrKKIoeLb9CqYsavHE2l6Hx+KMmRmesU+Cfrs=

请注意，我们在这里使用 echo-nginx-module 的 echo 指令直接输出 nginx 变量的值。

此指令要求在您的 Nginx 构建中启用 OpenSSL 库（通常通过将 --with-http_ssl_module 选项传递给 ./configure 脚本）。

set_random

语法： set_random $res <from> <to>

默认值： 无

上下文： location, location if

阶段： rewrite

生成范围 [<$from>, <$to>]（包含）的（伪）随机数（以文本形式）。

<from> 和 <to> 参数仅允许非负数。

当 <from> 大于 <to> 时，将相应地交换它们的值。

例如，

 location /test {
     set $from 5;
     set $to 7;
     set_random $res $from $to;

     echo $res;
 }

然后请求 GET /test 将输出 5 到 7 之间的数字（即 5、6、7 中的一个）。

目前，没有办法配置自定义随机生成器种子。

在幕后，它使用标准 C 函数 rand()。

此指令首次在 v0.22rc1 版本中引入。

另请参见 set_secure_random_alphanum 和 set_secure_random_lcalpha。

set_secure_random_alphanum

语法： set_secure_random_alphanum $res <length>

默认值： 无

上下文： location, location if

阶段： rewrite

生成一个长度为 <length> 的密码学强随机字符串，字母表为 [a-zA-Z0-9]。

<length> 可以在 1 到 64 之间（包含）。

例如，

 location /test {
     set_secure_random_alphanum $res 32;

     echo $res;
 }

然后请求 GET /test 将输出类似 ivVVRP2DGaAqDmdf3Rv4ZDJ7k0gOfASz 的字符串。

此功能依赖于 /dev/urandom 设备的存在，该设备在大多数类 UNIX 系统上可用。

另请参见 set_secure_random_lcalpha 和 set_random。

此指令首次在 v0.22rc8 版本中引入。

set_secure_random_lcalpha

语法： set_secure_random_lcalpha $res <length>

默认值： 无

上下文： location, location if

阶段： rewrite

生成一个长度为 <length> 的密码学强随机字符串，字母表为 [a-z]。

<length> 可以在 1 到 64 之间（包含）。

例如，

 location /test {
     set_secure_random_lcalpha $res 32;

     echo $res;
 }

然后请求 GET /test 将输出类似 kcuxcddktffsippuekhshdaclaquiusj 的字符串。

此功能依赖于 /dev/urandom 设备的存在，该设备在大多数类 UNIX 系统上可用。

此指令首次在 v0.22rc8 版本中引入。

另请参见 set_secure_random_alphanum 和 set_random。

set_rotate

语法： set_rotate $value <from> <to>

默认值： 无

上下文： location, location if

阶段： rewrite

递增 $value，但保持在 <from> 到 <to> 的范围内。如果 $value 大于 <to> 或小于 <from>，则将其设置为 <from> 值。

运行此指令后，当前值将始终按位置保存。并且当 $value 未初始化或具有不良值时，将使用此保存的值进行递增。

<from> 和 <to> 参数仅允许非负数。

当 <from> 大于 <to> 时，将相应地交换它们的值。

例如，

 location /rotate {
     default_type text/plain;
     set $counter $cookie_counter;
     set_rotate $counter 1 5;
     echo $counter;
     add_header Set-Cookie counter=$counter;
 }

然后请求 GET /rotate 将在每次刷新页面时输出 1 到 5 之间的下一个数字（即 1、2、3、4、5）。此指令可能对横幅轮换目的有用。

另一个示例是使用服务器端值持久性进行简单的轮询：

 location /rotate {
     default_type text/plain;
     set_rotate $counter 0 3;
     echo $counter;
 }

访问 /rotate 也将输出整数序列 0、1、2、3、0、1、2、3，依此类推。

此指令首次在 v0.22rc7 版本中引入。

set_local_today

语法： set_local_today $dst

默认值： 无

上下文： location, location if

阶段： rewrite

将今天的日期（"yyyy-mm-dd"）以当地时间设置到参数变量 $dst。

以下是一个示例，

 location /today {
     set_local_today $today;
     echo $today;
 }

然后请求 GET /today 将输出类似

2011-08-16

实际日期将每天变化 ;)

在幕后，此指令利用了 Nginx 核心中的 ngx_time API，因此通常不会由于 Nginx 核心中的时间缓存机制而涉及系统调用。

set_formatted_gmt_time

语法： set_formatted_gmt_time $res <time-format>

默认值： 无

上下文： location, location if

阶段： rewrite

将格式化的 GMT 时间设置到变量 $res（作为第一个参数），使用第二个参数中的格式字符串。

支持标准 C 函数 strftime 中的所有转换规范符号，如 %Y（用于 4 位年份）和 %M（用于十进制分钟）。有关完整的转换规范符号列表，请参见 http://linux.die.net/man/3/strftime。

以下是一个示例：

 location = /t {
     set_formatted_gmt_time $timestr "%a %b %e %H:%M:%S %Y GMT";
     echo $timestr;
 }

访问 /t 将产生以下输出

Fri Dec 13 15:34:37 2013 GMT

此指令首次在 0.23 版本中添加。

另请参见 set_formatted_local_time。

set_formatted_local_time

语法： set_formatted_local_time $res <time-format>

默认值： 无

上下文： location, location if

阶段： rewrite

将格式化的当地时间设置到变量 $res（作为第一个参数），使用第二个参数中的格式字符串。

支持标准 C 函数 strftime 中的所有转换规范符号，如 %Y（用于 4 位年份）和 %M（用于十进制分钟）。有关完整的转换规范符号列表，请参见 http://linux.die.net/man/3/strftime。

以下是一个示例：

 location = /t {
     set_formatted_local_time $timestr "%a %b %e %H:%M:%S %Y %Z";
     echo $timestr;
 }

访问 /t 将产生以下输出

Fri Dec 13 15:42:15 2013 PST

此指令首次在 0.23 版本中添加。

另请参见 set_formatted_gmt_time。

注意事项

请勿在此模块的指令中使用 $arg_PARAMETER、$cookie_COOKIE、$http_HEADER 或其他在 Nginx 核心模块中定义的特殊变量作为目标变量。例如，

 set_if_empty $arg_user 'foo';  # 不要使用这个！

可能会导致段错误。

变更

此模块每个版本的变更日志可以从 OpenResty 包的变更日志中获取：

http://openresty.org/#Changes

测试套件

此模块附带一个 Perl 驱动的测试套件。测试用例也是声明式的。感谢 Perl 领域的 Test::Nginx 模块。

要在您的环境中运行它：

 $ PATH=/path/to/your/nginx-with-set-misc-module:$PATH prove -r t

如果您更改了 Nginx 服务器二进制文件，则需要在运行测试套件之前终止任何 Nginx 进程。

由于所有测试脚本（.t 文件）都使用单个 nginx 服务器（默认情况下为 localhost:1984），因此在调用 prove 工具时指定 -jN 并行运行测试套件是没有意义的。

另请参见

GitHub

您可以在 GitHub nginx-module-set-misc 的代码库中找到此模块的其他配置提示和文档。