var: Atribuição de variável dinâmica através de funções pré-definidas

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 e Amazon Linux 2

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

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-var

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_var_module.so;

Este documento descreve o nginx-module-var v0.1.3 lançado em 02 de abril de 2026.

---

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location / {
        var $new_var set $scheme://$host$request_uri;
    }
}

Diretrizes

var

Sintaxe: var $new_variable function [-i] args... [if\=condition]

Padrão: -

Contexto: http, server, location

Define uma nova variável cujo valor é o resultado do cálculo da função. O valor da variável não pode ser armazenado em cache e é recalculado cada vez que é utilizado.

Se o nível atual não definir uma variável com o mesmo nome, ela pode ser herdada do nível anterior.

O parâmetro -i é usado para ignorar maiúsculas e minúsculas (disponível apenas em algumas funções).

Exceto pelo nome da função, pelo parâmetro -i e pela expressão regular, todos os parâmetros podem conter variáveis.

Quando o valor de um parâmetro é inválido, o valor da variável é vazio. Em funções booleanas, parâmetros inválidos também resultarão em um valor vazio em vez de 0.

var não pode ser usado para definir a mesma variável simultaneamente com as diretrizes map ou geo. No entanto, a diretiva set pode ser usada para substituir variáveis definidas por var.

As seguintes funções estão disponíveis:

#### Julgamento Condicional ####
# Retorna 1 se o parâmetro de entrada estiver vazio ou 0, caso contrário, retorna 0
var $bool_var not str;

# Retorna 1 se todos os parâmetros de entrada não estiverem vazios e não forem 0, caso contrário, retorna 0
var $bool_var and str1 str2...; 

# Retorna 1 se qualquer parâmetro de entrada não estiver vazio e não for 0, caso contrário, retorna 0
var $bool_var or str1 str2...; 


#### Julgamento de String ####
# Verifica se a string está vazia, retorna 1 ou 0
var $bool_var is_empty str;

# Verifica se a string não está vazia, retorna 1 ou 0
var $bool_var is_not_empty str;

# Verifica se a string é um número, retorna 1 ou 0. Apenas números decimais são permitidos. números negativos e frações são suportados.
var $bool_var is_num str;

# Verifica se as strings são iguais, retorna 1 ou 0
var $bool_var str_eq [-i] str1 str2;

# Verifica se as strings não são iguais, retorna 1 ou 0
var $bool_var str_ne [-i] str1 str2;

# Verifica se a string tem o prefixo especificado, retorna 1 ou 0
var $bool_var starts_with [-i] str prefix;

# Verifica se a string tem o sufixo especificado, retorna 1 ou 0
var $bool_var ends_with [-i] str suffix;

# Verifica se a substring está presente, retorna 1 ou 0
var $bool_var contains [-i] str sub_str;

# Verifica se str1 é um dos str2 .. strn, retorna 1 ou 0
var $bool_var str_in [-i] str1 str2 str3 .. strn;

#### Operações Gerais de String ####
# Define o valor diretamente da variável
var $new_var set src_str;

# Comprimento da string
var $new_var len src_str;

# Converter para maiúsculas
var $new_var upper src_str;

# Converter para minúsculas
var $new_var lower src_str;

# Capitaliza a primeira letra de cada palavra (as palavras são separadas por caracteres não alfanuméricos)
var $new_var initcap src_str;

# Remove caracteres em branco ou outros caracteres do início e do final
var $new_var trim src_str [char];

# Remove caracteres em branco ou outros caracteres do início
var $new_var ltrim src_str [char];

# Remove caracteres em branco ou outros caracteres do final
var $new_var rtrim src_str [char];

# Inverte a string
var $new_var reverse src_str;

# Obtém a posição inicial da substring
var $new_var position [-i] src_str sub_str;

# Repete a string um número determinado de vezes
var $new_var repeat src_str times;

# Extrai substring
var $new_var substr src_str start [len];

# Substitui palavra-chave
var $new_var replace [-i] src_str src dst;

# Extrair parâmetros
# Extrai um valor de uma lista de parâmetros. Um caso de uso para isso é extrair parâmetros de consulta sem precisar escrever uma expressão regular, mas pode ser usado para procurar valores em qualquer lista de pares nome/valor. Se várias ocorrências do parâmetro existirem, apenas a primeira é retornada. a variável recebe um valor em branco. O delimitador entre o nome e o valor de um parâmetro é '=' por padrão, e o separador de parâmetros é '&' por padrão.
var $new_var extract_param [-i] param_name src_string [separator] [delimiter];

# exemplo: uma consulta "foo=123&bar=456&baz=789". Se o nome do parâmetro for bar e o separador for &, então o valor da variável resultante será 456.
# var $extraed_arg_bar extract_param bar "foo=123&bar=456&baz=789" & =;

