Перейти к содержанию

set-misc: Модуль NGINX Set-Misc

Установка на Debian/Ubuntu

Эти документы применимы к APT пакету nginx-module-set-misc, предоставляемого репозиторием GetPageSpeed Extras.

  1. Настройте APT репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-set-misc
Показать комплекты и архитектуры 
| Дистрибутив | Комплект           | Компонент | Архитектуры   |
|-------------|---------------------|-----------|----------------|
| debian      | bookworm            | main      | amd64, arm64   |
| debian      | bookworm-mainline   | main      | amd64, arm64   |
| debian      | trixie              | main      | amd64, arm64   |
| debian      | trixie-mainline     | main      | amd64, arm64   |
| ubuntu      | focal               | main      | amd64, arm64   |
| ubuntu      | focal-mainline      | main      | amd64, arm64   |
| ubuntu      | jammy               | main      | amd64, arm64   |
| ubuntu      | jammy-mainline      | main      | amd64, arm64   |
| ubuntu      | noble               | main      | amd64, arm64   |
| ubuntu      | noble-mainline      | main      | amd64, arm64   |

Название

ngx_set_misc - Различные директивы set_xxx, добавленные в модуль переопределения nginx (md5/sha1, sql/json экранирование и многое другое)

Синопсис

 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

фаза: переопределение

Присваивает значение аргумента <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

фаза: переопределение

категория: 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 из echo-nginx-module для прямого вывода значений переменных nginx.

При приеме одного аргумента эта директива выполнит изменение существующей переменной. Например,

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

     echo $value;
 }

тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.

Эта директива обычно используется для предотвращения SQL-инъекций.

Эту директиву можно вызывать через интерфейс ndk.set_var.DIRECTIVE модуля lua-nginx-module и директиву array_map_op модуля array-var-nginx-module.

set_quote_pgsql_str

синтаксис: set_quote_pgsql_str $dst <src>

синтаксис: set_quote_pgsql_str $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: 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

фаза: переопределение

категория: 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 из echo-nginx-module для прямого вывода значений переменных nginx.

При приеме одного аргумента эта директива выполнит изменение существующей переменной. Например,

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

     echo $value;
 }

тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.

Эту директиву можно вызывать через интерфейс ndk.set_var.DIRECTIVE модуля lua-nginx-module и директиву array_map_op модуля array-var-nginx-module.

set_unescape_uri

синтаксис: set_unescape_uri $dst <src>

синтаксис: set_unescape_uri $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: 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 из echo-nginx-module для прямого вывода значений переменных nginx.

При приеме одного аргумента эта директива выполнит изменение существующей переменной. Например,

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

     echo $key;
 }

тогда запрос GET /test?key=hello+world%21 даст точно такой же вывод, как в предыдущем примере.

Эту директиву можно вызывать через интерфейс ndk.set_var.DIRECTIVE модуля lua-nginx-module и директиву array_map_op модуля array-var-nginx-module.

set_escape_uri

синтаксис: set_escape_uri $dst <src>

синтаксис: set_escape_uri $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: ndk_set_var_value

Очень похоже на директиву set_unescape_uri, но выполняет преобразование в противоположном направлении, т.е. экранирование компонента URL.

set_hashed_upstream

синтаксис: set_hashed_upstream $dst <имя_списка_внешних> <src>

по умолчанию: нет

контекст: location, location if

фаза: переопределение

Хэширует строковый аргумент <src> в один из имен внешних, включенных в список внешних с именем <имя_списка_внешних>. Используемая хэш-функция проста и основана на модульном делении.

Вот пример,

 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_pass модуля memc-nginx-module, директиву [[HttpRedis2Module#redis2_pass]] модуля redis2-nginx-module и директиву proxy_pass модуля ngx_http_proxy_module, среди прочих.

set_encode_base32

синтаксис: set_encode_base32 $dst <src>

синтаксис: set_encode_base32 $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: ndk_set_var_value

При приеме двух аргументов эта директива кодирует значение второго аргумента <src> в его кодировку base32(hex) и присваивает результат первому аргументу, переменной $dst. Например,

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

     echo $digest;
 }

Тогда запрос GET /test выдаст следующий вывод

c5h66p35

Обратите внимание, что мы используем директиву echo из echo-nginx-module для прямого вывода значений переменных 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 даст точно такой же вывод, как в предыдущем примере.

Эту директиву можно вызывать через интерфейс ndk.set_var.DIRECTIVE модуля lua-nginx-module и директиву array_map_op модуля array-var-nginx-module.

set_base32_padding

синтаксис: set_base32_padding on|off

по умолчанию: включено

контекст: 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

по умолчанию: включено

контекст: http, server, server if, location, location if

фаза: нет

Эта директива устарела с v0.28. Используйте set_base32_padding, если вы используете v0.28+.

set_base32_alphabet

синтаксис: set_base32_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

фаза: переопределение

категория: ndk_set_var_value

Похожие на директиву set_encode_base32, но выполняют точно обратную операцию, т.е. декодирование base32(hex) дайджеста обратно в оригинальную форму.

set_encode_base64

синтаксис: set_encode_base64 $dst <src>

синтаксис: set_encode_base64 $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: ndk_set_var_value

При приеме двух аргументов эта директива кодирует значение второго аргумента <src> в его кодировку base64 и присваивает результат первому аргументу, переменной $dst. Например,

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

     echo $digest;
 }

Тогда запрос GET /test выдаст следующий вывод

YWJjZGU=

Обратите внимание, что мы используем директиву echo из echo-nginx-module для прямого вывода значений переменных nginx.

