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
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, выпущенный 6 сентября 2021 года.
Синопсис
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
Присваивает значение аргумента <src>, если переменная $dst пуста (т.е. не найдена или имеет пустое строковое значение).
В следующем примере,
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
При передаче двух аргументов эта директива экранирует значение второго аргумента <src> по правилам экранирования строк MySQL и присваивает результат первому аргументу, переменной $dst. Например,
location /test {
set $value "hello\n\r'\"\\";
set_quote_sql_str $quoted $value;
echo $quoted;
}
Тогда запрос GET /test вернет следующий вывод
'hello\n\r\'\"\\'
Обратите внимание, что мы используем echo-nginx-module's echo directive здесь для прямого вывода значений переменных nginx.
При передаче одного аргумента эта директива будет выполнять модификацию аргументной переменной на месте. Например,
location /test {
set $value "hello\n\r'\"\\";
set_quote_sql_str $value;
echo $value;
}
Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.
Эта директива обычно используется для предотвращения SQL-инъекций.
Эта директива может быть вызвана интерфейсом lua-nginx-module's ndk.set_var.DIRECTIVE и директивой array-var-nginx-module's 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
При передаче двух аргументов эта директива экранирует значение второго аргумента <src> по правилам экранирования строк JSON и присваивает результат первому аргументу, переменной $dst. Например,
location /test {
set $value "hello\n\r'\"\\";
set_quote_json_str $quoted $value;
echo $quoted;
}
Тогда запрос GET /test вернет следующий вывод
"hello\n\r'\"\\"
Обратите внимание, что мы используем echo-nginx-module's echo directive здесь для прямого вывода значений переменных nginx.
При передаче одного аргумента эта директива будет выполнять модификацию аргументной переменной на месте. Например,
location /test {
set $value "hello\n\r'\"\\";
set_quote_json_str $value;
echo $value;
}
Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.
Эта директива может быть вызвана интерфейсом lua-nginx-module's ndk.set_var.DIRECTIVE и директивой array-var-nginx-module's 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's echo directive здесь для прямого вывода значений переменных nginx.
При передаче одного аргумента эта директива будет выполнять модификацию аргументной переменной на месте. Например,
location /test {
set $key $arg_key;
set_unescape_uri $key;
echo $key;
}
Тогда запрос GET /test?key=hello+world%21 даст точно такой же вывод, как в предыдущем примере.
Эта директива может быть вызвана интерфейсом lua-nginx-module's ndk.set_var.DIRECTIVE и директивой array-var-nginx-module's 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, включенных в список upstream с именем <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.
Эта директива обычно используется для вычисления переменной nginx, которая будет передана директиве memc-nginx-module's memc_pass, директиве redis2-nginx-module's [[HttpRedis2Module#redis2_pass]] и директиве ngx_http_proxy_module's 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's echo directive здесь для прямого вывода значений переменных 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's ndk.set_var.DIRECTIVE и директивой array-var-nginx-module's array_map_op.
set_base32_padding
синтаксис: set_base32_padding on|off
по умолчанию: on
контекст: http, server, server if, location, location if
фаза: нет
Эта директива может контролировать, нужно ли дополнить оставшиеся байты символом "=" при кодировании base32 дайджеста с помощью директивы set_encode_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. Используйте set_base32_padding вместо этого, если вы используете v0.28+.
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's echo directive здесь для прямого вывода значений переменных nginx.
При передаче одного аргумента эта директива будет выполнять модификацию аргументной переменной на месте. Например,
location /test {
set $value "abcde";
set_encode_base64 $value;
echo $value;
}
Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.
Эта директива может быть вызвана интерфейсом lua-nginx-module's ndk.set_var.DIRECTIVE и директивой array-var-nginx-module's array_map_op.
set_encode_base64url
синтаксис: set_encode_base64url $dst <src>
синтаксис: set_encode_base64url $dst
по умолчанию: нет
контекст: location, location if
фаза: rewrite
категория: ndk_set_var_value
При передаче двух аргументов эта директива кодирует значение второго аргумента <src> в его безопасный для URL base64 дайджест и присваивает результат первому аргументу, переменной $dst. Например,
location /test {
set $raw "abcde";
set_encode_base64url $digest $raw;
echo $digest;
}
Тогда запрос GET /test вернет следующий вывод
YWJjZGU=
Обратите внимание, что мы используем echo-nginx-module's echo directive здесь для прямого вывода значений переменных nginx.
При передаче одного аргумента эта директива будет выполнять модификацию аргументной переменной на месте. Например,
location /test {
set $value "abcde";
set_encode_base64url $value;
echo $value;
}
Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.
Эта директива может быть вызвана интерфейсом lua-nginx-module's ndk.set_var.DIRECTIVE и директивой array-var-nginx-module's 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, но выполняет точно противоположную операцию, т.е. декодирует безопасный для URL base64 дайджест в его исходную форму.
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's echo directive здесь для прямого вывода значений переменных nginx.
При передаче одного аргумента эта директива будет выполнять модификацию аргументной переменной на месте. Например,
location /test {
set $value "章亦春";
set_encode_hex $value;
echo $value;
}
Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.
Эта директива может быть вызвана интерфейсом lua-nginx-module's ndk.set_var.DIRECTIVE и директивой array-var-nginx-module's 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 будет сгенерирована автоматически, используйте set_decode_hex, чтобы декодировать результат, если вы хотите бинарную форму дайджеста SHA-1.
Например,
location /test {
set $raw "hello";
set_sha1 $digest $raw;
echo $digest;
}
Тогда запрос GET /test вернет следующий вывод
aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
Обратите внимание, что мы используем echo-nginx-module's echo directive здесь для прямого вывода значений переменных nginx.
При передаче одного аргумента эта директива будет выполнять модификацию аргументной переменной на месте. Например,
location /test {
set $value "hello";
set_sha1 $value;
echo $value;
}
Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.
Эта директива может быть вызвана интерфейсом lua-nginx-module's ndk.set_var.DIRECTIVE и директивой array-var-nginx-module's array_map_op.
set_md5
синтаксис: set_md5 $dst <src>
синтаксис: set_md5 $dst
по умолчанию: нет
контекст: location, location if
фаза: rewrite
категория: ndk_set_var_value
При передаче двух аргументов эта директива кодирует значение второго аргумента <src> в его MD5 дайджест и присваивает результат первому аргументу, переменной $dst. Шестнадцатеричная форма дайджеста MD5 будет сгенерирована автоматически, используйте set_decode_hex, чтобы декодировать результат, если вы хотите бинарную форму дайджеста MD5.
Например,
location /test {
set $raw "hello";
set_md5 $digest $raw;
echo $digest;
}
Тогда запрос GET /test вернет следующий вывод
5d41402abc4b2a76b9719d911017c592
Обратите внимание, что мы используем echo-nginx-module's echo directive здесь для прямого вывода значений переменных nginx.
При передаче одного аргумента эта директива будет выполнять модификацию аргументной переменной на месте. Например,
location /test {
set $value "hello";
set_md5 $value;
echo $value;
}
Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.
Эта директива может быть вызвана интерфейсом lua-nginx-module's ndk.set_var.DIRECTIVE и директивой array-var-nginx-module's array_map_op.
set_hmac_sha1
синтаксис: set_hmac_sha1 $dst <secret_key> <src>
синтаксис: set_hmac_sha1 $dst
по умолчанию: нет
контекст: location, location if
фаза: rewrite
Вычисляет дайджест HMAC-SHA1 аргумента <src> и присваивает результат переменной $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's echo directive здесь для прямого вывода значений переменных nginx.
Эта директива требует, чтобы библиотека OpenSSL была включена в вашу сборку Nginx (обычно путем передачи опции --with-http_ssl_module в скрипт ./configure).
set_hmac_sha256
синтаксис: set_hmac_sha256 $dst <secret_key> <src>
синтаксис: set_hmac_sha256 $dst
по умолчанию: нет
контекст: location, location if
фаза: rewrite
Вычисляет дайджест HMAC-SHA256 аргумента <src> и присваивает результат переменной $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's echo directive здесь для прямого вывода значений переменных nginx.
Эта директива требует, чтобы библиотека OpenSSL была включена в вашу сборку Nginx (обычно путем передачи опции --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
и год, фактическая дата, которую вы получите здесь, будет варьироваться каждый день ;)
За кулисами эта директива использует API ngx_time в ядре Nginx, поэтому обычно не происходит системного вызова из-за механизма кэширования времени в ядре 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:
Тестовый набор
Этот модуль поставляется с тестовым набором на основе Perl. Тестовые случаи также являются декларативными. Спасибо модулю Test::Nginx в мире Perl.
Чтобы запустить его у себя:
$ PATH=/path/to/your/nginx-with-set-misc-module:$PATH prove -r t
Вам нужно завершить любые процессы Nginx перед запуском тестового набора, если вы изменили бинарный файл сервера Nginx.
Поскольку один сервер nginx (по умолчанию, localhost:1984) используется во всех тестовых скриптах (.t файлы), бессмысленно запускать тестовый набор параллельно, указывая -jN, когда вы вызываете утилиту prove.
См. также
GitHub
Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-set-misc.