set-misc: Módulo Set-Misc do NGINX
Instalação
Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:
- RedHat Enterprise Linux 7, 8, 9 e 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 e 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
Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:
load_module modules/ngx_http_set_misc_module.so;
Este documento descreve o nginx-module-set-misc v0.33 lançado em 06 de setembro de 2021.
Sinopse
location /foo {
set $a $arg_a;
set_if_empty $a 56;
# GET /foo?a=32 resultará em $a == 32
# enquanto GET /foo e GET /foo?a= resultará
# em $a == 56 aqui.
}
location /bar {
set $foo "hello\n\n'\"\\";
set_quote_sql_str $foo $foo; # para mysql
# OU edição in-place:
# set_quote_sql_str $foo;
# agora $foo é: 'hello\n\n\'\"\\'
}
location /bar {
set $foo "hello\n\n'\"\\";
set_quote_pgsql_str $foo; # para PostgreSQL
# agora $foo é: E'hello\n\n\'\"\\'
}
location /json {
set $foo "hello\n\n'\"\\";
set_quote_json_str $foo $foo;
# OU edição in-place:
# set_quote_json_str $foo;
# agora $foo é: "hello\n\n'\"\\"
}
location /baz {
set $foo "hello%20world";
set_unescape_uri $foo $foo;
# OU edição in-place:
# set_unescape_uri $foo;
# agora $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; # usado com ngx_drizzle
}
location /base32 {
set $a 'abcde';
set_encode_base32 $a;
set_decode_base32 $b $a;
# agora $a == 'c5h66p35' e
# $b == 'abcde'
}
location /base64 {
set $a 'abcde';
set_encode_base64 $a;
set_decode_base64 $b $a;
# agora $a == 'YWJjZGU=' e
# $b == 'abcde'
}
location /hex {
set $a 'abcde';
set_encode_hex $a;
set_decode_hex $b $a;
# agora $a == '6162636465' e
# $b == 'abcde'
}
# GET /sha1 resulta na saída
# aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
location /sha1 {
set_sha1 $a hello;
echo $a;
}
# idem
location /sha1 {
set $a hello;
set_sha1 $a;
echo $a;
}
# GET /today resulta na data de hoje em horário local usando o formato 'yyyy-mm-dd'
location /today {
set_local_today $today;
echo $today;
}
# GET /signature resulta na assinatura hmac-sha-1
# dada uma chave secreta e uma string para assinar
# este exemplo resulta na assinatura codificada em base64 que é
# "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;
# ou escreva diretamente
# set_random $rand 3 15;
echo $rand; # imprimirá um inteiro aleatório no intervalo [3, 15]
}
Descrição
Este módulo estende o conjunto de diretivas do módulo HttpRewriteModule padrão para fornecer mais funcionalidades, como escape e unescape de URI, citação JSON, codificação e decodificação de digestos Hexadecimal/MD5/SHA1/Base32/Base64, gerador de números aleatórios e mais!
Cada diretiva fornecida por este módulo pode ser misturada livremente com outras diretivas do ngx_http_rewrite_module, como if e set. (Obrigado ao Nginx Devel Kit!)
Diretivas
set_if_empty
sintaxe: set_if_empty $dst <src>
padrão: não
contexto: location, location if
fase: rewrite
Atribui o valor do argumento <src> se e somente se a variável $dst estiver vazia (ou seja, não encontrada ou tiver um valor de string vazia).
No exemplo a seguir,
set $a 32;
set_if_empty $a 56;
a variável $dst terá o valor 32 no final. Mas no exemplo
set $a '';
set $value "hello, world"
set_if_empty $a $value;
$a terá o valor "hello, world" no final.
set_quote_sql_str
sintaxe: set_quote_sql_str $dst <src>
sintaxe: set_quote_sql_str $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Ao receber dois argumentos, esta diretiva irá citar o valor do segundo argumento <src> pela regra de citação de valor de string do MySQL e atribuir o resultado ao primeiro argumento, variável $dst. Por exemplo,
location /test {
set $value "hello\n\r'\"\\";
set_quote_sql_str $quoted $value;
echo $quoted;
}
Então, a requisição GET /test resultará na seguinte saída
'hello\n\r\'\"\\'
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Ao receber um único argumento, esta diretiva fará a modificação in-place da variável de argumento. Por exemplo,
location /test {
set $value "hello\n\r'\"\\";
set_quote_sql_str $value;
echo $value;
}
então a requisição GET /test dará exatamente a mesma saída que o exemplo anterior.
Esta diretiva é geralmente usada para prevenir injeção de SQL.
Esta diretiva pode ser invocada pela interface ndk.set_var.DIRECTIVE do lua-nginx-module e pela diretiva array_map_op do array-var-nginx-module.
set_quote_pgsql_str
sintaxe: set_quote_pgsql_str $dst <src>
sintaxe: set_quote_pgsql_str $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Muito semelhante ao set_quote_sql_str, mas com regras de citação do PostgreSQL para literais de string SQL.
set_quote_json_str
sintaxe: set_quote_json_str $dst <src>
sintaxe: set_quote_json_str $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Ao receber dois argumentos, esta diretiva irá citar o valor do segundo argumento <src> pela regra de citação de valor de string JSON e atribuir o resultado ao primeiro argumento, variável $dst. Por exemplo,
location /test {
set $value "hello\n\r'\"\\";
set_quote_json_str $quoted $value;
echo $quoted;
}
Então, a requisição GET /test resultará na seguinte saída
"hello\n\r'\"\\"
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Ao receber um único argumento, esta diretiva fará a modificação in-place da variável de argumento. Por exemplo,
location /test {
set $value "hello\n\r'\"\\";
set_quote_json_str $value;
echo $value;
}
então a requisição GET /test dará exatamente a mesma saída que o exemplo anterior.
Esta diretiva pode ser invocada pela interface ndk.set_var.DIRECTIVE do lua-nginx-module e pela diretiva array_map_op do array-var-nginx-module.
set_unescape_uri
sintaxe: set_unescape_uri $dst <src>
sintaxe: set_unescape_uri $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Ao receber dois argumentos, esta diretiva irá desescapar o valor do segundo argumento <src> como um componente de URI e atribuir o resultado ao primeiro argumento, variável $dst. Por exemplo,
location /test {
set_unescape_uri $key $arg_key;
echo $key;
}
Então, a requisição GET /test?key=hello+world%21 resultará na seguinte saída
hello world!
A variável padrão do nginx $arg_PARAMETER contém o valor bruto (escapado) do parâmetro URI. Portanto, precisamos da diretiva set_unescape_uri para desescapá-lo primeiro.
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Ao receber um único argumento, esta diretiva fará a modificação in-place da variável de argumento. Por exemplo,
location /test {
set $key $arg_key;
set_unescape_uri $key;
echo $key;
}
então a requisição GET /test?key=hello+world%21 dará exatamente a mesma saída que o exemplo anterior.
Esta diretiva pode ser invocada pela interface ndk.set_var.DIRECTIVE do lua-nginx-module e pela diretiva array_map_op do array-var-nginx-module.
set_escape_uri
sintaxe: set_escape_uri $dst <src>
sintaxe: set_escape_uri $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Muito semelhante à diretiva set_unescape_uri, mas faz a conversão na outra direção, ou seja, escape de componente de URL.
set_hashed_upstream
sintaxe: set_hashed_upstream $dst <upstream_list_name> <src>
padrão: não
contexto: location, location if
fase: rewrite
Hash a string argument <src> em um dos nomes de upstream incluídos na lista de upstream nomeada <upstream_list_name>. A função de hash utilizada é simples módulo.
Aqui está um exemplo,
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;
}
Então, GET /test?key=blah resultará em "moon", "sun" ou "earth", dependendo do valor real do argumento de consulta key.
Esta diretiva é geralmente usada para calcular uma variável nginx a ser passada para a diretiva memc_pass do memc-nginx-module, a diretiva [[HttpRedis2Module#redis2_pass]] do redis2-nginx-module, e a diretiva proxy_pass do ngx_http_proxy_module, entre outras.
set_encode_base32
sintaxe: set_encode_base32 $dst <src>
sintaxe: set_encode_base32 $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Ao receber dois argumentos, esta diretiva irá codificar o valor do segundo argumento <src> para seu digest base32(hex) e atribuir o resultado ao primeiro argumento, variável $dst. Por exemplo,
location /test {
set $raw "abcde";
set_encode_base32 $digest $raw;
echo $digest;
}
Então, a requisição GET /test resultará na seguinte saída
c5h66p35
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
O RFC força a codificação compatível com [A-Z2-7] do RFC-3548, mas estamos usando a codificação "base32hex" ([0-9a-v]) por padrão. A diretiva set_base32_alphabet (introduzida pela primeira vez na v0.28) permite que você altere o alfabeto usado para codificação/decodificação, então a codificação compatível com o RFC-3548 ainda é possível por configurações personalizadas.
Por padrão, o caractere = é usado para preencher os bytes restantes devido ao alinhamento. Mas o comportamento de preenchimento pode ser completamente desativado definindo set_base32_padding como off.
Ao receber um único argumento, esta diretiva fará a modificação in-place da variável de argumento. Por exemplo,
location /test {
set $value "abcde";
set_encode_base32 $value;
echo $value;
}
então a requisição GET /test dará exatamente a mesma saída que o exemplo anterior.
Esta diretiva pode ser invocada pela interface ndk.set_var.DIRECTIVE do lua-nginx-module e pela diretiva array_map_op do array-var-nginx-module.
set_base32_padding
sintaxe: set_base32_padding on|off
padrão: on
contexto: http, server, server if, location, location if
fase: não
Esta diretiva pode controlar se deve preencher os bytes restantes com o caractere "=" ao codificar um digest base32 pela diretiva set_encode_base32.
Esta diretiva foi introduzida pela primeira vez na v0.28. Se você usar versões anteriores deste módulo, então você deve usar set_misc_base32_padding em vez disso.
set_misc_base32_padding
sintaxe: set_misc_base32_padding on|off
padrão: on
contexto: http, server, server if, location, location if
fase: não
Esta diretiva foi descontinuada desde a v0.28. Use set_base32_padding em vez disso se você estiver usando v0.28+.
set_base32_alphabet
sintaxe: set_base32_alphabet <alphabet>
padrão: "0123456789abcdefghijklmnopqrstuv"
contexto: http, server, server if, location, location if
fase: não
Esta diretiva controla o alfabeto usado para codificação/decodificação de um digest base32. Aceita uma string contendo o alfabeto desejado, como "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567" para o alfabeto padrão.
O alfabeto estendido (base32hex) é usado por padrão.
Esta diretiva foi introduzida pela primeira vez na v0.28.
set_decode_base32
sintaxe: set_decode_base32 $dst <src>
sintaxe: set_decode_base32 $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Semelhante à diretiva set_encode_base32, mas faz exatamente a operação oposta, ou seja, decodifica um digest base32(hex) para sua forma original.
set_encode_base64
sintaxe: set_encode_base64 $dst <src>
sintaxe: set_encode_base64 $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Ao receber dois argumentos, esta diretiva irá codificar o valor do segundo argumento <src> para seu digest base64 e atribuir o resultado ao primeiro argumento, variável $dst. Por exemplo,
location /test {
set $raw "abcde";
set_encode_base64 $digest $raw;
echo $digest;
}
Então, a requisição GET /test resultará na seguinte saída
YWJjZGU=
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Ao receber um único argumento, esta diretiva fará a modificação in-place da variável de argumento. Por exemplo,
location /test {
set $value "abcde";
set_encode_base64 $value;
echo $value;
}
então a requisição GET /test dará exatamente a mesma saída que o exemplo anterior.
Esta diretiva pode ser invocada pela interface ndk.set_var.DIRECTIVE do lua-nginx-module e pela diretiva array_map_op do array-var-nginx-module.
set_encode_base64url
sintaxe: set_encode_base64url $dst <src>
sintaxe: set_encode_base64url $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Ao receber dois argumentos, esta diretiva irá codificar o valor do segundo argumento <src> para seu digest base64 seguro para URL e atribuir o resultado ao primeiro argumento, variável $dst. Por exemplo,
location /test {
set $raw "abcde";
set_encode_base64url $digest $raw;
echo $digest;
}
Então, a requisição GET /test resultará na seguinte saída
YWJjZGU=
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Ao receber um único argumento, esta diretiva fará a modificação in-place da variável de argumento. Por exemplo,
location /test {
set $value "abcde";
set_encode_base64url $value;
echo $value;
}
então a requisição GET /test dará exatamente a mesma saída que o exemplo anterior.
Esta diretiva pode ser invocada pela interface ndk.set_var.DIRECTIVE do lua-nginx-module e pela diretiva array_map_op do array-var-nginx-module.
set_decode_base64
sintaxe: set_decode_base64 $dst <src>
sintaxe: set_decode_base64 $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Semelhante à diretiva set_encode_base64, mas faz exatamente a operação oposta, ou seja, decodifica um digest base64 para sua forma original.
set_decode_base64url
sintaxe: set_decode_base64url $dst <src>
sintaxe: set_decode_base64url $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Semelhante à diretiva set_encode_base64url, mas faz exatamente a operação oposta, ou seja, decodifica um digest base64 seguro para URL para sua forma original.
set_encode_hex
sintaxe: set_encode_hex $dst <src>
sintaxe: set_encode_hex $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Ao receber dois argumentos, esta diretiva irá codificar o valor do segundo argumento <src> para seu digest hexadecimal e atribuir o resultado ao primeiro argumento, variável $dst. Por exemplo,
location /test {
set $raw "章亦春";
set_encode_hex $digest $raw;
echo $digest;
}
Então, a requisição GET /test resultará na seguinte saída
e7aba0e4baa6e698a5
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Ao receber um único argumento, esta diretiva fará a modificação in-place da variável de argumento. Por exemplo,
location /test {
set $value "章亦春";
set_encode_hex $value;
echo $value;
}
então a requisição GET /test dará exatamente a mesma saída que o exemplo anterior.
Esta diretiva pode ser invocada pela interface ndk.set_var.DIRECTIVE do lua-nginx-module e pela diretiva array_map_op do array-var-nginx-module.
set_decode_hex
sintaxe: set_decode_hex $dst <src>
sintaxe: set_decode_hex $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Semelhante à diretiva set_encode_hex, mas faz exatamente a operação oposta, ou seja, decodifica um digest hexadecimal para sua forma original.
set_sha1
sintaxe: set_sha1 $dst <src>
sintaxe: set_sha1 $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Ao receber dois argumentos, esta diretiva irá codificar o valor do segundo argumento <src> para seu digest SHA-1 e atribuir o resultado ao primeiro argumento, variável $dst. A forma hexadecimal do digest SHA-1 será gerada automaticamente, use set_decode_hex para decodificar o resultado se você quiser a forma binária do digest SHA-1.
Por exemplo,
location /test {
set $raw "hello";
set_sha1 $digest $raw;
echo $digest;
}
Então, a requisição GET /test resultará na seguinte saída
aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Ao receber um único argumento, esta diretiva fará a modificação in-place da variável de argumento. Por exemplo,
location /test {
set $value "hello";
set_sha1 $value;
echo $value;
}
então a requisição GET /test dará exatamente a mesma saída que o exemplo anterior.
Esta diretiva pode ser invocada pela interface ndk.set_var.DIRECTIVE do lua-nginx-module e pela diretiva array_map_op do array-var-nginx-module.
set_md5
sintaxe: set_md5 $dst <src>
sintaxe: set_md5 $dst
padrão: não
contexto: location, location if
fase: rewrite
categoria: ndk_set_var_value
Ao receber dois argumentos, esta diretiva irá codificar o valor do segundo argumento <src> para seu digest MD5 e atribuir o resultado ao primeiro argumento, variável $dst. A forma hexadecimal do digest MD5 será gerada automaticamente, use set_decode_hex para decodificar o resultado se você quiser a forma binária do digest MD5.
Por exemplo,
location /test {
set $raw "hello";
set_md5 $digest $raw;
echo $digest;
}
Então, a requisição GET /test resultará na seguinte saída
5d41402abc4b2a76b9719d911017c592
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Ao receber um único argumento, esta diretiva fará a modificação in-place da variável de argumento. Por exemplo,
location /test {
set $value "hello";
set_md5 $value;
echo $value;
}
então a requisição GET /test dará exatamente a mesma saída que o exemplo anterior.
Esta diretiva pode ser invocada pela interface ndk.set_var.DIRECTIVE do lua-nginx-module e pela diretiva array_map_op do array-var-nginx-module.
set_hmac_sha1
sintaxe: set_hmac_sha1 $dst <secret_key> <src>
sintaxe: set_hmac_sha1 $dst
padrão: não
contexto: location, location if
fase: rewrite
Calcula o digest HMAC-SHA1 do argumento <src> e atribui o resultado à variável de argumento $dst com a chave secreta <secret_key>.
A forma binária bruta do digest HMAC-SHA1 será gerada, use set_encode_base64, por exemplo, para codificar o resultado em uma representação textual, se desejado.
Por exemplo,
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;
}
Então, a requisição GET /test resultará na seguinte saída
R/pvxzHC4NLtj7S+kXFg/NePTmk=
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Esta diretiva requer que a biblioteca OpenSSL esteja habilitada na sua construção do NGINX (geralmente passando a opção --with-http_ssl_module para o script ./configure).
set_hmac_sha256
sintaxe: set_hmac_sha256 $dst <secret_key> <src>
sintaxe: set_hmac_sha256 $dst
padrão: não
contexto: location, location if
fase: rewrite
Calcula o digest HMAC-SHA256 do argumento <src> e atribui o resultado à variável de argumento $dst com a chave secreta <secret_key>.
A forma binária bruta do digest HMAC-SHA256 será gerada, use set_encode_base64, por exemplo, para codificar o resultado em uma representação textual, se desejado.
Por exemplo,
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;
}
Então, a requisição GET /test resultará na seguinte saída
4pU3GRQrKKIoeLb9CqYsavHE2l6Hx+KMmRmesU+Cfrs=
Por favor, note que estamos usando a echo-nginx-module's echo directive aqui para imprimir os valores das variáveis do nginx diretamente.
Esta diretiva requer que a biblioteca OpenSSL esteja habilitada na sua construção do NGINX (geralmente passando a opção --with-http_ssl_module para o script ./configure).
set_random
sintaxe: set_random $res <from> <to>
padrão: não
contexto: location, location if
fase: rewrite
Gera um número (pseudo) aleatório (em forma textual) dentro do intervalo [<$from>, <$to>] (inclusivo).
Apenas números não negativos são permitidos para os argumentos <from> e <to>.
Quando <from> é maior que <to>, seus valores serão trocados de acordo.
Por exemplo,
location /test {
set $from 5;
set $to 7;
set_random $res $from $to;
echo $res;
}
então a requisição GET /test resultará em um número entre 5 e 7 (ou seja, entre 5, 6, 7).
Por enquanto, não há como configurar uma semente de gerador aleatório personalizada.
Nos bastidores, utiliza a função padrão C rand().
Esta diretiva foi introduzida pela primeira vez na versão v0.22rc1.
Veja também set_secure_random_alphanum e set_secure_random_lcalpha.
set_secure_random_alphanum
sintaxe: set_secure_random_alphanum $res <length>
padrão: não
contexto: location, location if
fase: rewrite
Gera uma string aleatória criptograficamente forte de <length> caracteres com o alfabeto [a-zA-Z0-9].
<length> pode ser entre 1 e 64, inclusivo.
Por exemplo,
location /test {
set_secure_random_alphanum $res 32;
echo $res;
}
então a requisição GET /test resultará em uma string como ivVVRP2DGaAqDmdf3Rv4ZDJ7k0gOfASz.
Essa funcionalidade depende da presença do dispositivo /dev/urandom, disponível na maioria dos sistemas do tipo UNIX.
Veja também set_secure_random_lcalpha e set_random.
Esta diretiva foi introduzida pela primeira vez na versão v0.22rc8.
set_secure_random_lcalpha
sintaxe: set_secure_random_lcalpha $res <length>
padrão: não
contexto: location, location if
fase: rewrite
Gera uma string aleatória criptograficamente forte de <length> caracteres com o alfabeto [a-z].
<length> pode ser entre 1 e 64, inclusivo.
Por exemplo,
location /test {
set_secure_random_lcalpha $res 32;
echo $res;
}
então a requisição GET /test resultará em uma string como kcuxcddktffsippuekhshdaclaquiusj.
Essa funcionalidade depende da presença do dispositivo /dev/urandom, disponível na maioria dos sistemas do tipo UNIX.
Esta diretiva foi introduzida pela primeira vez na versão v0.22rc8.
Veja também set_secure_random_alphanum e set_random.
set_rotate
sintaxe: set_rotate $value <from> <to>
padrão: não
contexto: location, location if
fase: rewrite
Incrementa $value, mas mantém dentro do intervalo de <from> a <to>.
Se $value for maior que <to> ou menor que <from>, será definido para o valor de <from>.
O valor atual após a execução desta diretiva será sempre salvo com base na localização. E esse valor salvo será usado para a incrementação quando $value não estiver inicializado ou tiver um valor inválido.
Apenas números não negativos são permitidos para os argumentos <from> e <to>.
Quando <from> é maior que <to>, seus valores serão trocados de acordo.
Por exemplo,
location /rotate {
default_type text/plain;
set $counter $cookie_counter;
set_rotate $counter 1 5;
echo $counter;
add_header Set-Cookie counter=$counter;
}
então a requisição GET /rotate resultará no próximo número entre 1 e 5 (ou seja, 1, 2, 3, 4, 5) em cada atualização da página. Esta diretiva pode ser útil para fins de rotação de banners.
Outro exemplo é usar a persistência de valor do lado do servidor para fazer um simples round-robin:
location /rotate {
default_type text/plain;
set_rotate $counter 0 3;
echo $counter;
}
E acessar /rotate também resultará na sequência de inteiros 0, 1, 2, 3, 0, 1, 2, 3, e assim por diante.
Esta diretiva foi introduzida pela primeira vez na versão v0.22rc7.
set_local_today
sintaxe: set_local_today $dst
padrão: não
contexto: location, location if
fase: rewrite
Define a data de hoje ("yyyy-mm-dd") no horário local para a variável de argumento $dst.
Aqui está um exemplo,
location /today {
set_local_today $today;
echo $today;
}
então a requisição GET /today resultará em algo como
2011-08-16
e o ano, a data real que você obtém aqui variará a cada dia ;)
Nos bastidores, esta diretiva utiliza a API ngx_time no núcleo do NGINX, portanto, geralmente não há chamadas de sistema envolvidas devido ao mecanismo de cache de tempo no núcleo do NGINX.
set_formatted_gmt_time
sintaxe: set_formatted_gmt_time $res <time-format>
padrão: não
contexto: location, location if
fase: rewrite
Define um horário GMT formatado para a variável $res (como o primeiro argumento) usando a string de formato no segundo argumento.
Todas as notações de especificação de conversão na função padrão C strftime são suportadas, como %Y (para anos de 4 dígitos) e %M (para minutos em decimal). Veja http://linux.die.net/man/3/strftime para uma lista completa dos símbolos de especificação de conversão.
Abaixo está um exemplo:
location = /t {
set_formatted_gmt_time $timestr "%a %b %e %H:%M:%S %Y GMT";
echo $timestr;
}
Acessar /t resulta na saída
Sex Dez 13 15:34:37 2013 GMT
Esta diretiva foi adicionada pela primeira vez na versão 0.23.
Veja também set_formatted_local_time.
set_formatted_local_time
sintaxe: set_formatted_local_time $res <time-format>
padrão: não
contexto: location, location if
fase: rewrite
Define um horário local formatado para a variável $res (como o primeiro argumento) usando a string de formato no segundo argumento.
Todas as notações de especificação de conversão na função padrão C strftime são suportadas, como %Y (para anos de 4 dígitos) e %M (para minutos em decimal). Veja http://linux.die.net/man/3/strftime para uma lista completa dos símbolos de especificação de conversão.
Abaixo está um exemplo:
location = /t {
set_formatted_local_time $timestr "%a %b %e %H:%M:%S %Y %Z";
echo $timestr;
}
Acessar /t resulta na saída
Sex Dez 13 15:42:15 2013 PST
Esta diretiva foi adicionada pela primeira vez na versão 0.23.
Veja também set_formatted_gmt_time.
Advertências
Não use $arg_PARAMETER, $cookie_COOKIE, $http_HEADER ou outras variáveis especiais definidas no módulo núcleo do NGINX como a variável alvo nas diretivas deste módulo. Por exemplo,
set_if_empty $arg_user 'foo'; # NÃO USE ISTO!
pode levar a falhas de segmentação.
Mudanças
Os logs de alterações para cada versão deste módulo podem ser obtidos a partir dos logs de alterações do pacote OpenResty:
Conjunto de Testes
Este módulo vem com um conjunto de testes dirigido por Perl. Os casos de teste também são declarativos. Graças ao módulo Test::Nginx no mundo Perl.
Para executá-lo do seu lado:
$ PATH=/path/to/your/nginx-with-set-misc-module:$PATH prove -r t
Você precisa encerrar qualquer processo do NGINX antes de executar o conjunto de testes se você tiver alterado o binário do servidor NGINX.
Como um único servidor nginx (por padrão, localhost:1984) é usado em todos os scripts de teste (.t arquivos), não faz sentido executar o conjunto de testes em paralelo especificando -jN ao invocar a utilidade prove.
Veja Também
GitHub
Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório GitHub do nginx-module-set-misc.