#### Operação JSON ####
# Extrai valor json de uma string json válida.
# Requer que a biblioteca cJSON esteja instalada (veja a seção de Instalação)
var $new_var extract_json json subkey1 [subkey2] [subkey3] ...;

# Suporta chaves de objeto aninhadas e índices de array [n]
# Retorna valores de string sem aspas, outros tipos como strings JSON
# Arrays e objetos são retornados como strings JSON compactas

# Exemplos:
# Extrair de objeto aninhado
# var $new_var extract_json '{"a":{"b":{"c":3}}}' a b c;
# Resultado: 3

# Extrair de array usando [índice]
# var $new_var extract_json '{"users":[{"name":"Alice"},{"name":"Bob"}]}' users [0] name;
# Resultado: Alice

# Extrair array como string JSON
# var $items extract_json '{"data":[1,2,3]}' data;
# Resultado: [1,2,3]

# Extrair objeto como string JSON
# var $user extract_json '{"user":{"name":"Bob","age":30}}' user;
# Resultado: {"name":"Bob","age":30}


#### Julgamento Regex ####
# Verifica se o regex corresponde, retorna 1 ou 0
var $bool_var regex_match [-i] src_str match_regex;


#### Operações Regex ####
# Captura regex
var $new_var regex_capture [-i] src_str regex assign_value;

# Substitui regex
var $new_var regex_sub [-i] src_str regex replacement;


#### Julgamento Matemático ####
# Verifica se os números são iguais, retorna 1 ou 0
var $bool_var eq num1 num2;

# Verifica se os números não são iguais, retorna 1 ou 0
var $bool_var ne num1 num2;

# Verifica se é menor que, retorna 1 ou 0
var $bool_var lt num1 num2;

# Verifica se é menor ou igual, retorna 1 ou 0
var $bool_var le num1 num2;

# Verifica se é maior que, retorna 1 ou 0
var $bool_var gt num1 num2;

# Verifica se é maior ou igual, retorna 1 ou 0
var $bool_var ge num1 num2;

# Verifica se está dentro do intervalo start_num end_num, se end_num não for especificado, o intervalo é [0, start_num], retorna 1 ou 0
var $bool_var range num start_num [end_num];

# Verifica se o número é um dos num2 .. numn, retorna 1 ou 0
var $bool_var in num1 num2 .. numn;

### Operações Matemáticas ####
# Valor absoluto (retorna o formato original sem sinal negativo)
var $new_var abs num;

# Valor máximo (retorna com formato original)
var $new_var max num1 num2;

# Valor mínimo (retorna com formato original)
var $new_var min num1 num2;

# Adição inteira
var $new_var add int1 int2;

# Subtração inteira
var $new_var sub int1 int2;

# Multiplicação inteira
var $new_var mul int1 int2;

# Divisão inteira, int2 não pode ser 0
var $new_var div int1 int2;

# Módulo inteiro, int2 não pode ser 0
var $new_var mod int1 int2;

# Operação AND bit a bit
var $new_var bitwise_and int1 int2;

# Operação NOT bit a bit
var $new_var bitwise_not int;

# Operação OR bit a bit
var $new_var bitwise_or int1 int2;

# Operação XOR bit a bit (ou exclusivo)
var $new_var bitwise_xor int1 int2;

# Operação de deslocamento à esquerda, shift_bits deve ser >= 0
var $new_var lshift int shift_bits;

# Operação de deslocamento à direita (deslocamento aritmético, bit de sinal preservado), shift_bits deve ser >= 0
var $new_var rshift int shift_bits;

# Operação de deslocamento à direita sem sinal (deslocamento lógico, preenchimento com zero), shift_bits deve ser >= 0
var $new_var urshift int shift_bits;

# Arredondar para n dígitos significativos
var $new_var round src_num int;

# Truncar a parte decimal diretamente (sem arredondamento)
var $new_var int src_num;

# Valor de piso, o maior inteiro menor ou igual ao fonte
var $new_var floor src_num;

# Valor de teto, o menor inteiro maior ou igual ao fonte
var $new_var ceil src_num;

# Número inteiro positivo aleatório, o intervalo é [start_int, end_int], se end_int não for especificado, o intervalo é [0, start_int]
var $new_var rand [start_int] [end_int];

# Sequência hexadecimal aleatória especificada. number_of_bytes deve ser 1-32, o padrão é 32
var $new_var hexrand [number_of_bytes];


#### Codificação e Decodificação ####
# Converte binário para hexadecimal
var $new_var hex_encode src_str;

# Converte hexadecimal para binário
var $new_var hex_decode src_str;

# Decimal para hexadecimal
var $new_var dec_to_hex dec;

# Hexadecimal para decimal
var $new_var hex_to_dec hex;

