1<!--- 2Don't edit this file manually! Instead you should generate it by using: 3 wiki2markdown.pl doc/HttpSetMiscModule.wiki 4--> 5 6Name 7==== 8 9**ngx_set_misc** - Various set_xxx directives added to nginx's rewrite module (md5/sha1, sql/json quoting, and many more) 10 11*This module is not distributed with the Nginx source.* See [the installation instructions](#installation). 12 13Table of Contents 14================= 15 16* [Name](#name) 17* [Version](#version) 18* [Synopsis](#synopsis) 19* [Description](#description) 20* [Directives](#directives) 21 * [set_if_empty](#set_if_empty) 22 * [set_quote_sql_str](#set_quote_sql_str) 23 * [set_quote_pgsql_str](#set_quote_pgsql_str) 24 * [set_quote_json_str](#set_quote_json_str) 25 * [set_unescape_uri](#set_unescape_uri) 26 * [set_escape_uri](#set_escape_uri) 27 * [set_hashed_upstream](#set_hashed_upstream) 28 * [set_encode_base32](#set_encode_base32) 29 * [set_base32_padding](#set_base32_padding) 30 * [set_misc_base32_padding](#set_misc_base32_padding) 31 * [set_base32_alphabet](#set_base32_alphabet) 32 * [set_decode_base32](#set_decode_base32) 33 * [set_encode_base64](#set_encode_base64) 34 * [set_decode_base64](#set_decode_base64) 35 * [set_encode_hex](#set_encode_hex) 36 * [set_decode_hex](#set_decode_hex) 37 * [set_sha1](#set_sha1) 38 * [set_md5](#set_md5) 39 * [set_hmac_sha1](#set_hmac_sha1) 40 * [set_random](#set_random) 41 * [set_secure_random_alphanum](#set_secure_random_alphanum) 42 * [set_secure_random_lcalpha](#set_secure_random_lcalpha) 43 * [set_rotate](#set_rotate) 44 * [set_local_today](#set_local_today) 45 * [set_formatted_gmt_time](#set_formatted_gmt_time) 46 * [set_formatted_local_time](#set_formatted_local_time) 47* [Caveats](#caveats) 48* [Installation](#installation) 49 * [Building as a dynamic module](#building-as-a-dynamic-module) 50* [Compatibility](#compatibility) 51* [Report Bugs](#report-bugs) 52* [Source Repository](#source-repository) 53* [Changes](#changes) 54* [Test Suite](#test-suite) 55* [Getting involved](#getting-involved) 56* [Author](#author) 57* [Copyright & License](#copyright--license) 58* [See Also](#see-also) 59 60Version 61======= 62 63This document describes ngx_set_misc [v0.32](https://github.com/openresty/set-misc-nginx-module/tags) released on 19 April 2018. 64 65Synopsis 66======== 67 68```nginx 69 70 location /foo { 71 set $a $arg_a; 72 set_if_empty $a 56; 73 74 # GET /foo?a=32 will yield $a == 32 75 # while GET /foo and GET /foo?a= will 76 # yeild $a == 56 here. 77 } 78 79 location /bar { 80 set $foo "hello\n\n'\"\\"; 81 set_quote_sql_str $foo $foo; # for mysql 82 83 # OR in-place editing: 84 # set_quote_sql_str $foo; 85 86 # now $foo is: 'hello\n\n\'\"\\' 87 } 88 89 location /bar { 90 set $foo "hello\n\n'\"\\"; 91 set_quote_pgsql_str $foo; # for PostgreSQL 92 93 # now $foo is: E'hello\n\n\'\"\\' 94 } 95 96 location /json { 97 set $foo "hello\n\n'\"\\"; 98 set_quote_json_str $foo $foo; 99 100 # OR in-place editing: 101 # set_quote_json_str $foo; 102 103 # now $foo is: "hello\n\n'\"\\" 104 } 105 106 location /baz { 107 set $foo "hello%20world"; 108 set_unescape_uri $foo $foo; 109 110 # OR in-place editing: 111 # set_unescape_uri $foo; 112 113 # now $foo is: hello world 114 } 115 116 upstream_list universe moon sun earth; 117 upstream moon { ... } 118 upstream sun { ... } 119 upstream earth { ... } 120 location /foo { 121 set_hashed_upstream $backend universe $arg_id; 122 drizzle_pass $backend; # used with ngx_drizzle 123 } 124 125 location /base32 { 126 set $a 'abcde'; 127 set_encode_base32 $a; 128 set_decode_base32 $b $a; 129 130 # now $a == 'c5h66p35' and 131 # $b == 'abcde' 132 } 133 134 location /base64 { 135 set $a 'abcde'; 136 set_encode_base64 $a; 137 set_decode_base64 $b $a; 138 139 # now $a == 'YWJjZGU=' and 140 # $b == 'abcde' 141 } 142 143 location /hex { 144 set $a 'abcde'; 145 set_encode_hex $a; 146 set_decode_hex $b $a; 147 148 # now $a == '6162636465' and 149 # $b == 'abcde' 150 } 151 152 # GET /sha1 yields the output 153 # aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d 154 location /sha1 { 155 set_sha1 $a hello; 156 echo $a; 157 } 158 159 # ditto 160 location /sha1 { 161 set $a hello; 162 set_sha1 $a; 163 echo $a; 164 } 165 166 # GET /today yields the date of today in local time using format 'yyyy-mm-dd' 167 location /today { 168 set_local_today $today; 169 echo $today; 170 } 171 172 # GET /signature yields the hmac-sha-1 signature 173 # given a secret and a string to sign 174 # this example yields the base64 encoded singature which is 175 # "HkADYytcoQQzqbjQX33k/ZBB/DQ=" 176 location /signature { 177 set $secret_key 'secret-key'; 178 set $string_to_sign "some-string-to-sign"; 179 set_hmac_sha1 $signature $secret_key $string_to_sign; 180 set_encode_base64 $signature $signature; 181 echo $signature; 182 } 183 184 location = /rand { 185 set $from 3; 186 set $to 15; 187 set_random $rand $from $to; 188 189 # or write directly 190 # set_random $rand 3 15; 191 192 echo $rand; # will print a random integer in the range [3, 15] 193 } 194``` 195 196Description 197=========== 198 199This module extends the standard HttpRewriteModule's directive set to provide more functionalities like URI escaping and unescaping, JSON quoting, Hexadecimal/MD5/SHA1/Base32/Base64 digest encoding and decoding, random number generator, and more! 200 201Every directive provided by this module can be mixed freely with other [ngx_http_rewrite_module](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html)'s directives, like [if](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#if) and [set](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#set). (Thanks to the [Nginx Devel Kit](https://github.com/simpl/ngx_devel_kit)!) 202 203[Back to TOC](#table-of-contents) 204 205Directives 206========== 207 208[Back to TOC](#table-of-contents) 209 210set_if_empty 211------------ 212**syntax:** *set_if_empty $dst <src>* 213 214**default:** *no* 215 216**context:** *location, location if* 217 218**phase:** *rewrite* 219 220Assign the value of the argument `<src>` if and only if variable `$dst` is empty (i.e., not found or has an empty string value). 221 222In the following example, 223 224```nginx 225 226 set $a 32; 227 set_if_empty $a 56; 228``` 229 230the variable `$dst` will take the value 32 at last. But in the sample 231 232```nginx 233 234 set $a ''; 235 set $value "hello, world" 236 set_if_empty $a $value; 237``` 238 239`$a` will take the value `"hello, world"` at last. 240 241[Back to TOC](#table-of-contents) 242 243set_quote_sql_str 244----------------- 245**syntax:** *set_quote_sql_str $dst <src>* 246 247**syntax:** *set_quote_sql_str $dst* 248 249**default:** *no* 250 251**context:** *location, location if* 252 253**phase:** *rewrite* 254 255**category:** *ndk_set_var_value* 256 257When taking two arguments, this directive will quote the value of the second argument `<src>` by MySQL's string value quoting rule and assign the result into the first argument, variable `$dst`. For example, 258 259```nginx 260 261 location /test { 262 set $value "hello\n\r'\"\\"; 263 set_quote_sql_str $quoted $value; 264 265 echo $quoted; 266 } 267``` 268 269Then request `GET /test` will yield the following output 270 271```sql 272 273 'hello\n\r\'\"\\' 274``` 275 276Please note that we're using [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s [echo directive](http://github.com/openresty/echo-nginx-module#echo) here to output values of nginx variables directly. 277 278When taking a single argument, this directive will do in-place modification of the argument variable. For example, 279 280```nginx 281 282 location /test { 283 set $value "hello\n\r'\"\\"; 284 set_quote_sql_str $value; 285 286 echo $value; 287 } 288``` 289 290then request `GET /test` will give exactly the same output as the previous example. 291 292This directive is usually used to prevent SQL injection. 293 294This directive can be invoked by [lua-nginx-module](http://github.com/openresty/lua-nginx-module)'s [ndk.set_var.DIRECTIVE](http://github.com/openresty/lua-nginx-module#ndkset_vardirective) interface and [array-var-nginx-module](http://github.com/openresty/array-var-nginx-module)'s [array_map_op](http://github.com/openresty/array-var-nginx-module#array_map_op) directive. 295 296[Back to TOC](#table-of-contents) 297 298set_quote_pgsql_str 299------------------- 300**syntax:** *set_quote_pgsql_str $dst <src>* 301 302**syntax:** *set_quote_pgsql_str $dst* 303 304**default:** *no* 305 306**context:** *location, location if* 307 308**phase:** *rewrite* 309 310**category:** *ndk_set_var_value* 311 312Very much like [set_quote_sql_str](#set_quote_sql_str), but with PostgreSQL quoting rules for SQL string literals. 313 314[Back to TOC](#table-of-contents) 315 316set_quote_json_str 317------------------ 318**syntax:** *set_quote_json_str $dst <src>* 319 320**syntax:** *set_quote_json_str $dst* 321 322**default:** *no* 323 324**context:** *location, location if* 325 326**phase:** *rewrite* 327 328**category:** *ndk_set_var_value* 329 330When taking two arguments, this directive will quote the value of the second argument `<src>` by JSON string value quoting rule and assign the result into the first argument, variable `$dst`. For example, 331 332```nginx 333 334 location /test { 335 set $value "hello\n\r'\"\\"; 336 set_quote_json_str $quoted $value; 337 338 echo $quoted; 339 } 340``` 341 342Then request `GET /test` will yield the following output 343 344```javascript 345 346 "hello\n\r'\"\\" 347``` 348 349Please note that we're using [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s [echo directive](http://github.com/openresty/echo-nginx-module#echo) here to output values of nginx variables directly. 350 351When taking a single argument, this directive will do in-place modification of the argument variable. For example, 352 353```nginx 354 355 location /test { 356 set $value "hello\n\r'\"\\"; 357 set_quote_json_str $value; 358 359 echo $value; 360 } 361``` 362 363then request `GET /test` will give exactly the same output as the previous example. 364 365This directive can be invoked by [lua-nginx-module](http://github.com/openresty/lua-nginx-module)'s [ndk.set_var.DIRECTIVE](http://github.com/openresty/lua-nginx-module#ndkset_vardirective) interface and [array-var-nginx-module](http://github.com/openresty/array-var-nginx-module)'s [array_map_op](http://github.com/openresty/array-var-nginx-module#array_map_op) directive. 366 367[Back to TOC](#table-of-contents) 368 369set_unescape_uri 370---------------- 371**syntax:** *set_unescape_uri $dst <src>* 372 373**syntax:** *set_unescape_uri $dst* 374 375**default:** *no* 376 377**context:** *location, location if* 378 379**phase:** *rewrite* 380 381**category:** *ndk_set_var_value* 382 383When taking two arguments, this directive will unescape the value of the second argument `<src>` as a URI component and assign the result into the first argument, variable `$dst`. For example, 384 385```nginx 386 387 location /test { 388 set_unescape_uri $key $arg_key; 389 echo $key; 390 } 391``` 392 393Then request `GET /test?key=hello+world%21` will yield the following output 394 395``` 396hello world! 397``` 398 399The nginx standard [$arg_PARAMETER](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_arg_) variable holds the raw (escaped) value of the URI parameter. So we need the `set_unescape_uri` directive to unescape it first. 400 401Please note that we're using [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s [echo directive](http://github.com/openresty/echo-nginx-module#echo) here to output values of nginx variables directly. 402 403When taking a single argument, this directive will do in-place modification of the argument variable. For example, 404 405```nginx 406 407 location /test { 408 set $key $arg_key; 409 set_unescape_uri $key; 410 411 echo $key; 412 } 413``` 414 415then request `GET /test?key=hello+world%21` will give exactly the same output as the previous example. 416 417This directive can be invoked by [lua-nginx-module](http://github.com/openresty/lua-nginx-module)'s [ndk.set_var.DIRECTIVE](http://github.com/openresty/lua-nginx-module#ndkset_vardirective) interface and [array-var-nginx-module](http://github.com/openresty/array-var-nginx-module)'s [array_map_op](http://github.com/openresty/array-var-nginx-module#array_map_op) directive. 418 419[Back to TOC](#table-of-contents) 420 421set_escape_uri 422-------------- 423**syntax:** *set_escape_uri $dst <src>* 424 425**syntax:** *set_escape_uri $dst* 426 427**default:** *no* 428 429**context:** *location, location if* 430 431**phase:** *rewrite* 432 433**category:** *ndk_set_var_value* 434 435Very much like the [set_unescape_uri](#set_unescape_uri) directive, but does the conversion the other way around, i.e., URL component escaping. 436 437[Back to TOC](#table-of-contents) 438 439set_hashed_upstream 440------------------- 441**syntax:** *set_hashed_upstream $dst <upstream_list_name> <src>* 442 443**default:** *no* 444 445**context:** *location, location if* 446 447**phase:** *rewrite* 448 449Hashes the string argument `<src>` into one of the upstream name included in the upstream list named `<upstream_list_name>`. The hash function being used is simple modulo. 450 451Here's an example, 452 453```nginx 454 455 upstream moon { ... } 456 upstream sun { ... } 457 upstream earth { ... } 458 459 upstream_list universe moon sun earth; 460 461 location /test { 462 set_unescape_uri $key $arg_key; 463 set $list_name universe; 464 set_hashed_upstream $backend $list_name $key; 465 466 echo $backend; 467 } 468``` 469 470Then `GET /test?key=blah` will output either "moon", "sun", or "earth", depending on the actual value of the `key` query argument. 471 472This directive is usually used to compute an nginx variable to be passed to [memc-nginx-module](http://github.com/openresty/memc-nginx-module)'s [memc_pass](http://github.com/openresty/memc-nginx-module#memc_pass) directive, [redis2-nginx-module](http://github.com/openresty/redis2-nginx-module)'s [[HttpRedis2Module#redis2_pass]] directive, and [ngx_http_proxy_module](http://nginx.org/en/docs/http/ngx_http_proxy_module.html)'s [proxy_pass](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) directive, among others. 473 474[Back to TOC](#table-of-contents) 475 476set_encode_base32 477----------------- 478**syntax:** *set_encode_base32 $dst <src>* 479 480**syntax:** *set_encode_base32 $dst* 481 482**default:** *no* 483 484**context:** *location, location if* 485 486**phase:** *rewrite* 487 488**category:** *ndk_set_var_value* 489 490When taking two arguments, this directive will encode the value of the second argument `<src>` to its base32(hex) digest and assign the result into the first argument, variable `$dst`. For example, 491 492```nginx 493 494 location /test { 495 set $raw "abcde"; 496 set_encode_base32 $digest $raw; 497 498 echo $digest; 499 } 500``` 501 502Then request `GET /test` will yield the following output 503 504``` 505c5h66p35 506``` 507 508Please note that we're using [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s [echo directive](http://github.com/openresty/echo-nginx-module#echo) here to output values of nginx variables directly. 509 510RFC forces the `[A-Z2-7]` RFC-3548 compliant encoding, but we are using the "base32hex" encoding (`[0-9a-v]`) by default. The [set_base32_alphabet](#set_base32_alphabet) directive (first introduced in `v0.28`) allows you to change the alphabet used for encoding/decoding so RFC-3548 compliant encoding is still possible by custom configurations. 511 512By default, the `=` character is used to pad the left-over bytes due to alignment. But the padding behavior can be completely disabled by setting [set_base32_padding](#set_base32_padding) `off`. 513 514When taking a single argument, this directive will do in-place modification of the argument variable. For example, 515 516```nginx 517 518 location /test { 519 set $value "abcde"; 520 set_encode_base32 $value; 521 522 echo $value; 523 } 524``` 525 526then request `GET /test` will give exactly the same output as the previous example. 527 528This directive can be invoked by [lua-nginx-module](http://github.com/openresty/lua-nginx-module)'s [ndk.set_var.DIRECTIVE](http://github.com/openresty/lua-nginx-module#ndkset_vardirective) interface and [array-var-nginx-module](http://github.com/openresty/array-var-nginx-module)'s [array_map_op](http://github.com/openresty/array-var-nginx-module#array_map_op) directive. 529 530[Back to TOC](#table-of-contents) 531 532set_base32_padding 533------------------ 534**syntax:** *set_base32_padding on|off* 535 536**default:** *on* 537 538**context:** *http, server, server if, location, location if* 539 540**phase:** *no* 541 542This directive can control whether to pad left-over bytes with the "=" character when encoding a base32 digest by the 543[set_encode_base32](#set_encode_base32) directive. 544 545This directive was first introduced in `v0.28`. If you use earlier versions of this module, then you should use [set_misc_base32_padding](#set_misc_base32_padding) instead. 546 547[Back to TOC](#table-of-contents) 548 549set_misc_base32_padding 550----------------------- 551**syntax:** *set_misc_base32_padding on|off* 552 553**default:** *on* 554 555**context:** *http, server, server if, location, location if* 556 557**phase:** *no* 558 559This directive has been deprecated since `v0.28`. Use [set_base32_padding](#set_base32_padding) instead if you are using `v0.28+`. 560 561[Back to TOC](#table-of-contents) 562 563set_base32_alphabet 564------------------- 565**syntax:** *set_base32_alphabet <alphabet>* 566 567**default:** *"0123456789abcdefghijklmnopqrstuv"* 568 569**context:** *http, server, server if, location, location if* 570 571**phase:** *no* 572 573This directive controls the alphabet used for encoding/decoding a base32 digest. It accepts a string containing the desired alphabet like "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567" for standard alphabet. 574 575Extended (base32hex) alphabet is used by default. 576 577This directive was first introduced in `v0.28`. 578 579[Back to TOC](#table-of-contents) 580 581set_decode_base32 582----------------- 583**syntax:** *set_decode_base32 $dst <src>* 584 585**syntax:** *set_decode_base32 $dst* 586 587**default:** *no* 588 589**context:** *location, location if* 590 591**phase:** *rewrite* 592 593**category:** *ndk_set_var_value* 594 595Similar to the [set_encode_base32](#set_encode_base32) directive, but does exactly the opposite operation, .i.e, decoding a base32(hex) digest into its original form. 596 597[Back to TOC](#table-of-contents) 598 599set_encode_base64 600----------------- 601**syntax:** *set_encode_base64 $dst <src>* 602 603**syntax:** *set_encode_base64 $dst* 604 605**default:** *no* 606 607**context:** *location, location if* 608 609**phase:** *rewrite* 610 611**category:** *ndk_set_var_value* 612 613When taking two arguments, this directive will encode the value of the second argument `<src>` to its base64 digest and assign the result into the first argument, variable `$dst`. For example, 614 615```nginx 616 617 location /test { 618 set $raw "abcde"; 619 set_encode_base64 $digest $raw; 620 621 echo $digest; 622 } 623``` 624 625Then request `GET /test` will yield the following output 626 627``` 628YWJjZGU= 629``` 630 631Please note that we're using [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s [echo directive](http://github.com/openresty/echo-nginx-module#echo) here to output values of nginx variables directly. 632 633When taking a single argument, this directive will do in-place modification of the argument variable. For example, 634 635```nginx 636 637 location /test { 638 set $value "abcde"; 639 set_encode_base64 $value; 640 641 echo $value; 642 } 643``` 644 645then request `GET /test` will give exactly the same output as the previous example. 646 647This directive can be invoked by [lua-nginx-module](http://github.com/openresty/lua-nginx-module)'s [ndk.set_var.DIRECTIVE](http://github.com/openresty/lua-nginx-module#ndkset_vardirective) interface and [array-var-nginx-module](http://github.com/openresty/array-var-nginx-module)'s [array_map_op](http://github.com/openresty/array-var-nginx-module#array_map_op) directive. 648 649[Back to TOC](#table-of-contents) 650 651set_decode_base64 652----------------- 653**syntax:** *set_decode_base64 $dst <src>* 654 655**syntax:** *set_decode_base64 $dst* 656 657**default:** *no* 658 659**context:** *location, location if* 660 661**phase:** *rewrite* 662 663**category:** *ndk_set_var_value* 664 665Similar to the [set_encode_base64](#set_encode_base64) directive, but does exactly the opposite operation, .i.e, decoding a base64 digest into its original form. 666 667[Back to TOC](#table-of-contents) 668 669set_encode_hex 670-------------- 671**syntax:** *set_encode_hex $dst <src>* 672 673**syntax:** *set_encode_hex $dst* 674 675**default:** *no* 676 677**context:** *location, location if* 678 679**phase:** *rewrite* 680 681**category:** *ndk_set_var_value* 682 683When taking two arguments, this directive will encode the value of the second argument `<src>` to its hexadecimal digest and assign the result into the first argument, variable `$dst`. For example, 684 685```nginx 686 687 location /test { 688 set $raw "章亦春"; 689 set_encode_hex $digest $raw; 690 691 echo $digest; 692 } 693``` 694 695Then request `GET /test` will yield the following output 696 697``` 698e7aba0e4baa6e698a5 699``` 700 701Please note that we're using [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s [echo directive](http://github.com/openresty/echo-nginx-module#echo) here to output values of nginx variables directly. 702 703When taking a single argument, this directive will do in-place modification of the argument variable. For example, 704 705```nginx 706 707 location /test { 708 set $value "章亦春"; 709 set_encode_hex $value; 710 711 echo $value; 712 } 713``` 714 715then request `GET /test` will give exactly the same output as the previous example. 716 717This directive can be invoked by [lua-nginx-module](http://github.com/openresty/lua-nginx-module)'s [ndk.set_var.DIRECTIVE](http://github.com/openresty/lua-nginx-module#ndkset_vardirective) interface and [array-var-nginx-module](http://github.com/openresty/array-var-nginx-module)'s [array_map_op](http://github.com/openresty/array-var-nginx-module#array_map_op) directive. 718 719[Back to TOC](#table-of-contents) 720 721set_decode_hex 722-------------- 723**syntax:** *set_decode_hex $dst <src>* 724 725**syntax:** *set_decode_hex $dst* 726 727**default:** *no* 728 729**context:** *location, location if* 730 731**phase:** *rewrite* 732 733**category:** *ndk_set_var_value* 734 735Similar to the [set_encode_hex](#set_encode_hex) directive, but does exactly the opposite operation, .i.e, decoding a hexadecimal digest into its original form. 736 737[Back to TOC](#table-of-contents) 738 739set_sha1 740-------- 741**syntax:** *set_sha1 $dst <src>* 742 743**syntax:** *set_sha1 $dst* 744 745**default:** *no* 746 747**context:** *location, location if* 748 749**phase:** *rewrite* 750 751**category:** *ndk_set_var_value* 752 753When taking two arguments, this directive will encode the value of the second argument `<src>` to its [SHA-1](http://en.wikipedia.org/wiki/SHA-1) digest and assign the result into the first argument, variable `$dst`. The hexadecimal form of the `SHA-1` digest will be generated automatically, use [set_decode_hex](#set_decode_hex) to decode the result if you want the binary form of the `SHA-1` digest. 754 755For example, 756 757```nginx 758 759 location /test { 760 set $raw "hello"; 761 set_sha1 $digest $raw; 762 763 echo $digest; 764 } 765``` 766 767Then request `GET /test` will yield the following output 768 769``` 770aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d 771``` 772 773Please note that we're using [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s [echo directive](http://github.com/openresty/echo-nginx-module#echo) here to output values of nginx variables directly. 774 775When taking a single argument, this directive will do in-place modification of the argument variable. For example, 776 777```nginx 778 779 location /test { 780 set $value "hello"; 781 set_sha1 $value; 782 783 echo $value; 784 } 785``` 786 787then request `GET /test` will give exactly the same output as the previous example. 788 789This directive can be invoked by [lua-nginx-module](http://github.com/openresty/lua-nginx-module)'s [ndk.set_var.DIRECTIVE](http://github.com/openresty/lua-nginx-module#ndkset_vardirective) interface and [array-var-nginx-module](http://github.com/openresty/array-var-nginx-module)'s [array_map_op](http://github.com/openresty/array-var-nginx-module#array_map_op) directive. 790 791[Back to TOC](#table-of-contents) 792 793set_md5 794------- 795**syntax:** *set_md5 $dst <src>* 796 797**syntax:** *set_md5 $dst* 798 799**default:** *no* 800 801**context:** *location, location if* 802 803**phase:** *rewrite* 804 805**category:** *ndk_set_var_value* 806 807When taking two arguments, this directive will encode the value of the second argument `<src>` to its [MD5](http://en.wikipedia.org/wiki/MD5) digest and assign the result into the first argument, variable `$dst`. The hexadecimal form of the `MD5` digest will be generated automatically, use [set_decode_hex](#set_decode_hex) to decode the result if you want the binary form of the `MD5` digest. 808 809For example, 810 811```nginx 812 813 location /test { 814 set $raw "hello"; 815 set_md5 $digest $raw; 816 817 echo $digest; 818 } 819``` 820 821Then request `GET /test` will yield the following output 822 823 824 5d41402abc4b2a76b9719d911017c592 825 826 827Please note that we're using [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s [echo directive](http://github.com/openresty/echo-nginx-module#echo) here to output values of nginx variables directly. 828 829When taking a single argument, this directive will do in-place modification of the argument variable. For example, 830 831```nginx 832 833 location /test { 834 set $value "hello"; 835 set_md5 $value; 836 837 echo $value; 838 } 839``` 840 841then request `GET /test` will give exactly the same output as the previous example. 842 843This directive can be invoked by [lua-nginx-module](http://github.com/openresty/lua-nginx-module)'s [ndk.set_var.DIRECTIVE](http://github.com/openresty/lua-nginx-module#ndkset_vardirective) interface and [array-var-nginx-module](http://github.com/openresty/array-var-nginx-module)'s [array_map_op](http://github.com/openresty/array-var-nginx-module#array_map_op) directive. 844 845[Back to TOC](#table-of-contents) 846 847set_hmac_sha1 848------------- 849**syntax:** *set_hmac_sha1 $dst <secret_key> <src>* 850 851**syntax:** *set_hmac_sha1 $dst* 852 853**default:** *no* 854 855**context:** *location, location if* 856 857**phase:** *rewrite* 858 859Computes the [HMAC-SHA1](http://en.wikipedia.org/wiki/HMAC) digest of the argument `<src>` and assigns the result into the argument variable `$dst` with the secret key `<secret_key>`. 860 861The raw binary form of the `HMAC-SHA1` digest will be generated, use [set_encode_base64](#set_encode_base64), for example, to encode the result to a textual representation if desired. 862 863For example, 864 865```nginx 866 867 location /test { 868 set $secret 'thisisverysecretstuff'; 869 set $string_to_sign 'some string we want to sign'; 870 set_hmac_sha1 $signature $secret $string_to_sign; 871 set_encode_base64 $signature $signature; 872 echo $signature; 873 } 874``` 875 876Then request `GET /test` will yield the following output 877 878``` 879R/pvxzHC4NLtj7S+kXFg/NePTmk= 880``` 881 882Please note that we're using [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s [echo directive](http://github.com/openresty/echo-nginx-module#echo) here to output values of nginx variables directly. 883 884This directive requires the OpenSSL library enabled in your Nignx build (usually by passing the `--with-http_ssl_module` option to the `./configure` script). 885 886[Back to TOC](#table-of-contents) 887 888set_random 889---------- 890**syntax:** *set_random $res <from> <to>* 891 892**default:** *no* 893 894**context:** *location, location if* 895 896**phase:** *rewrite* 897 898Generates a (pseudo) random number (in textual form) within the range `[<$from>, <$to>]` (inclusive). 899 900Only non-negative numbers are allowed for the `<from>` and `<to>` arguments. 901 902When `<from>` is greater than `<to>`, their values will be exchanged accordingly. 903 904For instance, 905 906```nginx 907 908 location /test { 909 set $from 5; 910 set $to 7; 911 set_random $res $from $to; 912 913 echo $res; 914 } 915``` 916 917then request `GET /test` will output a number between 5 and 7 (i.e., among 5, 6, 7). 918 919For now, there's no way to configure a custom random generator seed. 920 921Behind the scene, it makes use of the standard C function `rand()`. 922 923This directive was first introduced in the `v0.22rc1` release. 924 925See also [set_secure_random_alphanum](#set_secure_random_alphanum) and [set_secure_random_lcalpha](#set_secure_random_lcalpha). 926 927[Back to TOC](#table-of-contents) 928 929set_secure_random_alphanum 930-------------------------- 931**syntax:** *set_secure_random_alphanum $res <length>* 932 933**default:** *no* 934 935**context:** *location, location if* 936 937**phase:** *rewrite* 938 939Generates a cryptographically-strong random string `<length>` characters long with the alphabet `[a-zA-Z0-9]`. 940 941`<length>` may be between 1 and 64, inclusive. 942 943For instance, 944 945```nginx 946 947 location /test { 948 set_secure_random_alphanum $res 32; 949 950 echo $res; 951 } 952``` 953 954then request `GET /test` will output a string like `ivVVRP2DGaAqDmdf3Rv4ZDJ7k0gOfASz`. 955 956This functionality depends on the presence of the `/dev/urandom` device, available on most UNIX-like systems. 957 958See also [set_secure_random_lcalpha](#set_secure_random_lcalpha) and [set_random](#set_random). 959 960This directive was first introduced in the `v0.22rc8` release. 961 962[Back to TOC](#table-of-contents) 963 964set_secure_random_lcalpha 965------------------------- 966**syntax:** *set_secure_random_lcalpha $res <length>* 967 968**default:** *no* 969 970**context:** *location, location if* 971 972**phase:** *rewrite* 973 974Generates a cryptographically-strong random string `<length>` characters long with the alphabet `[a-z]`. 975 976`<length>` may be between 1 and 64, inclusive. 977 978For instance, 979 980```nginx 981 982 location /test { 983 set_secure_random_lcalpha $res 32; 984 985 echo $res; 986 } 987``` 988 989then request `GET /test` will output a string like `kcuxcddktffsippuekhshdaclaquiusj`. 990 991This functionality depends on the presence of the `/dev/urandom` device, available on most UNIX-like systems. 992 993This directive was first introduced in the `v0.22rc8` release. 994 995See also [set_secure_random_alphanum](#set_secure_random_alphanum) and [set_random](#set_random). 996 997[Back to TOC](#table-of-contents) 998 999set_rotate 1000---------- 1001**syntax:** *set_rotate $value <from> <to>* 1002 1003**default:** *no* 1004 1005**context:** *location, location if* 1006 1007**phase:** *rewrite* 1008 1009Increments `$value` but keeps it in range from `<from>` to `<to>`. 1010If `$value` is greater than `<to>` or less than `<from>` is will be 1011set to `<from>` value. 1012 1013The current value after running this directive will always be saved on a per-location basis. And the this saved value will be used for incrementation when the `$value` is not initialized or has a bad value. 1014 1015Only non-negative numbers are allowed for the `<from>` and `<to>` arguments. 1016 1017When `<from>` is greater than `<to>`, their values will be exchanged accordingly. 1018 1019For instance, 1020 1021```nginx 1022 1023 location /rotate { 1024 default_type text/plain; 1025 set $counter $cookie_counter; 1026 set_rotate $counter 1 5; 1027 echo $counter; 1028 add_header Set-Cookie counter=$counter; 1029 } 1030``` 1031 1032then request `GET /rotate` will output next number between 1 and 5 (i.e., 1, 2, 3, 4, 5) on each 1033refresh of the page. This directive may be userful for banner rotation purposes. 1034 1035Another example is to use server-side value persistence to do simple round-robin: 1036 1037```nginx 1038 1039 location /rotate { 1040 default_type text/plain; 1041 set_rotate $counter 0 3; 1042 echo $counter; 1043 } 1044``` 1045 1046And accessing `/rotate` will also output integer sequence 0, 1, 2, 3, 0, 1, 2, 3, and so on. 1047 1048This directive was first introduced in the `v0.22rc7` release. 1049 1050[Back to TOC](#table-of-contents) 1051 1052set_local_today 1053--------------- 1054**syntax:** *set_local_today $dst* 1055 1056**default:** *no* 1057 1058**context:** *location, location if* 1059 1060**phase:** *rewrite* 1061 1062Set today's date ("yyyy-mm-dd") in localtime to the argument variable `$dst`. 1063 1064Here's an example, 1065 1066```nginx 1067 1068 location /today { 1069 set_local_today $today; 1070 echo $today; 1071 } 1072``` 1073 1074then request `GET /today` will output something like 1075 1076``` 10772011-08-16 1078``` 1079 1080and year, the actual date you get here will vary every day ;) 1081 1082Behind the scene, this directive utilizes the `ngx_time` API in the Nginx core, so usually no syscall is involved due to the time caching mechanism in the Nginx core. 1083 1084[Back to TOC](#table-of-contents) 1085 1086set_formatted_gmt_time 1087---------------------- 1088**syntax:** *set_formatted_gmt_time $res <time-format>* 1089 1090**default:** *no* 1091 1092**context:** *location, location if* 1093 1094**phase:** *rewrite* 1095 1096Set a formatted GMT time to variable `$res` (as the first argument) using the format string in the second argument. 1097 1098All the conversion specification notations in the standard C function `strftime` are supported, like `%Y` (for 4-digit years) and `%M` (for minutes in decimal). See <http://linux.die.net/man/3/strftime> for a complete list of conversion specification symbols. 1099 1100Below is an example: 1101 1102```nginx 1103 1104 location = /t { 1105 set_formatted_gmt_time $timestr "%a %b %e %H:%M:%S %Y GMT"; 1106 echo $timestr; 1107 } 1108``` 1109 1110Accessing `/t` yields the output 1111 1112``` 1113Fri Dec 13 15:34:37 2013 GMT 1114``` 1115 1116This directive was first added in the `0.23` release. 1117 1118See also [set_formatted_local_time](#set_formatted_local_time). 1119 1120[Back to TOC](#table-of-contents) 1121 1122set_formatted_local_time 1123------------------------ 1124**syntax:** *set_formatted_local_time $res <time-format>* 1125 1126**default:** *no* 1127 1128**context:** *location, location if* 1129 1130**phase:** *rewrite* 1131 1132Set a formatted local time to variable `$res` (as the first argument) using the format string in the second argument. 1133 1134All the conversion specification notations in the standard C function `strftime` are supported, like `%Y` (for 4-digit years) and `%M` (for minutes in decimal). See <http://linux.die.net/man/3/strftime> for a complete list of conversion specification symbols. 1135 1136Below is an example: 1137 1138```nginx 1139 1140 location = /t { 1141 set_formatted_local_time $timestr "%a %b %e %H:%M:%S %Y %Z"; 1142 echo $timestr; 1143 } 1144``` 1145 1146Accessing `/t` yields the output 1147 1148``` 1149Fri Dec 13 15:42:15 2013 PST 1150``` 1151 1152This directive was first added in the `0.23` release. 1153 1154See also [set_formatted_gmt_time](#set_formatted_gmt_time). 1155 1156[Back to TOC](#table-of-contents) 1157 1158Caveats 1159======= 1160 1161Do not use [$arg_PARAMETER](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_arg_), [$cookie_COOKIE](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_cookie_), [$http_HEADER](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_http_) or other special variables defined in the Nginx core module as the target variable in this module's directives. For instance, 1162 1163```nginx 1164 1165 set_if_empty $arg_user 'foo'; # DO NOT USE THIS! 1166``` 1167 1168may lead to segmentation faults. 1169 1170[Back to TOC](#table-of-contents) 1171 1172Installation 1173============ 1174 1175This module is included and enabled by default in the [OpenResty bundle](http://openresty.org). If you want to install this module manually with your own Nginx source tarball, then follow the steps below: 1176 1177Grab the nginx source code from [nginx.org](http://nginx.org/), for example, 1178the version 1.13.6 (see [nginx compatibility](#compatibility)), and then build the source with this module: 1179 1180```bash 1181 1182 wget 'http://nginx.org/download/nginx-1.13.6.tar.gz' 1183 tar -xzvf nginx-1.13.6.tar.gz 1184 cd nginx-1.13.6/ 1185 1186 # Here we assume you would install you nginx under /opt/nginx/. 1187 ./configure --prefix=/opt/nginx \ 1188 --with-http_ssl_module \ 1189 --add-module=/path/to/ngx_devel_kit \ 1190 --add-module=/path/to/set-misc-nginx-module 1191 1192 make -j2 1193 make install 1194``` 1195 1196Download the latest version of the release tarball of this module from [set-misc-nginx-module file list](http://github.com/openresty/set-misc-nginx-module/tags), and the latest tarball for [ngx_devel_kit](https://github.com/simplresty/ngx_devel_kit) from its [file list](https://github.com/simplresty/ngx_devel_kit/tags). 1197 1198[Back to TOC](#table-of-contents) 1199 1200Building as a dynamic module 1201---------------------------- 1202 1203Starting from NGINX 1.9.11, you can also compile this module as a dynamic module, by using the `--add-dynamic-module=PATH` option instead of `--add-module=PATH` on the 1204`./configure` command line above. And then you can explicitly load the module in your `nginx.conf` via the [load_module](http://nginx.org/en/docs/ngx_core_module.html#load_module) 1205directive, for example, 1206 1207```nginx 1208load_module /path/to/modules/ndk_http_module.so; # assuming NDK is built as a dynamic module too 1209load_module /path/to/modules/ngx_http_set_misc_module.so; 1210``` 1211 1212Also, this module is included and enabled by default in the [OpenResty bundle](http://openresty.org/). 1213 1214[Back to TOC](#table-of-contents) 1215 1216Compatibility 1217============= 1218 1219The following versions of Nginx should work with this module: 1220 1221* **1.13.x** (last tested: 1.13.6) 1222* **1.12.x** 1223* **1.11.x** (last tested: 1.11.2) 1224* **1.10.x** 1225* **1.9.x** (last tested: 1.9.15) 1226* **1.8.x** 1227* **1.7.x** (last tested: 1.7.10) 1228* **1.6.x** 1229* **1.5.x** (last tested: 1.5.8) 1230* **1.4.x** (last tested: 1.4.4) 1231* **1.2.x** (last tested: 1.2.9) 1232* **1.1.x** (last tested: 1.1.5) 1233* **1.0.x** (last tested: 1.0.15) 1234* **0.9.x** (last tested: 0.9.4) 1235* **0.8.x** (last tested: 0.8.54) 1236* **0.7.x >= 0.7.46** (last tested: 0.7.68) 1237 1238If you find that any particular version of Nginx above 0.7.46 does not work with this module, please consider [reporting a bug](#report-bugs). 1239 1240[Back to TOC](#table-of-contents) 1241 1242Report Bugs 1243=========== 1244 1245Although a lot of effort has been put into testing and code tuning, there must be some serious bugs lurking somewhere in this module. So whenever you are bitten by any quirks, please don't hesitate to 1246 12471. send a bug report or even patches to the [openresty-en mailing list](https://groups.google.com/group/openresty-en), 12481. or create a ticket on the [issue tracking interface](http://github.com/openresty/set-misc-nginx-module/issues) provided by GitHub. 1249 1250[Back to TOC](#table-of-contents) 1251 1252Source Repository 1253================= 1254 1255Available on github at [openresty/set-misc-nginx-module](http://github.com/openresty/set-misc-nginx-module). 1256 1257[Back to TOC](#table-of-contents) 1258 1259Changes 1260======= 1261 1262The change logs for every release of this module can be obtained from the OpenResty bundle's change logs: 1263 1264<http://openresty.org/#Changes> 1265 1266[Back to TOC](#table-of-contents) 1267 1268Test Suite 1269========== 1270 1271This module comes with a Perl-driven test suite. The [test cases](http://github.com/openresty/set-misc-nginx-module/tree/master/t/) are 1272[declarative](http://github.com/openresty/set-misc-nginx-module/blob/master/t/escape-uri.t) too. Thanks to the [Test::Nginx](http://search.cpan.org/perldoc?Test::Nginx) module in the Perl world. 1273 1274To run it on your side: 1275 1276```bash 1277 1278 $ PATH=/path/to/your/nginx-with-set-misc-module:$PATH prove -r t 1279``` 1280 1281You need to terminate any Nginx processes before running the test suite if you have changed the Nginx server binary. 1282 1283Because a single nginx server (by default, `localhost:1984`) is used across all the test scripts (`.t` files), it's meaningless to run the test suite in parallel by specifying `-jN` when invoking the `prove` utility. 1284 1285[Back to TOC](#table-of-contents) 1286 1287Getting involved 1288================ 1289 1290You'll be very welcomed to submit patches to the [author](#author) or just ask for a commit bit to the [source repository](#source-repository) on GitHub. 1291 1292[Back to TOC](#table-of-contents) 1293 1294Author 1295====== 1296 1297Yichun Zhang (agentzh) *<agentzh@gmail.com>*, OpenResty Inc. 1298 1299This wiki page is also maintained by the author himself, and everybody is encouraged to improve this page as well. 1300 1301[Back to TOC](#table-of-contents) 1302 1303Copyright & License 1304=================== 1305 1306Copyright (C) 2009-2018, Yichun Zhang (章亦春) <agentzh@gmail.com>, OpenResty Inc. 1307 1308This module is licensed under the terms of the BSD license. 1309 1310Redistribution and use in source and binary forms, with or without 1311modification, are permitted provided that the following conditions 1312are met: 1313 1314* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 1315* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 1316 1317THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 1318"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 1319LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 1320A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 1321HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 1322SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 1323TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 1324PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 1325LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 1326NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 1327SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 1328 1329[Back to TOC](#table-of-contents) 1330 1331See Also 1332======== 1333* [Nginx Devel Kit](https://github.com/simpl/ngx_devel_kit) 1334* [The OpenResty bundle](http://openresty.org) 1335 1336[Back to TOC](#table-of-contents) 1337 1338