set-misc: Module Set-Misc de NGINX
Installation
Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :
- RedHat Enterprise Linux 7, 8, 9 et 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 et 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
Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :
load_module modules/ngx_http_set_misc_module.so;
Ce document décrit nginx-module-set-misc v0.33 publié le 06 septembre 2021.
Synopsis
location /foo {
set $a $arg_a;
set_if_empty $a 56;
# GET /foo?a=32 donnera $a == 32
# tandis que GET /foo et GET /foo?a= donnera
# $a == 56 ici.
}
location /bar {
set $foo "hello\n\n'\"\\";
set_quote_sql_str $foo $foo; # pour mysql
# OU édition en place :
# set_quote_sql_str $foo;
# maintenant $foo est : 'hello\n\n\'\"\\'
}
location /bar {
set $foo "hello\n\n'\"\\";
set_quote_pgsql_str $foo; # pour PostgreSQL
# maintenant $foo est : E'hello\n\n\'\"\\'
}
location /json {
set $foo "hello\n\n'\"\\";
set_quote_json_str $foo $foo;
# OU édition en place :
# set_quote_json_str $foo;
# maintenant $foo est : "hello\n\n'\"\\"
}
location /baz {
set $foo "hello%20world";
set_unescape_uri $foo $foo;
# OU édition en place :
# set_unescape_uri $foo;
# maintenant $foo est : 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; # utilisé avec ngx_drizzle
}
location /base32 {
set $a 'abcde';
set_encode_base32 $a;
set_decode_base32 $b $a;
# maintenant $a == 'c5h66p35' et
# $b == 'abcde'
}
location /base64 {
set $a 'abcde';
set_encode_base64 $a;
set_decode_base64 $b $a;
# maintenant $a == 'YWJjZGU=' et
# $b == 'abcde'
}
location /hex {
set $a 'abcde';
set_encode_hex $a;
set_decode_hex $b $a;
# maintenant $a == '6162636465' et
# $b == 'abcde'
}
# GET /sha1 donne la sortie
# aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
location /sha1 {
set_sha1 $a hello;
echo $a;
}
# idem
location /sha1 {
set $a hello;
set_sha1 $a;
echo $a;
}
# GET /today donne la date d'aujourd'hui en heure locale au format 'yyyy-mm-dd'
location /today {
set_local_today $today;
echo $today;
}
# GET /signature donne la signature hmac-sha-1
# donnée une clé secrète et une chaîne à signer
# cet exemple donne la signature encodée en base64 qui est
# "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 écrire directement
# set_random $rand 3 15;
echo $rand; # affichera un entier aléatoire dans la plage [3, 15]
}
Description
Ce module étend l'ensemble des directives du module HttpRewriteModule standard pour fournir plus de fonctionnalités telles que l'échappement et le déséchappement d'URI, le quoting JSON, l'encodage et le décodage de digest Hexadécimal/MD5/SHA1/Base32/Base64, le générateur de nombres aléatoires, et plus encore !
Chaque directive fournie par ce module peut être mélangée librement avec d'autres directives du ngx_http_rewrite_module, comme if et set. (Merci au Nginx Devel Kit !)
Directives
set_if_empty
syntax: set_if_empty $dst <src>
default: non
context: location, location if
phase: rewrite
Assigne la valeur de l'argument <src> si et seulement si la variable $dst est vide (c'est-à-dire, non trouvée ou a une valeur de chaîne vide).
Dans l'exemple suivant,
set $a 32;
set_if_empty $a 56;
la variable $dst prendra finalement la valeur 32. Mais dans l'exemple
set $a '';
set $value "hello, world"
set_if_empty $a $value;
$a prendra finalement la valeur "hello, world".
set_quote_sql_str
syntax: set_quote_sql_str $dst <src>
syntax: set_quote_sql_str $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Lorsqu'il prend deux arguments, cette directive va citer la valeur du deuxième argument <src> selon la règle de citation des valeurs de chaîne de MySQL et assigner le résultat au premier argument, la variable $dst. Par exemple,
location /test {
set $value "hello\n\r'\"\\";
set_quote_sql_str $quoted $value;
echo $quoted;
}
Ensuite, la requête GET /test donnera la sortie suivante
'hello\n\r\'\"\\'
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Lorsqu'il prend un seul argument, cette directive effectuera une modification en place de la variable d'argument. Par exemple,
location /test {
set $value "hello\n\r'\"\\";
set_quote_sql_str $value;
echo $value;
}
Ensuite, la requête GET /test donnera exactement la même sortie que l'exemple précédent.
Cette directive est généralement utilisée pour prévenir les injections SQL.
Cette directive peut être invoquée par l'interface ndk.set_var.DIRECTIVE du lua-nginx-module et la directive array_map_op du array-var-nginx-module.
set_quote_pgsql_str
syntax: set_quote_pgsql_str $dst <src>
syntax: set_quote_pgsql_str $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Très similaire à set_quote_sql_str, mais avec les règles de citation PostgreSQL pour les littéraux de chaîne SQL.
set_quote_json_str
syntax: set_quote_json_str $dst <src>
syntax: set_quote_json_str $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Lorsqu'il prend deux arguments, cette directive va citer la valeur du deuxième argument <src> selon la règle de citation des valeurs de chaîne JSON et assigner le résultat au premier argument, la variable $dst. Par exemple,
location /test {
set $value "hello\n\r'\"\\";
set_quote_json_str $quoted $value;
echo $quoted;
}
Ensuite, la requête GET /test donnera la sortie suivante
"hello\n\r'\"\\"
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Lorsqu'il prend un seul argument, cette directive effectuera une modification en place de la variable d'argument. Par exemple,
location /test {
set $value "hello\n\r'\"\\";
set_quote_json_str $value;
echo $value;
}
Ensuite, la requête GET /test donnera exactement la même sortie que l'exemple précédent.
Cette directive peut être invoquée par l'interface ndk.set_var.DIRECTIVE du lua-nginx-module et la directive array_map_op du array-var-nginx-module.
set_unescape_uri
syntax: set_unescape_uri $dst <src>
syntax: set_unescape_uri $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Lorsqu'il prend deux arguments, cette directive va déséchapper la valeur du deuxième argument <src> en tant que composant URI et assigner le résultat au premier argument, la variable $dst. Par exemple,
location /test {
set_unescape_uri $key $arg_key;
echo $key;
}
Ensuite, la requête GET /test?key=hello+world%21 donnera la sortie suivante
hello world!
La variable standard nginx $arg_PARAMETER contient la valeur brute (échappée) du paramètre URI. Donc, nous avons besoin de la directive set_unescape_uri pour la déséchapper d'abord.
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Lorsqu'il prend un seul argument, cette directive effectuera une modification en place de la variable d'argument. Par exemple,
location /test {
set $key $arg_key;
set_unescape_uri $key;
echo $key;
}
Ensuite, la requête GET /test?key=hello+world%21 donnera exactement la même sortie que l'exemple précédent.
Cette directive peut être invoquée par l'interface ndk.set_var.DIRECTIVE du lua-nginx-module et la directive array_map_op du array-var-nginx-module.
set_escape_uri
syntax: set_escape_uri $dst <src>
syntax: set_escape_uri $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Très similaire à la directive set_unescape_uri, mais effectue la conversion dans l'autre sens, c'est-à-dire, l'échappement des composants d'URL.
set_hashed_upstream
syntax: set_hashed_upstream $dst <upstream_list_name> <src>
default: non
context: location, location if
phase: rewrite
Hache la chaîne d'argument <src> dans l'un des noms de upstream inclus dans la liste de upstream nommée <upstream_list_name>. La fonction de hachage utilisée est un simple modulo.
Voici un exemple,
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;
}
Ensuite, GET /test?key=blah affichera soit "moon", "sun", ou "earth", selon la valeur réelle de l'argument de requête key.
Cette directive est généralement utilisée pour calculer une variable nginx à passer à la directive memc_pass du memc-nginx-module, à la directive [[HttpRedis2Module#redis2_pass]] du redis2-nginx-module, et à la directive proxy_pass du ngx_http_proxy_module, entre autres.
set_encode_base32
syntax: set_encode_base32 $dst <src>
syntax: set_encode_base32 $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Lorsqu'il prend deux arguments, cette directive va encoder la valeur du deuxième argument <src> en son digest base32(hex) et assigner le résultat au premier argument, la variable $dst. Par exemple,
location /test {
set $raw "abcde";
set_encode_base32 $digest $raw;
echo $digest;
}
Ensuite, la requête GET /test donnera la sortie suivante
c5h66p35
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Le RFC impose l'encodage conforme au [A-Z2-7] RFC-3548, mais nous utilisons l'encodage "base32hex" ([0-9a-v]) par défaut. La directive set_base32_alphabet (introduite pour la première fois dans v0.28) vous permet de changer l'alphabet utilisé pour l'encodage/décodage afin qu'un encodage conforme au RFC-3548 soit toujours possible par des configurations personnalisées.
Par défaut, le caractère = est utilisé pour remplir les octets restants en raison de l'alignement. Mais le comportement de remplissage peut être complètement désactivé en définissant set_base32_padding sur off.
Lorsqu'il prend un seul argument, cette directive effectuera une modification en place de la variable d'argument. Par exemple,
location /test {
set $value "abcde";
set_encode_base32 $value;
echo $value;
}
Ensuite, la requête GET /test donnera exactement la même sortie que l'exemple précédent.
Cette directive peut être invoquée par l'interface ndk.set_var.DIRECTIVE du lua-nginx-module et la directive array_map_op du array-var-nginx-module.
set_base32_padding
syntax: set_base32_padding on|off
default: on
context: http, server, server if, location, location if
phase: non
Cette directive peut contrôler si les octets restants doivent être remplis avec le caractère "=" lors de l'encodage d'un digest base32 par la directive set_encode_base32.
Cette directive a été introduite pour la première fois dans v0.28. Si vous utilisez des versions antérieures de ce module, vous devriez utiliser set_misc_base32_padding à la place.
set_misc_base32_padding
syntax: set_misc_base32_padding on|off
default: on
context: http, server, server if, location, location if
phase: non
Cette directive a été dépréciée depuis v0.28. Utilisez set_base32_padding à la place si vous utilisez v0.28+.
set_base32_alphabet
syntax: set_base32_alphabet <alphabet>
default: "0123456789abcdefghijklmnopqrstuv"
context: http, server, server if, location, location if
phase: non
Cette directive contrôle l'alphabet utilisé pour l'encodage/décodage d'un digest base32. Elle accepte une chaîne contenant l'alphabet souhaité comme "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567" pour l'alphabet standard.
L'alphabet étendu (base32hex) est utilisé par défaut.
Cette directive a été introduite pour la première fois dans v0.28.
set_decode_base32
syntax: set_decode_base32 $dst <src>
syntax: set_decode_base32 $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Similaire à la directive set_encode_base32, mais effectue exactement l'opération inverse, c'est-à-dire, décode un digest base32(hex) dans sa forme originale.
set_encode_base64
syntax: set_encode_base64 $dst <src>
syntax: set_encode_base64 $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Lorsqu'il prend deux arguments, cette directive va encoder la valeur du deuxième argument <src> en son digest base64 et assigner le résultat au premier argument, la variable $dst. Par exemple,
location /test {
set $raw "abcde";
set_encode_base64 $digest $raw;
echo $digest;
}
Ensuite, la requête GET /test donnera la sortie suivante
YWJjZGU=
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Lorsqu'il prend un seul argument, cette directive effectuera une modification en place de la variable d'argument. Par exemple,
location /test {
set $value "abcde";
set_encode_base64 $value;
echo $value;
}
Ensuite, la requête GET /test donnera exactement la même sortie que l'exemple précédent.
Cette directive peut être invoquée par l'interface ndk.set_var.DIRECTIVE du lua-nginx-module et la directive array_map_op du array-var-nginx-module.
set_encode_base64url
syntax: set_encode_base64url $dst <src>
syntax: set_encode_base64url $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Lorsqu'il prend deux arguments, cette directive va encoder la valeur du deuxième argument <src> en son digest base64 sécurisé pour les URL et assigner le résultat au premier argument, la variable $dst. Par exemple,
location /test {
set $raw "abcde";
set_encode_base64url $digest $raw;
echo $digest;
}
Ensuite, la requête GET /test donnera la sortie suivante
YWJjZGU=
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Lorsqu'il prend un seul argument, cette directive effectuera une modification en place de la variable d'argument. Par exemple,
location /test {
set $value "abcde";
set_encode_base64url $value;
echo $value;
}
Ensuite, la requête GET /test donnera exactement la même sortie que l'exemple précédent.
Cette directive peut être invoquée par l'interface ndk.set_var.DIRECTIVE du lua-nginx-module et la directive array_map_op du array-var-nginx-module.
set_decode_base64
syntax: set_decode_base64 $dst <src>
syntax: set_decode_base64 $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Similaire à la directive set_encode_base64, mais effectue exactement l'opération inverse, c'est-à-dire, décode un digest base64 dans sa forme originale.
set_decode_base64url
syntax: set_decode_base64url $dst <src>
syntax: set_decode_base64url $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Similaire à la directive set_encode_base64url, mais effectue exactement l'opération inverse, c'est-à-dire, décode un digest base64 sécurisé pour les URL dans sa forme originale.
set_encode_hex
syntax: set_encode_hex $dst <src>
syntax: set_encode_hex $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Lorsqu'il prend deux arguments, cette directive va encoder la valeur du deuxième argument <src> en son digest hexadécimal et assigner le résultat au premier argument, la variable $dst. Par exemple,
location /test {
set $raw "章亦春";
set_encode_hex $digest $raw;
echo $digest;
}
Ensuite, la requête GET /test donnera la sortie suivante
e7aba0e4baa6e698a5
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Lorsqu'il prend un seul argument, cette directive effectuera une modification en place de la variable d'argument. Par exemple,
location /test {
set $value "章亦春";
set_encode_hex $value;
echo $value;
}
Ensuite, la requête GET /test donnera exactement la même sortie que l'exemple précédent.
Cette directive peut être invoquée par l'interface ndk.set_var.DIRECTIVE du lua-nginx-module et la directive array_map_op du array-var-nginx-module.
set_decode_hex
syntax: set_decode_hex $dst <src>
syntax: set_decode_hex $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Similaire à la directive set_encode_hex, mais effectue exactement l'opération inverse, c'est-à-dire, décode un digest hexadécimal dans sa forme originale.
set_sha1
syntax: set_sha1 $dst <src>
syntax: set_sha1 $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Lorsqu'il prend deux arguments, cette directive va encoder la valeur du deuxième argument <src> en son digest SHA-1 et assigner le résultat au premier argument, la variable $dst. La forme hexadécimale du digest SHA-1 sera générée automatiquement, utilisez set_decode_hex pour décoder le résultat si vous souhaitez la forme binaire du digest SHA-1.
Par exemple,
location /test {
set $raw "hello";
set_sha1 $digest $raw;
echo $digest;
}
Ensuite, la requête GET /test donnera la sortie suivante
aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Lorsqu'il prend un seul argument, cette directive effectuera une modification en place de la variable d'argument. Par exemple,
location /test {
set $value "hello";
set_sha1 $value;
echo $value;
}
Ensuite, la requête GET /test donnera exactement la même sortie que l'exemple précédent.
Cette directive peut être invoquée par l'interface ndk.set_var.DIRECTIVE du lua-nginx-module et la directive array_map_op du array-var-nginx-module.
set_md5
syntax: set_md5 $dst <src>
syntax: set_md5 $dst
default: non
context: location, location if
phase: rewrite
category: ndk_set_var_value
Lorsqu'il prend deux arguments, cette directive va encoder la valeur du deuxième argument <src> en son digest MD5 et assigner le résultat au premier argument, la variable $dst. La forme hexadécimale du digest MD5 sera générée automatiquement, utilisez set_decode_hex pour décoder le résultat si vous souhaitez la forme binaire du digest MD5.
Par exemple,
location /test {
set $raw "hello";
set_md5 $digest $raw;
echo $digest;
}
Ensuite, la requête GET /test donnera la sortie suivante
5d41402abc4b2a76b9719d911017c592
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Lorsqu'il prend un seul argument, cette directive effectuera une modification en place de la variable d'argument. Par exemple,
location /test {
set $value "hello";
set_md5 $value;
echo $value;
}
Ensuite, la requête GET /test donnera exactement la même sortie que l'exemple précédent.
Cette directive peut être invoquée par l'interface ndk.set_var.DIRECTIVE du lua-nginx-module et la directive array_map_op du array-var-nginx-module.
set_hmac_sha1
syntax: set_hmac_sha1 $dst <secret_key> <src>
syntax: set_hmac_sha1 $dst
default: non
context: location, location if
phase: rewrite
Calcule le digest HMAC-SHA1 de l'argument <src> et assigne le résultat à la variable d'argument $dst avec la clé secrète <secret_key>.
La forme binaire brute du digest HMAC-SHA1 sera générée, utilisez set_encode_base64, par exemple, pour encoder le résultat en une représentation textuelle si désiré.
Par exemple,
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;
}
Ensuite, la requête GET /test donnera la sortie suivante
R/pvxzHC4NLtj7S+kXFg/NePTmk=
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Cette directive nécessite que la bibliothèque OpenSSL soit activée dans votre compilation NGINX (généralement en passant l'option --with-http_ssl_module au script ./configure).
set_hmac_sha256
syntax: set_hmac_sha256 $dst <secret_key> <src>
syntax: set_hmac_sha256 $dst
default: non
context: location, location if
phase: rewrite
Calcule le digest HMAC-SHA256 de l'argument <src> et assigne le résultat à la variable d'argument $dst avec la clé secrète <secret_key>.
La forme binaire brute du digest HMAC-SHA256 sera générée, utilisez set_encode_base64, par exemple, pour encoder le résultat en une représentation textuelle si désiré.
Par exemple,
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;
}
Ensuite, la requête GET /test donnera la sortie suivante
4pU3GRQrKKIoeLb9CqYsavHE2l6Hx+KMmRmesU+Cfrs=
Veuillez noter que nous utilisons la directive echo-nginx-module's echo directive ici pour afficher directement les valeurs des variables nginx.
Cette directive nécessite que la bibliothèque OpenSSL soit activée dans votre compilation NGINX (généralement en passant l'option --with-http_ssl_module au script ./configure).
set_random
syntax: set_random $res <from> <to>
default: non
context: location, location if
phase: rewrite
Génère un nombre (pseudo) aléatoire (sous forme textuelle) dans la plage [<$from>, <$to>] (inclusif).
Seuls les nombres non négatifs sont autorisés pour les arguments <from> et <to>.
Lorsque <from> est supérieur à <to>, leurs valeurs seront échangées en conséquence.
Par exemple,
location /test {
set $from 5;
set $to 7;
set_random $res $from $to;
echo $res;
}
Ensuite, la requête GET /test affichera un nombre entre 5 et 7 (c'est-à-dire, parmi 5, 6, 7).
Pour l'instant, il n'y a aucun moyen de configurer une graine de générateur aléatoire personnalisée.
En coulisse, cela utilise la fonction standard C rand().
Cette directive a été introduite pour la première fois dans la version v0.22rc1.
Voir aussi set_secure_random_alphanum et set_secure_random_lcalpha.
set_secure_random_alphanum
syntax: set_secure_random_alphanum $res <length>
default: non
context: location, location if
phase: rewrite
Génère une chaîne aléatoire cryptographiquement sécurisée de <length> caractères avec l'alphabet [a-zA-Z0-9].
<length> peut être compris entre 1 et 64, inclus.
Par exemple,
location /test {
set_secure_random_alphanum $res 32;
echo $res;
}
Ensuite, la requête GET /test affichera une chaîne comme ivVVRP2DGaAqDmdf3Rv4ZDJ7k0gOfASz.
Cette fonctionnalité dépend de la présence du périphérique /dev/urandom, disponible sur la plupart des systèmes de type UNIX.
Voir aussi set_secure_random_lcalpha et set_random.
Cette directive a été introduite pour la première fois dans la version v0.22rc8.
set_secure_random_lcalpha
syntax: set_secure_random_lcalpha $res <length>
default: non
context: location, location if
phase: rewrite
Génère une chaîne aléatoire cryptographiquement sécurisée de <length> caractères avec l'alphabet [a-z].
<length> peut être compris entre 1 et 64, inclus.
Par exemple,
location /test {
set_secure_random_lcalpha $res 32;
echo $res;
}
Ensuite, la requête GET /test affichera une chaîne comme kcuxcddktffsippuekhshdaclaquiusj.
Cette fonctionnalité dépend de la présence du périphérique /dev/urandom, disponible sur la plupart des systèmes de type UNIX.
Cette directive a été introduite pour la première fois dans la version v0.22rc8.
Voir aussi set_secure_random_alphanum et set_random.
set_rotate
syntax: set_rotate $value <from> <to>
default: non
context: location, location if
phase: rewrite
Incrémente $value mais le garde dans la plage de <from> à <to>.
Si $value est supérieur à <to> ou inférieur à <from>, il sera
défini sur la valeur <from>.
La valeur actuelle après l'exécution de cette directive sera toujours sauvegardée sur une base par emplacement. Et cette valeur sauvegardée sera utilisée pour l'incrémentation lorsque $value n'est pas initialisé ou a une mauvaise valeur.
Seuls les nombres non négatifs sont autorisés pour les arguments <from> et <to>.
Lorsque <from> est supérieur à <to>, leurs valeurs seront échangées en conséquence.
Par exemple,
location /rotate {
default_type text/plain;
set $counter $cookie_counter;
set_rotate $counter 1 5;
echo $counter;
add_header Set-Cookie counter=$counter;
}
Ensuite, la requête GET /rotate affichera le prochain nombre entre 1 et 5 (c'est-à-dire, 1, 2, 3, 4, 5) à chaque
rafraîchissement de la page. Cette directive peut être utile pour des rotations de bannières.
Un autre exemple est d'utiliser la persistance de valeur côté serveur pour faire un simple round-robin :
location /rotate {
default_type text/plain;
set_rotate $counter 0 3;
echo $counter;
}
Et accéder à /rotate affichera également la séquence entière d'entiers 0, 1, 2, 3, 0, 1, 2, 3, et ainsi de suite.
Cette directive a été introduite pour la première fois dans la version v0.22rc7.
set_local_today
syntax: set_local_today $dst
default: non
context: location, location if
phase: rewrite
Définit la date d'aujourd'hui ("yyyy-mm-dd") en heure locale dans la variable d'argument $dst.
Voici un exemple,
location /today {
set_local_today $today;
echo $today;
}
Ensuite, la requête GET /today affichera quelque chose comme
2011-08-16
et l'année, la date réelle que vous obtiendrez ici variera chaque jour ;)
En coulisse, cette directive utilise l'API ngx_time dans le cœur de NGINX, donc généralement aucun appel système n'est impliqué en raison du mécanisme de mise en cache du temps dans le cœur de NGINX.
set_formatted_gmt_time
syntax: set_formatted_gmt_time $res <time-format>
default: non
context: location, location if
phase: rewrite
Définit un temps GMT formaté dans la variable $res (comme premier argument) en utilisant la chaîne de format dans le deuxième argument.
Toutes les notations de spécification de conversion dans la fonction standard C strftime sont prises en charge, comme %Y (pour les années sur 4 chiffres) et %M (pour les minutes en décimal). Voir http://linux.die.net/man/3/strftime pour une liste complète des symboles de spécification de conversion.
Voici un exemple :
location = /t {
set_formatted_gmt_time $timestr "%a %b %e %H:%M:%S %Y GMT";
echo $timestr;
}
Accéder à /t donne la sortie
Fri Dec 13 15:34:37 2013 GMT
Cette directive a été ajoutée pour la première fois dans la version 0.23.
Voir aussi set_formatted_local_time.
set_formatted_local_time
syntax: set_formatted_local_time $res <time-format>
default: non
context: location, location if
phase: rewrite
Définit un temps local formaté dans la variable $res (comme premier argument) en utilisant la chaîne de format dans le deuxième argument.
Toutes les notations de spécification de conversion dans la fonction standard C strftime sont prises en charge, comme %Y (pour les années sur 4 chiffres) et %M (pour les minutes en décimal). Voir http://linux.die.net/man/3/strftime pour une liste complète des symboles de spécification de conversion.
Voici un exemple :
location = /t {
set_formatted_local_time $timestr "%a %b %e %H:%M:%S %Y %Z";
echo $timestr;
}
Accéder à /t donne la sortie
Fri Dec 13 15:42:15 2013 PST
Cette directive a été ajoutée pour la première fois dans la version 0.23.
Voir aussi set_formatted_gmt_time.
Caveats
Ne pas utiliser $arg_PARAMETER, $cookie_COOKIE, $http_HEADER ou d'autres variables spéciales définies dans le module de base NGINX comme variable cible dans les directives de ce module. Par exemple,
set_if_empty $arg_user 'foo'; # NE PAS UTILISER ÇA !
peut entraîner des fautes de segmentation.
Changes
Les journaux de modifications pour chaque version de ce module peuvent être obtenus à partir des journaux de modifications du bundle OpenResty :
Test Suite
Ce module est livré avec une suite de tests pilotée par Perl. Les cas de test sont également déclaratifs. Merci au module Test::Nginx dans le monde Perl.
Pour l'exécuter de votre côté :
$ PATH=/path/to/your/nginx-with-set-misc-module:$PATH prove -r t
Vous devez terminer tous les processus NGINX avant d'exécuter la suite de tests si vous avez changé le binaire du serveur NGINX.
Parce qu'un seul serveur nginx (par défaut, localhost:1984) est utilisé dans tous les scripts de test (.t fichiers), il est inutile d'exécuter la suite de tests en parallèle en spécifiant -jN lors de l'invocation de l'utilitaire prove.
See Also
GitHub
Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-set-misc.