# Codificação completa de URI
var $new_var escape_uri src_str;

# Codificação de argumento
var $new_var escape_args src_str;

# Codificação de componente de URI
var $new_var escape_uri_component src_str;

# Codificação HTML
var $new_var escape_html src_str;

# Decodificação de URI
var $new_var unescape_uri src_str;

# Codificação Base64
var $new_var base64_encode src_str;

# Codificação Base64url
var $new_var base64url_encode src_str;

# Decodificação Base64
var $new_var base64_decode src_str;

# Decodificação Base64url
var $new_var base64url_decode src_str;


#### Cálculos de Hash Criptográfico ####
# CRC32
var $new_var crc32 src_str;

# MD5
var $new_var md5sum src_str;

# SHA1
var $new_var sha1sum src_str;

# SHA224
var $new_var sha224sum src_str;

# SHA256
var $new_var sha256sum src_str;

# SHA384
var $new_var sha384sum src_str;

# SHA512
var $new_var sha512sum src_str;

# Criptografia HMAC_MD5
var $new_var hmac_md5 src_str secret;

# Criptografia HMAC_SHA1
var $new_var hmac_sha1 src_str secret;

# Criptografia HMAC_SHA224
var $new_var hmac_sha224 src_str secret;

# Criptografia HMAC_SHA256
var $new_var hmac_sha256 src_str secret;

# Criptografia HMAC_SHA384
var $new_var hmac_sha384 src_str secret;

# Criptografia HMAC_SHA512
var $new_var hmac_sha512 src_str secret;

#### Julgamento de Intervalo de Tempo ####
# Determina se o horário atual atende ao intervalo de tempo dado, requer pelo menos um parâmetro.
# Retorna 1 se todas as condições forem atendidas, caso contrário, retorna 0.
# O dia da semana é representado por 0-6, onde domingo é 0, e o formato de fuso horário é gmt+0800
var $bool_var time_range [year=year_range] [month=month_range] [day=day_range] [wday=wday_range(0-6)] [hour=hour_range] [min=min_range] [sec=sec_range] [gmt | gmt+0000];


#### Formato de Tempo ####
# Converte timestamp para tempo HTTP (tempo atual se o timestamp for omitido)
var $new_var gmt_time [src_ts] http_time;

# Converte timestamp para tempo de cookie (tempo atual se o timestamp for omitido)
var $new_var gmt_time [src_ts] cookie_time;

# Converte timestamp para tempo GMT no formato especificado (tempo atual se o timestamp for omitido)
var $new_var gmt_time [src_ts] date_format;

# Converte timestamp para tempo local no formato especificado (tempo atual se o timestamp for omitido)
var $new_var local_time [src_ts] date_format;

# Retorna timestamp atual
var $new_var unix_time;

# Converte tempo HTTP para timestamp
var $new_var unix_time src_time http_time;

# Converte data especificada para timestamp (retorna timestamp atual se todos forem omitidos)
var $new_var unix_time src_time date_format [timezone];


#### IP ####
# Determina se o endereço IP está dentro do intervalo de ip, cidr ou ipv4, se sim, retorna 1, caso contrário, retorna 0
var $bool_var ip_range ip_str [ipv4 | ipv6 | cidr | ipv4_range ] ...;

# Calcula o endereço de rede com base no endereço IP e nos bits de rede
# Para IPv4: intervalo de network_bits é 1-32
# Para IPv6: intervalo de network_bits é 1-128
# Se ipv6_network_bits não for especificado, usará o mesmo valor que ipv4_network_bits
# Retorna apenas o endereço de rede sem o comprimento do prefixo (por exemplo, "10.0.0.0" não "10.0.0.0/8")
var $new_var cidr ipv4/ipv6 ipv4_network_bits [ipv6_network_bits];

Todos os parâmetros, exceto expressões regulares, podem conter variáveis. No entanto, valores de parâmetros incorretos causarão o resultado do cálculo da função ser vazio.

Variáveis definidas com a diretiva var podem ser sobrescritas por diretivas como set e auth_request_set.

O parâmetro if habilita a variável condicional. var não será atribuído um valor se a condição avaliar como “0” ou uma string vazia. E continuará a procurar definições subsequentes dessa variável.

# Quando o cabeçalho de solicitação A está presente, o valor da variável é 'have-header-a'
var $new_var set have-header-a if=$http_a;

# Quando o cabeçalho de solicitação A não está presente, mas o cabeçalho de solicitação B está presente, o valor da variável é 'have-header-b'
var $new_var set have-header-b if=$http_b;

# Quando ambos os cabeçalhos de solicitação A e B não estão presentes, o valor da variável é 'not-have-a-or-b'
var $new_var set not-have-a-or-b;

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-var.