При приеме одного аргумента эта директива выполнит изменение существующей переменной. Например,

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

     echo $value;
 }

Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.

Эту директиву можно вызывать через интерфейс ndk.set_var.DIRECTIVE модуля lua-nginx-module и директиву array_map_op модуля array-var-nginx-module.

set_encode_base64url

синтаксис: set_encode_base64url $dst <src>

синтаксис: set_encode_base64url $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: ndk_set_var_value

При приеме двух аргументов эта директива кодирует значение второго аргумента <src> в его безопасный для URL формат base64 и присваивает результат первому аргументу, переменной $dst. Например,

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

     echo $digest;
 }

Тогда запрос GET /test выдаст следующий вывод

YWJjZGU=

Обратите внимание, что мы используем директиву echo из echo-nginx-module для прямого вывода значений переменных nginx.

При приеме одного аргумента эта директива выполнит изменение существующей переменной. Например,

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

     echo $value;
 }

Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.

Эту директиву можно вызывать через интерфейс ndk.set_var.DIRECTIVE модуля lua-nginx-module и директиву array_map_op модуля array-var-nginx-module.

set_decode_base64

синтаксис: set_decode_base64 $dst <src>

синтаксис: set_decode_base64 $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: ndk_set_var_value

Похожие на директиву set_encode_base64, но выполняют точно обратную операцию, т.е. декодирование base64 дайджеста обратно в оригинальную форму.

set_decode_base64url

синтаксис: set_decode_base64url $dst <src>

синтаксис: set_decode_base64url $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: ndk_set_var_value

Похожие на директиву set_encode_base64url, но выполняют точно противоположную операцию, т.е. декодирование безопасного для URL base64 дайджеста обратно в оригинальную форму.

set_encode_hex

синтаксис: set_encode_hex $dst <src>

синтаксис: set_encode_hex $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: ndk_set_var_value

При приеме двух аргументов эта директива кодирует значение второго аргумента <src> в его шестнадцатеричное представление и присваивает результат первому аргументу, переменной $dst. Например,

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

     echo $digest;
 }

Тогда запрос GET /test выдаст следующий вывод

e7aba0e4baa6e698a5

Обратите внимание, что мы используем директиву echo из echo-nginx-module для прямого вывода значений переменных nginx.

При приеме одного аргумента эта директива выполнит изменение существующей переменной. Например,

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

     echo $value;
 }

Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.

Эту директиву можно вызывать через интерфейс ndk.set_var.DIRECTIVE модуля lua-nginx-module и директиву array_map_op модуля array-var-nginx-module.

set_decode_hex

синтаксис: set_decode_hex $dst <src>

синтаксис: set_decode_hex $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: ndk_set_var_value

Похожие на директиву set_encode_hex, но выполняют точно обратную операцию, т.е. декодирование шестнадцатеричного дайджеста обратно в оригинальную форму.

set_sha1

синтаксис: set_sha1 $dst <src>

синтаксис: set_sha1 $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: 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 из echo-nginx-module для прямого вывода значений переменных nginx.

При приеме одного аргумента эта директива выполнит изменение существующей переменной. Например,

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

     echo $value;
 }

Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.

Эту директиву можно вызывать через интерфейс ndk.set_var.DIRECTIVE модуля lua-nginx-module и директиву array_map_op модуля array-var-nginx-module.

set_md5

синтаксис: set_md5 $dst <src>

синтаксис: set_md5 $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

категория: 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 из echo-nginx-module для прямого вывода значений переменных nginx.

При приеме одного аргумента эта директива выполнит изменение существующей переменной. Например,

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

     echo $value;
 }

Тогда запрос GET /test даст точно такой же вывод, как в предыдущем примере.

Эту директиву можно вызывать через интерфейс ndk.set_var.DIRECTIVE модуля lua-nginx-module и директиву array_map_op модуля array-var-nginx-module.

set_hmac_sha1

синтаксис: set_hmac_sha1 $dst <secret_key> <src>

синтаксис: set_hmac_sha1 $dst

по умолчанию: нет

контекст: location, location if

фаза: переопределение

Вычисляет дайджест 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 из echo-nginx-module для прямого вывода значений переменных 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

фаза: переопределение

Вычисляет дайджест 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 из echo-nginx-module для прямого вывода значений переменных nginx.

Эта директива требует наличия библиотеки OpenSSL в вашей сборке Nginx (обычно добавлением опции --with-http_ssl_module к скрипту ./configure).

set_random

синтаксис: set_random $res <from> <to>

по умолчанию: нет

контекст: location, location if

фаза: переопределение

Генерирует (псевдо) случайное число (в текстовом формате) в диапазоне [<$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

фаза: переопределение

Генерирует криптографически стойкую случайную строку длиной <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

фаза: переопределение

Генерирует криптографически стойкую случайную строку длиной <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

фаза: переопределение

Увеличивает $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

фаза: переопределение

Устанавливает сегодняшнюю дату ("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

фаза: переопределение

Устанавливает отформатированное 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

фаза: переопределение

Устанавливает отформатированное местное время в переменной $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. Тестовые случаи также являются декларативными. Спасибо модулю Test::Nginx в мире Perl.

Чтобы запустить его на своей стороне:

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

Вам нужно завершить любые процессы Nginx перед запуском тестового набора, если вы изменили двоичный файл сервера Nginx.

Поскольку один сервер nginx (по умолчанию localhost:1984) используется во всех тестовых скриптах (.t файлы), имеет смысл запускать тестовый набор параллельно, указывая -jN при вызове утилиты prove.

Смотрите также