{"id":13635814,"url":"https://github.com/openresty/echo-nginx-module","last_synced_at":"2025-05-15T20:03:27.203Z","repository":{"id":675347,"uuid":"318905","full_name":"openresty/echo-nginx-module","owner":"openresty","description":"An Nginx module for bringing the power of \"echo\", \"sleep\", \"time\" and more to Nginx's config file","archived":false,"fork":false,"pushed_at":"2024-08-17T12:36:17.000Z","size":1219,"stargazers_count":1186,"open_issues_count":30,"forks_count":255,"subscribers_count":83,"default_branch":"master","last_synced_at":"2025-05-15T20:03:24.267Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://wiki.nginx.org/NginxHttpEchoModule","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"natify/nexmos","license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openresty.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2009-09-27T09:37:17.000Z","updated_at":"2025-05-14T16:31:56.000Z","dependencies_parsed_at":"2023-07-06T11:31:36.124Z","dependency_job_id":"c64aaae8-c17a-4915-88a1-e7605c37518b","html_url":"https://github.com/openresty/echo-nginx-module","commit_stats":{"total_commits":485,"total_committers":14,"mean_commits":"34.642857142857146","dds":0.06391752577319587,"last_synced_commit":"6b11aa8f844d0770bbfdd271bf44f0237c43d23b"},"previous_names":[],"tags_count":84,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fecho-nginx-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fecho-nginx-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fecho-nginx-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fecho-nginx-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openresty","download_url":"https://codeload.github.com/openresty/echo-nginx-module/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414493,"owners_count":22067271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T00:00:52.393Z","updated_at":"2025-05-15T20:03:25.288Z","avatar_url":"https://github.com/openresty.png","language":"C","funding_links":[],"categories":["Modules","Third Modules","Third Party Modules","C","Lua and OpenResty ecosystem"],"sub_categories":["C Modules"],"readme":"Name\n====\n\n**ngx_echo** - Brings \"echo\", \"sleep\", \"time\", \"exec\" and more shell-style goodies to Nginx config file.\n\n*This module is not distributed with the Nginx source.* See [the installation instructions](#installation).\n\nTable of Contents\n=================\n\n* [Name](#name)\n* [Status](#status)\n* [Version](#version)\n* [Synopsis](#synopsis)\n* [Description](#description)\n* [Content Handler Directives](#content-handler-directives)\n    * [echo](#echo)\n    * [echo_duplicate](#echo_duplicate)\n    * [echo_flush](#echo_flush)\n    * [echo_sleep](#echo_sleep)\n    * [echo_blocking_sleep](#echo_blocking_sleep)\n    * [echo_reset_timer](#echo_reset_timer)\n    * [echo_read_request_body](#echo_read_request_body)\n    * [echo_location_async](#echo_location_async)\n    * [echo_location](#echo_location)\n    * [echo_subrequest_async](#echo_subrequest_async)\n    * [echo_subrequest](#echo_subrequest)\n    * [echo_foreach_split](#echo_foreach_split)\n    * [echo_end](#echo_end)\n    * [echo_request_body](#echo_request_body)\n    * [echo_exec](#echo_exec)\n    * [echo_status](#echo_status)\n* [Filter Directives](#filter-directives)\n    * [echo_before_body](#echo_before_body)\n    * [echo_after_body](#echo_after_body)\n* [Variables](#variables)\n    * [$echo_it](#echo_it)\n    * [$echo_timer_elapsed](#echo_timer_elapsed)\n    * [$echo_request_body](#echo_request_body)\n    * [$echo_request_method](#echo_request_method)\n    * [$echo_client_request_method](#echo_client_request_method)\n    * [$echo_client_request_headers](#echo_client_request_headers)\n    * [$echo_cacheable_request_uri](#echo_cacheable_request_uri)\n    * [$echo_request_uri](#echo_request_uri)\n    * [$echo_incr](#echo_incr)\n    * [$echo_response_status](#echo_response_status)\n* [Installation](#installation)\n* [Compatibility](#compatibility)\n* [Modules that use this module for testing](#modules-that-use-this-module-for-testing)\n* [Community](#community)\n    * [English Mailing List](#english-mailing-list)\n    * [Chinese Mailing List](#chinese-mailing-list)\n* [Report Bugs](#report-bugs)\n* [Source Repository](#source-repository)\n* [Changes](#changes)\n* [Test Suite](#test-suite)\n* [TODO](#todo)\n* [Getting involved](#getting-involved)\n* [Author](#author)\n* [Copyright \u0026 License](#copyright--license)\n* [See Also](#see-also)\n\nStatus\n======\n\nThis module is production ready.\n\nVersion\n=======\n\nThis document describes ngx_echo [v0.63](https://github.com/openresty/echo-nginx-module/tags) released on 1 August, 2022.\n\nSynopsis\n========\n\n```nginx\n\n   location /hello {\n     echo \"hello, world!\";\n   }\n```\n\n```nginx\n\n   location /hello {\n     echo -n \"hello, \";\n     echo \"world!\";\n   }\n```\n\n```nginx\n\n   location /timed_hello {\n     echo_reset_timer;\n     echo hello world;\n     echo \"'hello world' takes about $echo_timer_elapsed sec.\";\n     echo hiya igor;\n     echo \"'hiya igor' takes about $echo_timer_elapsed sec.\";\n   }\n```\n\n```nginx\n\n   location /echo_with_sleep {\n     echo hello;\n     echo_flush;  # ensure the client can see previous output immediately\n     echo_sleep   2.5;  # in sec\n     echo world;\n   }\n```\n\n```nginx\n\n   # in the following example, accessing /echo yields\n   #   hello\n   #   world\n   #   blah\n   #   hiya\n   #   igor\n   location /echo {\n       echo_before_body hello;\n       echo_before_body world;\n       proxy_pass $scheme://127.0.0.1:$server_port$request_uri/more;\n       echo_after_body hiya;\n       echo_after_body igor;\n   }\n   location /echo/more {\n       echo blah;\n   }\n```\n\n```nginx\n\n   # the output of /main might be\n   #   hello\n   #   world\n   #   took 0.000 sec for total.\n   # and the whole request would take about 2 sec to complete.\n   location /main {\n       echo_reset_timer;\n\n       # subrequests in parallel\n       echo_location_async /sub1;\n       echo_location_async /sub2;\n\n       echo \"took $echo_timer_elapsed sec for total.\";\n   }\n   location /sub1 {\n       echo_sleep 2;\n       echo hello;\n   }\n   location /sub2 {\n       echo_sleep 1;\n       echo world;\n   }\n```\n\n```nginx\n\n   # the output of /main might be\n   #   hello\n   #   world\n   #   took 3.003 sec for total.\n   # and the whole request would take about 3 sec to complete.\n   location /main {\n       echo_reset_timer;\n\n       # subrequests in series (chained by CPS)\n       echo_location /sub1;\n       echo_location /sub2;\n\n       echo \"took $echo_timer_elapsed sec for total.\";\n   }\n   location /sub1 {\n       echo_sleep 2;\n       echo hello;\n   }\n   location /sub2 {\n       echo_sleep 1;\n       echo world;\n   }\n```\n\n```nginx\n\n   # Accessing /dup gives\n   #   ------ END ------\n   location /dup {\n     echo_duplicate 3 \"--\";\n     echo_duplicate 1 \" END \";\n     echo_duplicate 3 \"--\";\n     echo;\n   }\n```\n\n```nginx\n\n   # /bighello will generate 1000,000,000 hello's.\n   location /bighello {\n     echo_duplicate 1000_000_000 'hello';\n   }\n```\n\n```nginx\n\n   # echo back the client request\n   location /echoback {\n     echo_duplicate 1 $echo_client_request_headers;\n     echo \"\\r\";\n\n     echo_read_request_body;\n\n     echo_request_body;\n   }\n```\n\n```nginx\n\n   # GET /multi will yields\n   #   querystring: foo=Foo\n   #   method: POST\n   #   body: hi\n   #   content length: 2\n   #   ///\n   #   querystring: bar=Bar\n   #   method: PUT\n   #   body: hello\n   #   content length: 5\n   #   ///\n   location /multi {\n       echo_subrequest_async POST '/sub' -q 'foo=Foo' -b 'hi';\n       echo_subrequest_async PUT '/sub' -q 'bar=Bar' -b 'hello';\n   }\n   location /sub {\n       echo \"querystring: $query_string\";\n       echo \"method: $echo_request_method\";\n       echo \"body: $echo_request_body\";\n       echo \"content length: $http_content_length\";\n       echo '///';\n   }\n```\n\n```nginx\n\n   # GET /merge?/foo.js\u0026/bar/blah.js\u0026/yui/baz.js will merge the .js resources together\n   location /merge {\n       default_type 'text/javascript';\n       echo_foreach_split '\u0026' $query_string;\n           echo \"/* JS File $echo_it */\";\n           echo_location_async $echo_it;\n           echo;\n       echo_end;\n   }\n```\n\n```nginx\n\n   # accessing /if?val=abc yields the \"hit\" output\n   # while /if?val=bcd yields \"miss\":\n   location ^~ /if {\n       set $res miss;\n       if ($arg_val ~* '^a') {\n           set $res hit;\n           echo $res;\n       }\n       echo $res;\n   }\n```\n\n[Back to TOC](#table-of-contents)\n\nDescription\n===========\n\nThis module wraps lots of Nginx internal APIs for streaming input and output, parallel/sequential subrequests, timers and sleeping, as well as various meta data accessing.\n\nBasically it provides various utilities that help testing and debugging of other modules by trivially emulating different kinds of faked subrequest locations.\n\nPeople will also find it useful in real-world applications that need to\n\n1. serve static contents directly from memory (loading from the Nginx config file).\n1. wrap the upstream response with custom header and footer (kinda like the [addition module](http://nginx.org/en/docs/http/ngx_http_addition_module.html) but with contents read directly from the config file and Nginx variables).\n1. merge contents of various \"Nginx locations\" (i.e., subrequests) together in a single main request (using [echo_location](#echo_location) and its friends).\n\nThis is a special dual-role module that can *lazily* serve as a content handler or register itself as an output filter only upon demand. By default, this module does not do anything at all.\n\nTechnically, this module has also demonstrated the following techniques that might be helpful for module writers:\n\n1. Issue parallel subrequests directly from content handler.\n1. Issue chained subrequests directly from content handler, by passing continuation along the subrequest chain.\n1. Issue subrequests with all HTTP 1.1 methods and even an optional faked HTTP request body.\n1. Interact with the Nginx event model directly from content handler using custom events and timers, and resume the content handler back if necessary.\n1. Dual-role module that can (lazily) serve as a content handler or an output filter or both.\n1. Nginx config file variable creation and interpolation.\n1. Streaming output control using output_chain, flush and its friends.\n1. Read client request body from the content handler, and returns back (asynchronously) to the content handler after completion.\n1. Use Perl-based declarative [test suite](#test-suite) to drive the development of Nginx C modules.\n\n[Back to TOC](#table-of-contents)\n\nContent Handler Directives\n==========================\n\nUse of the following directives register this module to the current Nginx location as a content handler. If you want to use another module, like the [standard proxy module](http://nginx.org/en/docs/http/ngx_http_proxy_module.html), as the content handler, use the [filter directives](#filter-directives) provided by this module.\n\nAll the content handler directives can be mixed together in a single Nginx location and they're supposed to run sequentially just as in the Bash scripting language.\n\nEvery content handler directive supports variable interpolation in its arguments (if any).\n\nThe MIME type set by the [standard default_type directive](http://nginx.org/en/docs/http/ngx_http_core_module.html#default_type) is respected by this module, as in:\n\n```nginx\n\n   location /hello {\n     default_type text/plain;\n     echo hello;\n   }\n```\n\nThen on the client side:\n\n```bash\n\n   $ curl -I 'http://localhost/echo'\n   HTTP/1.1 200 OK\n   Server: nginx/0.8.20\n   Date: Sat, 17 Oct 2009 03:40:19 GMT\n   Content-Type: text/plain\n   Connection: keep-alive\n```\n\nSince the [v0.22](#v022) release, all of the directives are allowed in the [rewrite module](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html)'s [if](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#if) directive block, for instance:\n\n```nginx\n\n location ^~ /if {\n     set $res miss;\n     if ($arg_val ~* '^a') {\n         set $res hit;\n         echo $res;\n     }\n     echo $res;\n }\n```\n\n[Back to TOC](#table-of-contents)\n\necho\n----\n**syntax:** *echo \\[options\\] \u0026lt;string\u0026gt;...*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nSends arguments joined by spaces, along with a trailing newline, out to the client.\n\nNote that the data might be buffered by Nginx's underlying buffer. To force the output data flushed immediately, use the [echo_flush](#echo_flush) command just after `echo`, as in\n\n```nginx\n\n    echo hello world;\n    echo_flush;\n```\n\nWhen no argument is specified, *echo* emits the trailing newline alone, just like the *echo* command in shell.\n\nVariables may appear in the arguments. An example is\n\n```nginx\n\n    echo The current request uri is $request_uri;\n```\n\nwhere [$request_uri](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_uri) is a variable exposed by the [ngx_http_core_module](http://nginx.org/en/docs/http/ngx_http_core_module.html).\n\nThis command can be used multiple times in a single location configuration, as in\n\n```nginx\n\n location /echo {\n     echo hello;\n     echo world;\n }\n```\n\nThe output on the client side looks like this\n\n```bash\n\n $ curl 'http://localhost/echo'\n hello\n world\n```\n\nSpecial characters like newlines (`\\n`) and tabs (`\\t`) can be escaped using C-style escaping sequences. But a notable exception is the dollar sign (`$`). As of Nginx 0.8.20, there's still no clean way to escape this character. (A work-around might be to use a `$echo_dollor` variable that is always evaluated to the constant `$` character. This feature will possibly be introduced in a future version of this module.)\n\nAs of the echo [v0.28](#v028) release, one can suppress the trailing newline character in the output by using the `-n` option, as in\n\n```nginx\n\n location /echo {\n     echo -n \"hello, \";\n     echo \"world\";\n }\n```\n\nAccessing `/echo` gives\n\n```bash\n\n $ curl 'http://localhost/echo'\n hello, world\n```\n\nLeading `-n` in variable values won't take effect and will be emitted literally, as in\n\n```nginx\n\n location /echo {\n     set $opt -n;\n     echo $opt \"hello,\";\n     echo \"world\";\n }\n```\n\nThis gives the following output\n\n```bash\n\n $ curl 'http://localhost/echo'\n -n hello,\n world\n```\n\nOne can output leading `-n` literals and other options using the special `--` option like this\n\n```nginx\n\n location /echo {\n     echo -- -n is an option;\n }\n```\n\nwhich yields\n\n```bash\n\n $ curl 'http://localhost/echo'\n -n is an option\n```\n\nUse this form when you want to output anything leading with a dash (`-`).\n\n[Back to TOC](#table-of-contents)\n\necho_duplicate\n--------------\n**syntax:** *echo_duplicate \u0026lt;count\u0026gt; \u0026lt;string\u0026gt;*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nOutputs duplication of a string indicated by the second argument, using the count specified in the first argument.\n\nFor instance,\n\n```nginx\n\n   location /dup {\n       echo_duplicate 3 \"abc\";\n   }\n```\n\nwill lead to the output of `\"abcabcabc\"`.\n\nUnderscores are allowed in the count number, just like in Perl. For example, to emit 1000,000,000 instances of `\"hello, world\"`:\n\n```nginx\n\n   location /many_hellos {\n       echo_duplicate 1000_000_000 \"hello, world\";\n   }\n```\n\nThe `count` argument could be zero, but not negative. The second `string` argument could be an empty string (\"\") likewise.\n\nUnlike the [echo](#echo) directive, no trailing newline is appended to the result. So it's possible to \"abuse\" this directive as a no-trailing-newline version of [echo](#echo) by using \"count\" 1, as in\n\n```nginx\n\n   location /echo_art {\n       echo_duplicate 2 '---';\n       echo_duplicate 1 ' END ';  # we don't want a trailing newline here\n       echo_duplicate 2 '---';\n       echo;  # we want a trailing newline here...\n   }\n```\n\nYou get\n\n```bash\n   ------ END ------\n```\n\nBut use of the `-n` option in [echo](#echo) is more appropriate for this purpose.\n\nThis directive was first introduced in [version 0.11](#v011).\n\n[Back to TOC](#table-of-contents)\n\necho_flush\n----------\n**syntax:** *echo_flush*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nForces the data potentially buffered by underlying Nginx output filters to send immediately to the client side via socket.\n\nNote that techically the command just emits a ngx_buf_t object with `flush` slot set to 1, so certain weird third-party output filter module could still block it before it reaches Nginx's (last) write filter.\n\nThis directive does not take any argument.\n\nConsider the following example:\n\n```nginx\n\n   location /flush {\n      echo hello;\n\n      echo_flush;\n\n      echo_sleep 1;\n      echo world;\n   }\n```\n\nThen on the client side, using curl to access `/flush`, you'll see the \"hello\" line immediately, but only after 1 second, the last \"world\" line. Without calling `echo_flush` in the example above, you'll most likely see no output until 1 second is elapsed due to the internal buffering of Nginx.\n\nThis directive will fail to flush the output buffer in case of subrequests get involved. Consider the following example:\n\n```nginx\n\n   location /main {\n       echo_location_async /sub;\n       echo hello;\n       echo_flush;\n   }\n   location /sub {\n       echo_sleep 1;\n   }\n```\n\nThen the client won't see \"hello\" appear even if `echo_flush` has been executed before the subrequest to `/sub` has actually started executing. The outputs of `/main` that are sent *after* [echo_location_async](#echo_location_async) will be postponed and buffered firmly.\n\nThis does *not* apply to outputs sent before the subrequest initiated. For a modified version of the example given above:\n\n```nginx\n\n   location /main {\n       echo hello;\n       echo_flush;\n       echo_location_async /sub;\n   }\n   location /sub {\n       echo_sleep 1;\n   }\n```\n\nThe client will immediately see \"hello\" before `/sub` enters sleeping.\n\nSee also [echo](#echo), [echo_sleep](#echo_sleep), and [echo_location_async](#echo_location_async).\n\n[Back to TOC](#table-of-contents)\n\necho_sleep\n----------\n**syntax:** *echo_sleep \u0026lt;seconds\u0026gt;*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nSleeps for the time period specified by the argument, which is in seconds.\n\nThis operation is non-blocking on server side, so unlike the [echo_blocking_sleep](#echo_blocking_sleep) directive, it won't block the whole Nginx worker process.\n\nThe period might takes three digits after the decimal point and must be greater than 0.001.\n\nAn example is\n\n```nginx\n\n    location /echo_after_sleep {\n        echo_sleep 1.234;\n        echo resumed!;\n    }\n```\n\nBehind the scene, it sets up a per-request \"sleep\" ngx_event_t object, and adds a timer using that custom event to the Nginx event model and just waits for a timeout on that event. Because the \"sleep\" event is per-request, this directive can work in parallel subrequests.\n\n[Back to TOC](#table-of-contents)\n\necho_blocking_sleep\n-------------------\n**syntax:** *echo_blocking_sleep \u0026lt;seconds\u0026gt;*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nThis is a blocking version of the [echo_sleep](#echo_sleep) directive.\n\nSee the documentation of [echo_sleep](#echo_sleep) for more detail.\n\nBehind the curtain, it calls the ngx_msleep macro provided by the Nginx core which maps to usleep on POSIX-compliant systems.\n\nNote that this directive will block the current Nginx worker process completely while being executed, so never use it in production environment.\n\n[Back to TOC](#table-of-contents)\n\necho_reset_timer\n----------------\n**syntax:** *echo_reset_timer*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nReset the timer begin time to *now*, i.e., the time when this command is executed during request.\n\nThe timer begin time is default to the starting time of the current request and can be overridden by this directive, potentially multiple times in a single location. For example:\n\n```nginx\n\n   location /timed_sleep {\n       echo_sleep 0.03;\n       echo \"$echo_timer_elapsed sec elapsed.\";\n\n       echo_reset_timer;\n\n       echo_sleep 0.02;\n       echo \"$echo_timer_elapsed sec elapsed.\";\n   }\n```\n\nThe output on the client side might be\n\n```bash\n\n $ curl 'http://localhost/timed_sleep'\n 0.032 sec elapsed.\n 0.020 sec elapsed.\n```\n\nThe actual figures you get on your side may vary a bit due to your system's current activities.\n\nInvocation of this directive will force the underlying Nginx timer to get updated to the current system time (regardless the timer resolution specified elsewhere in the config file). Furthermore, references of the [$echo_timer_elapsed](#echo_timer_elapsed) variable will also trigger timer update forcibly.\n\nSee also [echo_sleep](#echo_sleep) and [$echo_timer_elapsed](#echo_timer_elapsed).\n\n[Back to TOC](#table-of-contents)\n\necho_read_request_body\n----------------------\n**syntax:** *echo_read_request_body*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nExplicitly reads request body so that the [$request_body](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_body) variable will always have non-empty values (unless the body is so big that it has been saved by Nginx to a local temporary file).\n\nNote that this might not be the original client request body because the current request might be a subrequest with a \"artificial\" body specified by its parent.\n\nThis directive does not generate any output itself, just like [echo_sleep](#echo_sleep).\n\nHere's an example for echo'ing back the original HTTP client request (both headers and body are included):\n\n```nginx\n\n   location /echoback {\n     echo_duplicate 1 $echo_client_request_headers;\n     echo \"\\r\";\n     echo_read_request_body;\n     echo $request_body;\n   }\n```\n\nThe content of `/echoback` looks like this on my side (I was using Perl's LWP utility to access this location on the server):\n\n```bash\n\n   $ (echo hello; echo world) | lwp-request -m POST 'http://localhost/echoback'\n   POST /echoback HTTP/1.1\n   TE: deflate,gzip;q=0.3\n   Connection: TE, close\n   Host: localhost\n   User-Agent: lwp-request/5.818 libwww-perl/5.820\n   Content-Length: 12\n   Content-Type: application/x-www-form-urlencoded\n\n   hello\n   world\n```\n\nBecause `/echoback` is the main request, [$request_body](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_body) holds the original client request body.\n\nBefore Nginx 0.7.56, it makes no sense to use this directive because [$request_body](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_body) was first introduced in Nginx 0.7.58.\n\nThis directive itself was first introduced in the echo module's [v0.14 release](#v014).\n\n[Back to TOC](#table-of-contents)\n\necho_location_async\n-------------------\n**syntax:** *echo_location_async \u0026lt;location\u0026gt; [\u0026lt;url_args\u0026gt;]*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nIssue GET subrequest to the location specified (first argument) with optional url arguments specified in the second argument.\n\nAs of Nginx 0.8.20, the `location` argument does *not* support named location, due to a limitation in the `ngx_http_subrequest` function. The same is true for its brother, the [echo_location](#echo_location) directive.\n\nA very simple example is\n\n```nginx\n\n location /main {\n     echo_location_async /sub;\n     echo world;\n }\n location /sub {\n     echo hello;\n }\n```\n\nAccessing `/main` gets\n\n```bash\n\n   hello\n   world\n```\n\nCalling multiple locations in parallel is also possible:\n\n```nginx\n\n location /main {\n     echo_reset_timer;\n     echo_location_async /sub1;\n     echo_location_async /sub2;\n     echo \"took $echo_timer_elapsed sec for total.\";\n }\n location /sub1 {\n     echo_sleep 2; # sleeps 2 sec\n     echo hello;\n }\n location /sub2 {\n     echo_sleep 1; # sleeps 1 sec\n     echo world;\n }\n```\n\nAccessing `/main` yields\n\n```bash\n\n   $ time curl 'http://localhost/main'\n   hello\n   world\n   took 0.000 sec for total.\n\n   real  0m2.006s\n   user  0m0.000s\n   sys   0m0.004s\n```\n\nYou can see that the main handler `/main` does *not* wait the subrequests `/sub1` and `/sub2` to complete and quickly goes on, hence the \"0.000 sec\" timing result. The whole request, however takes approximately 2 sec in total to complete because `/sub1` and `/sub2` run in parallel (or \"concurrently\" to be more accurate).\n\nIf you use [echo_blocking_sleep](#echo_blocking_sleep) in the previous example instead, then you'll get the same output, but with 3 sec total response time, because \"blocking sleep\" blocks the whole Nginx worker process.\n\nLocations can also take an optional querystring argument, for instance\n\n```nginx\n\n location /main {\n     echo_location_async /sub 'foo=Foo\u0026bar=Bar';\n }\n location /sub {\n     echo $arg_foo $arg_bar;\n }\n```\n\nAccessing `/main` yields\n\n```bash\n\n   $ curl 'http://localhost/main'\n   Foo Bar\n```\n\nQuerystrings is *not* allowed to be concatenated onto the `location` argument with \"?\" directly, for example, `/sub?foo=Foo\u0026bar=Bar` is an invalid location, and shouldn't be fed as the first argument to this directive.\n\nTechnically speaking, this directive is an example that Nginx content handler issues one or more subrequests directly. AFAIK, the [fancyindex module](https://connectical.com/projects/ngx-fancyindex/wiki) also does such kind of things ;)\n\nNginx named locations like `@foo` is *not* supported here.\n\nThis directive is logically equivalent to the GET version of [echo_subrequest_async](#echo_subrequest_async). For example,\n\n```nginx\n\n   echo_location_async /foo 'bar=Bar';\n```\n\nis logically equivalent to\n\n```nginx\n\n   echo_subrequest_async GET /foo -q 'bar=Bar';\n```\n\nBut calling this directive is slightly faster than calling [echo_subrequest_async](#echo_subrequest_async) using `GET` because we don't have to parse the HTTP method names like `GET` and options like `-q`.\n\nThis directive is first introduced in [version 0.09](#v009) of this module and requires at least Nginx 0.7.46.\n\n[Back to TOC](#table-of-contents)\n\necho_location\n-------------\n**syntax:** *echo_location \u0026lt;location\u0026gt; [\u0026lt;url_args\u0026gt;]*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nJust like the [echo_location_async](#echo_location_async) directive, but `echo_location` issues subrequests *in series* rather than in parallel. That is, the content handler directives following this directive won't be executed until the subrequest issued by this directive completes.\n\nThe final response body is almost always equivalent to the case when [echo_location_async](#echo_location_async) is used instead, only if timing variables is used in the outputs.\n\nConsider the following example:\n\n```nginx\n\n location /main {\n     echo_reset_timer;\n     echo_location /sub1;\n     echo_location /sub2;\n     echo \"took $echo_timer_elapsed sec for total.\";\n }\n location /sub1 {\n     echo_sleep 2;\n     echo hello;\n }\n location /sub2 {\n     echo_sleep 1;\n     echo world;\n }\n```\n\nThe location `/main` above will take for total 3 sec to complete (compared to 2 sec if [echo_location_async](#echo_location_async) is used instead here). Here's the result in action on my machine:\n\n```bash\n\n   $ curl 'http://localhost/main'\n   hello\n   world\n   took 3.003 sec for total.\n\n   real  0m3.027s\n   user  0m0.020s\n   sys   0m0.004s\n```\n\nThis directive is logically equivalent to the GET version of [echo_subrequest](#echo_subrequest). For example,\n\n```nginx\n\n   echo_location /foo 'bar=Bar';\n```\n\nis logically equivalent to\n\n```nginx\n\n   echo_subrequest GET /foo -q 'bar=Bar';\n```\n\nBut calling this directive is slightly faster than calling [echo_subrequest](#echo_subrequest) using `GET` because we don't have to parse the HTTP method names like `GET` and options like `-q`.\n\nBehind the scene, it creates an `ngx_http_post_subrequest_t` object as a *continuation* and passes it into the `ngx_http_subrequest` function call. Nginx will later reopen this \"continuation\" in the subrequest's `ngx_http_finalize_request` function call. We resumes the execution of the parent-request's content handler and starts to run the next directive (command) if any.\n\nNginx named locations like `@foo` is *not* supported here.\n\nThis directive was first introduced in the [release v0.12](#v012).\n\nSee also [echo_location_async](#echo_location_async) for more details about the meaning of the arguments.\n\n[Back to TOC](#table-of-contents)\n\necho_subrequest_async\n---------------------\n**syntax:** *echo_subrequest_async \u0026lt;HTTP_method\u0026gt; \u0026lt;location\u0026gt; [-q \u0026lt;url_args\u0026gt;] [-b \u0026lt;request_body\u0026gt;] [-f \u0026lt;request_body_path\u0026gt;]*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nInitiate an asynchronous subrequest using HTTP method, an optional url arguments (or querystring) and an optional request body which can be defined as a string or as a path to a file which contains the body.\n\nThis directive is very much like a generalized version of the [echo_location_async](#echo_location_async) directive.\n\nHere's a small example demonstrating its usage:\n\n```nginx\n\n location /multi {\n     # body defined as string\n     echo_subrequest_async POST '/sub' -q 'foo=Foo' -b 'hi';\n     # body defined as path to a file, relative to nginx prefix path if not absolute\n     echo_subrequest_async PUT '/sub' -q 'bar=Bar' -f '/tmp/hello.txt';\n }\n location /sub {\n     echo \"querystring: $query_string\";\n     echo \"method: $echo_request_method\";\n     echo \"body: $echo_request_body\";\n     echo \"content length: $http_content_length\";\n     echo '///';\n }\n```\n\nThen on the client side:\n\n```bash\n\n   $ echo -n hello \u003e /tmp/hello.txt\n   $ curl 'http://localhost/multi'\n   querystring: foo=Foo\n   method: POST\n   body: hi\n   content length: 2\n   ///\n   querystring: bar=Bar\n   method: PUT\n   body: hello\n   content length: 5\n   ///\n```\n\nHere's more funny example using the standard [proxy module](#httpproxymodule) to handle the subrequest:\n\n```nginx\n\n location /main {\n     echo_subrequest_async POST /sub -b 'hello, world';\n }\n location /sub {\n     proxy_pass $scheme://127.0.0.1:$server_port/proxied;\n }\n location /proxied {\n     echo \"method: $echo_request_method.\";\n\n     # we need to read body explicitly here...or $echo_request_body\n     #   will evaluate to empty (\"\")\n     echo_read_request_body;\n\n     echo \"body: $echo_request_body.\";\n }\n```\n\nThen on the client side, we can see that\n\n```bash\n\n   $ curl 'http://localhost/main'\n   method: POST.\n   body: hello, world.\n```\n\nNginx named locations like `@foo` is *not* supported here.\n\nThis directive takes several options:\n\n\n    -q \u003curl_args\u003e        Specify the URL arguments (or URL querystring) for the subrequest.\n\n    -f \u003cpath\u003e            Specify the path for the file whose content will be serve as the\n                         subrequest's request body.\n\n    -b \u003cdata\u003e            Specify the request body data\n\n\nThis directive was first introduced in the [release v0.15](#v015).\n\nThe `-f` option to define a file path for the body was introduced in the [release v0.35](#v035).\n\nSee also the [echo_subrequest](#echo_subrequest) and [echo_location_async](#echo_location_async) directives.\n\n[Back to TOC](#table-of-contents)\n\necho_subrequest\n---------------\n**syntax:** *echo_subrequest \u0026lt;HTTP_method\u0026gt; \u0026lt;location\u0026gt; [-q \u0026lt;url_args\u0026gt;] [-b \u0026lt;request_body\u0026gt;] [-f \u0026lt;request_body_path\u0026gt;]*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nThis is the synchronous version of the [echo_subrequest_async](#echo_subrequest_async) directive. And just like [echo_location](#echo_location), it does not block the Nginx worker process (while [echo_blocking_sleep](#echo_blocking_sleep) does), rather, it uses continuation to pass control along the subrequest chain.\n\nSee [echo_subrequest_async](#echo_subrequest_async) for more details.\n\nNginx named locations like `@foo` is *not* supported here.\n\nThis directive was first introduced in the [release v0.15](#v015).\n\n[Back to TOC](#table-of-contents)\n\necho_foreach_split\n------------------\n**syntax:** *echo_foreach_split \u0026lt;delimiter\u0026gt; \u0026lt;string\u0026gt;*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nSplit the second argument `string` using the delimiter specified in the first argument, and then iterate through the resulting items. For instance:\n\n```nginx\n\n   location /loop {\n     echo_foreach_split ',' $arg_list;\n       echo \"item: $echo_it\";\n     echo_end;\n   }\n```\n\nAccessing /main yields\n\n```bash\n\n   $ curl 'http://localhost/loop?list=cat,dog,mouse'\n   item: cat\n   item: dog\n   item: mouse\n```\n\nAs seen in the previous example, this directive should always be accompanied by an [echo_end](#echo_end) directive.\n\nParallel `echo_foreach_split` loops are allowed, but nested ones are currently forbidden.\n\nThe `delimiter` argument could contain *multiple* arbitrary characters, like\n\n```nginx\n\n   # this outputs \"cat\\ndog\\nmouse\\n\"\n   echo_foreach_split -- '-a-' 'cat-a-dog-a-mouse';\n     echo $echo_it;\n   echo_end;\n```\n\nLogically speaking, this looping structure is just the `foreach` loop combined with a `split` function call in Perl (using the previous example):\n\n```perl\n\n    foreach (split ',', $arg_list) {\n        print \"item $_\\n\";\n    }\n```\n\nPeople will also find it useful in merging multiple `.js` or `.css` resources into a whole. Here's an example:\n\n```nginx\n\n   location /merge {\n       default_type 'text/javascript';\n\n       echo_foreach_split '\u0026' $query_string;\n           echo \"/* JS File $echo_it */\";\n           echo_location_async $echo_it;\n           echo;\n       echo_end;\n   }\n```\n\nThen accessing /merge to merge the `.js` resources specified in the query string:\n\n```bash\n\n   $ curl 'http://localhost/merge?/foo/bar.js\u0026/yui/blah.js\u0026/baz.js'\n```\n\nOne can also use third-party Nginx cache module to cache the merged response generated by the `/merge` location in the previous example.\n\nThis directive was first introduced in the [release v0.17](#v017).\n\n[Back to TOC](#table-of-contents)\n\necho_end\n--------\n**syntax:** *echo_end*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nThis directive is used to terminate the body of looping and conditional control structures like [echo_foreach_split](#echo_foreach_split).\n\nThis directive was first introduced in the [release v0.17](#v017).\n\n[Back to TOC](#table-of-contents)\n\necho_request_body\n-----------------\n**syntax:** *echo_request_body*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nOutputs the contents of the request body previous read.\n\nBehind the scene, it's implemented roughly like this:\n\n```C\n\n   if (r-\u003erequest_body \u0026\u0026 r-\u003erequest_body-\u003ebufs) {\n       return ngx_http_output_filter(r, r-\u003erequest_body-\u003ebufs);\n   }\n```\n\nUnlike the [$echo_request_body](#echo_request_body) and $request_body variables, this directive will show the whole request body even if some parts or all parts of it are saved in temporary files on the disk.\n\nIt is a \"no-op\" if no request body has been read yet.\n\nThis directive was first introduced in the [release v0.18](#v018).\n\nSee also [echo_read_request_body](#echo_read_request_body) and the [chunkin module](http://github.com/agentzh/chunkin-nginx-module).\n\n[Back to TOC](#table-of-contents)\n\necho_exec\n---------\n**syntax:** *echo_exec \u0026lt;location\u0026gt; [\u0026lt;query_string\u0026gt;]*\n\n**syntax:** *echo_exec \u0026lt;named_location\u0026gt;*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nDoes an internal redirect to the location specified. An optional query string can be specified for normal locations, as in\n\n```nginx\n\n   location /foo {\n       echo_exec /bar weight=5;\n   }\n   location /bar {\n       echo $arg_weight;\n   }\n```\n\nOr equivalently\n\n```nginx\n\n   location /foo {\n       echo_exec /bar?weight=5;\n   }\n   location /bar {\n       echo $arg_weight;\n   }\n```\n\nNamed locations are also supported. Here's an example:\n\n```nginx\n\n   location /foo {\n       echo_exec @bar;\n   }\n   location @bar {\n       # you'll get /foo rather than @bar\n       #  due to a potential bug in nginx.\n       echo $echo_request_uri;\n   }\n```\n\nBut query string (if any) will always be ignored for named location redirects due to a limitation in the `ngx_http_named_location` function.\n\nNever try to echo things before the `echo_exec` directive or you won't see the proper response of the location you want to redirect to. Because any echoing will cause the original location handler to send HTTP headers before the redirection happens.\n\nTechnically speaking, this directive exposes the Nginx internal API functions `ngx_http_internal_redirect` and `ngx_http_named_location`.\n\nThis directive was first introduced in the [v0.21 release](#v021).\n\n[Back to TOC](#table-of-contents)\n\necho_status\n-----------\n**syntax:** *echo_status \u0026lt;status-num\u0026gt;*\n\n**default:** *echo_status 200*\n\n**context:** *location, location if*\n\n**phase:** *content*\n\nSpecify the default response status code. Default to `200`. This directive is declarative and the relative order with other echo-like directives is not important.\n\nHere is an example,\n\n```nginx\n\n location = /bad {\n     echo_status 404;\n     echo \"Something is missing...\";\n }\n```\n\nthen we get a response like this:\n\n\n    HTTP/1.1 404 Not Found\n    Server: nginx/1.2.1\n    Date: Sun, 24 Jun 2012 03:58:18 GMT\n    Content-Type: text/plain\n    Transfer-Encoding: chunked\n    Connection: keep-alive\n\n    Something is missing...\n\n\nThis directive was first introduced in the `v0.40` release.\n\n[Back to TOC](#table-of-contents)\n\nFilter Directives\n=================\n\nUse of the following directives trigger the filter registration of this module. By default, no filter will be registered by this module.\n\nEvery filter directive supports variable interpolation in its arguments (if any).\n\n[Back to TOC](#table-of-contents)\n\necho_before_body\n----------------\n**syntax:** *echo_before_body \\[options\\] \\[argument\\]...*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *output filter*\n\nIt's the filter version of the [echo](#echo) directive, and prepends its output to the beginning of the original outputs generated by the underlying content handler.\n\nAn example is\n\n```nginx\n\n location /echo {\n     echo_before_body hello;\n     proxy_pass $scheme://127.0.0.1:$server_port$request_uri/more;\n }\n location /echo/more {\n     echo world\n }\n```\n\nAccessing `/echo` from the client side yields\n\n```bash\n\n   hello\n   world\n```\n\nIn the previous sample, we borrow the [standard proxy module](http://nginx.org/en/docs/http/ngx_http_proxy_module.html) to serve as the underlying content handler that generates the \"main contents\".\n\nMultiple instances of this filter directive are also allowed, as in:\n\n```nginx\n\n location /echo {\n     echo_before_body hello;\n     echo_before_body world;\n     echo !;\n }\n```\n\nOn the client side, the output is like\n\n```bash\n\n   $ curl 'http://localhost/echo'\n   hello\n   world\n   !\n```\n\nIn this example, we also use the [content handler directives](#content-handler-directives) provided by this module as the underlying content handler.\n\nThis directive also supports the `-n` and `--` options like the [echo](#echo) directive.\n\nThis directive can be mixed with its brother directive [echo_after_body](#echo_after_body).\n\n[Back to TOC](#table-of-contents)\n\necho_after_body\n---------------\n**syntax:** *echo_after_body \\[argument\\]...*\n\n**default:** *no*\n\n**context:** *location, location if*\n\n**phase:** *output filter*\n\nIt's very much like the [echo_before_body](#echo_before_body) directive, but *appends* its output to the end of the original outputs generated by the underlying content handler.\n\nHere's a simple example:\n\n```nginx\n\n location /echo {\n     echo_after_body hello;\n     proxy_pass http://127.0.0.1:$server_port$request_uri/more;\n }\n location /echo/more {\n     echo world\n }\n```\n\nAccessing `/echo` from the client side yields\n\n\n      world\n      hello\n\n\nMultiple instances are allowed, as in:\n\n```nginx\n\n location /echo {\n     echo_after_body hello;\n     echo_after_body world;\n     echo i;\n     echo say;\n }\n```\n\nThe output on the client side while accessing the `/echo` location looks like\n\n\n      i\n      say\n      hello\n      world\n\n\nThis directive also supports the `-n` and `--` options like the [echo](#echo) directive.\n\nThis directive can be mixed with its brother directive [echo_before_body](#echo_before_body).\n\n[Back to TOC](#table-of-contents)\n\nVariables\n=========\n\n[Back to TOC](#table-of-contents)\n\n$echo_it\n--------\n\nThis is a \"topic variable\" used by [echo_foreach_split](#echo_foreach_split), just like the `$_` variable in Perl.\n\n[Back to TOC](#table-of-contents)\n\n$echo_timer_elapsed\n-------------------\n\nThis variable holds the seconds elapsed since the start of the current request (might be a subrequest though) or the last invocation of the [echo_reset_timer](#echo_reset_timer) command.\n\nThe timing result takes three digits after the decimal point.\n\nReferences of this variable will force the underlying Nginx timer to update to the current system time, regardless the timer resolution settings elsewhere in the config file, just like the [echo_reset_timer](#echo_reset_timer) directive.\n\n[Back to TOC](#table-of-contents)\n\n$echo_request_body\n------------------\n\nEvaluates to the current (sub)request's request body previously read if no part of the body has been saved to a temporary file. To always show the request body even if it's very large, use the [echo_request_body](#echo_request_body) directive.\n\n[Back to TOC](#table-of-contents)\n\n$echo_request_method\n--------------------\n\nEvaluates to the HTTP request method of the current request (it can be a subrequest).\n\nBehind the scene, it just takes the string data stored in `r-\u003emethod_name`.\n\nCompare it to the [$echo_client_request_method](#echo_client_request_method) variable.\n\nAt least for Nginx 0.8.20 and older, the [$request_method](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_method) variable provided by the [http core module](http://nginx.org/en/docs/http/ngx_http_core_module.html) is actually doing what our [$echo_client_request_method](#echo_client_request_method) is doing.\n\nThis variable was first introduced in our [v0.15 release](#v015).\n\n[Back to TOC](#table-of-contents)\n\n$echo_client_request_method\n---------------------------\n\nAlways evaluates to the main request's HTTP method even if the current request is a subrequest.\n\nBehind the scene, it just takes the string data stored in `r-\u003emain-\u003emethod_name`.\n\nCompare it to the [$echo_request_method](#echo_request_method) variable.\n\nThis variable was first introduced in our [v0.15 release](#v015).\n\n[Back to TOC](#table-of-contents)\n\n$echo_client_request_headers\n----------------------------\n\nEvaluates to the original client request's headers.\n\nJust as the name suggests, it will always take the main request (or the client request) even if it's currently executed in a subrequest.\n\nA simple example is below:\n\n```nginx\n\n   location /echoback {\n      echo \"headers are:\"\n      echo $echo_client_request_headers;\n   }\n```\n\nAccessing `/echoback` yields\n\n```bash\n\n   $ curl 'http://localhost/echoback'\n   headers are\n   GET /echoback HTTP/1.1\n   User-Agent: curl/7.18.2 (i486-pc-linux-gnu) libcurl/7.18.2 OpenSSL/0.9.8g\n   Host: localhost:1984\n   Accept: */*\n```\n\nBehind the scene, it recovers `r-\u003emain-\u003eheader_in` (or the large header buffers, if any) on the C level and does not construct the headers itself by traversing parsed results in the request object.\n\nThis varible is always evaluated to an empty value in HTTP/2 requests for now due to the current implementation.\n\nThis variable was first introduced in [version 0.15](#v015).\n\n[Back to TOC](#table-of-contents)\n\n$echo_cacheable_request_uri\n---------------------------\n\nEvaluates to the parsed form of the URI (usually led by `/`) of the current (sub-)request. Unlike the [$echo_request_uri](#echo_request_uri) variable, it is cacheable.\n\nSee [$echo_request_uri](#echo_request_uri) for more details.\n\nThis variable was first introduced in [version 0.17](#v017).\n\n[Back to TOC](#table-of-contents)\n\n$echo_request_uri\n-----------------\n\nEvaluates to the parsed form of the URI (usually led by `/`) of the current (sub-)request. Unlike the [$echo_cacheable_request_uri](#echo_cacheable_request_uri) variable, it is *not* cacheable.\n\nThis is quite different from the [$request_uri](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_uri) variable exported by the [ngx_http_core_module](http://nginx.org/en/docs/http/ngx_http_core_module.html), because `$request_uri` is the *unparsed* form of the current request's URI.\n\nThis variable was first introduced in [version 0.17](#v017).\n\n[Back to TOC](#table-of-contents)\n\n$echo_incr\n----------\n\nIt is a counter that always generate the current counting number, starting from 1. The counter is always associated with the main request even if it is accessed within a subrequest.\n\nConsider the following example\n\n```Nginx\n\n location /main {\n     echo \"main pre: $echo_incr\";\n     echo_location_async /sub;\n     echo_location_async /sub;\n     echo \"main post: $echo_incr\";\n }\n location /sub {\n     echo \"sub: $echo_incr\";\n }\n```\n\nAccessing `/main` yields\n\n    main pre: 1\n    sub: 3\n    sub: 4\n    main post: 2\n\nThis directive was first introduced in the [v0.18 release](#v018).\n\n[Back to TOC](#table-of-contents)\n\n$echo_response_status\n---------------------\n\nEvaluates to the status code of the current (sub)request, null if not any.\n\nBehind the scene, it's just the textual representation of `r-\u003eheaders_out-\u003estatus`.\n\nThis directive was first introduced in the [v0.23 release](#v023).\n\n[Back to TOC](#table-of-contents)\n\nInstallation\n============\n\nYou're recommended to install this module (as well as the Nginx core and many other goodies) via the [OpenResty bundle](http://openresty.org). See [the detailed instructions](http://openresty.org/#Installation) for downloading and installing OpenResty into your system. This is the easiest and most safe way to set things up.\n\nAlternatively, you can install this module manually with the Nginx source:\n\nGrab the nginx source code from [nginx.org](http://nginx.org/), for example,\nthe version 1.11.2 (see [nginx compatibility](#compatibility)), and then build the source with this module:\n\n```bash\n\n $ wget 'http://nginx.org/download/nginx-1.11.2.tar.gz'\n $ tar -xzvf nginx-1.11.2.tar.gz\n $ cd nginx-1.11.2/\n\n # Here we assume you would install you nginx under /opt/nginx/.\n $ ./configure --prefix=/opt/nginx \\\n     --add-module=/path/to/echo-nginx-module\n\n $ make -j2\n $ make install\n```\n\nDownload the latest version of the release tarball of this module from [echo-nginx-module file list](https://github.com/openresty/echo-nginx-module/tags).\n\nStarting 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\n`./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)\ndirective, for example,\n\n```nginx\nload_module /path/to/modules/ngx_http_echo_module.so;\n```\n\nAlso, this module is included and enabled by default in the [OpenResty bundle](http://openresty.org).\n\n[Back to TOC](#table-of-contents)\n\nCompatibility\n=============\n\nThe following versions of Nginx should work with this module:\n\n* **1.16.x**\n* **1.15.x**                      (last tested: 1.15.8)\n* **1.14.x**\n* **1.13.x**                      (last tested: 1.13.6)\n* **1.12.x**\n* **1.11.x**                      (last tested: 1.11.2)\n* **1.10.x**\n* **1.9.x**                       (last tested: 1.9.15)\n* **1.8.x**\n* **1.7.x**                       (last tested: 1.7.10)\n* **1.6.x**\n* **1.5.x**                       (last tested: 1.5.12)\n* **1.4.x**                       (last tested: 1.4.4)\n* **1.3.x**                       (last tested: 1.3.7)\n* **1.2.x**                       (last tested: 1.2.9)\n* **1.1.x**                       (last tested: 1.1.5)\n* **1.0.x**                       (last tested: 1.0.11)\n* **0.9.x**                       (last tested: 0.9.4)\n* **0.8.x**                       (last tested: 0.8.54)\n* **0.7.x \u003e= 0.7.21**             (last tested: 0.7.68)\n\nIn particular,\n\n* the directive [echo_location_async](#echo_location_async) and its brother [echo_subrequest_async](#echo_subrequest_async) do *not* work with **0.7.x \u003c 0.7.46**.\n* the [echo_after_body](#echo_after_body) directive does *not* work at all with nginx **\u003c 0.8.7**.\n* the [echo_sleep](#echo_sleep) directive cannot be used after [echo_location](#echo_location) or [echo_subrequest](#echo_subrequest) for nginx **\u003c 0.8.11**.\n\nEarlier versions of Nginx like 0.6.x and 0.5.x will *not* work at all.\n\nIf you find that any particular version of Nginx above 0.7.21 does not work with this module, please consider [reporting a bug](#report-bugs).\n\n[Back to TOC](#table-of-contents)\n\nModules that use this module for testing\n========================================\n\nThe following modules take advantage of this `echo` module in their test suite:\n\n* The [memc](http://github.com/openresty/memc-nginx-module) module that supports almost the whole memcached TCP protocol.\n* The [chunkin](http://github.com/agentzh/chunkin-nginx-module) module that adds HTTP 1.1 chunked input support to Nginx.\n* The [headers_more](http://github.com/openresty/headers-more-nginx-module) module that allows you to add, set, and clear input and output headers under the conditions that you specify.\n* The `echo` module itself.\n\nPlease mail me other modules that use `echo` in any form and I'll add them to the list above :)\n\n[Back to TOC](#table-of-contents)\n\nCommunity\n=========\n\n[Back to TOC](#table-of-contents)\n\nEnglish Mailing List\n--------------------\n\nThe [openresty-en](https://groups.google.com/group/openresty-en) mailing list is for English speakers.\n\n[Back to TOC](#table-of-contents)\n\nChinese Mailing List\n--------------------\n\nThe [openresty](https://groups.google.com/group/openresty) mailing list is for Chinese speakers.\n\n[Back to TOC](#table-of-contents)\n\nReport Bugs\n===========\n\nAlthough 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\n\n1. create a ticket on the [issue tracking interface](https://github.com/openresty/echo-nginx-module/issues) provided by GitHub,\n1. or send a bug report, questions, or even patches to the [OpenResty Community](#community).\n\n[Back to TOC](#table-of-contents)\n\nSource Repository\n=================\n\nAvailable on github at [openresty/echo-nginx-module](https://github.com/openresty/echo-nginx-module).\n\n[Back to TOC](#table-of-contents)\n\nChanges\n=======\n\nThe changes of every release of this module can be obtained from the OpenResty bundle's change logs:\n\n\u003chttp://openresty.org/#Changes\u003e\n\n[Back to TOC](#table-of-contents)\n\nTest Suite\n==========\n\nThis module comes with a Perl-driven test suite. The [test cases](https://github.com/openresty/echo-nginx-module/tree/master/t/) are\n[declarative](https://github.com/openresty/echo-nginx-module/blob/master/t/echo.t) too. Thanks to the [Test::Nginx](http://search.cpan.org/perldoc?Test::Nginx) module in the Perl world.\n\nTo run it on your side:\n\n```bash\n\n $ PATH=/path/to/your/nginx-with-echo-module:$PATH prove -r t\n```\n\nYou need to terminate any Nginx processes before running the test suite if you have changed the Nginx server binary.\n\nBecause 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.\n\nSome parts of the test suite requires standard modules [proxy](http://nginx.org/en/docs/http/ngx_http_proxy_module.html), [rewrite](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html) and [SSI](http://nginx.org/en/docs/http/ngx_http_ssi_module.html) to be enabled as well when building Nginx.\n\n[Back to TOC](#table-of-contents)\n\nTODO\n====\n\n* Fix the [echo_after_body](#echo_after_body) directive in subrequests.\n* Add directives *echo_read_client_request_body* and *echo_request_headers*.\n* Add new directive *echo_log* to use Nginx's logging facility directly from the config file and specific loglevel can be specified, as in\n\n```nginx\n\n   echo_log debug \"I am being called.\";\n```\n\n* Add support for options `-h` and `-t` to [echo_subrequest_async](#echo_subrequest_async) and [echo_subrequest](#echo_subrequest). For example\n\n```nginx\n\n   echo_subrequest POST /sub -q 'foo=Foo\u0026bar=Bar' -b 'hello' -t 'text/plan' -h 'X-My-Header: blah blah'\n```\n\n* Add options to control whether a subrequest should inherit cached variables from its parent request (i.e. the current request that is calling the subrequest in question). Currently none of the subrequests issued by this module inherit the cached variables from the parent request.\n* Add new variable *$echo_active_subrequests* to show `r-\u003emain-\u003ecount - 1`.\n* Add the *echo_file* and *echo_cached_file* directives.\n* Add new varaible *$echo_request_headers* to accompany the existing [$echo_client_request_headers](#echo_client_request_headers) variable.\n* Add new directive *echo_foreach*, as in\n\n```nginx\n\n   echo_foreach 'cat' 'dog' 'mouse';\n     echo_location_async \"/animals/$echo_it\";\n   echo_end;\n```\n\n* Add new directive *echo_foreach_range*, as in\n\n```nginx\n\n   echo_foreach_range '[1..100]' '[a-zA-z0-9]';\n     echo_location_async \"/item/$echo_it\";\n   echo_end;\n```\n\n* Add new directive *echo_repeat*, as in\n\n```nginx\n\n   echo_repeat 10 $i {\n       echo \"Page $i\";\n       echo_location \"/path/to/page/$i\";\n   }\n```\n\nThis is just another way of saying\n\n```nginx\n\n   echo_foreach_range $i [1..10];\n       echo \"Page $i\";\n       echo_location \"/path/to/page/$i\";\n   echo_end;\n```\n\nThanks Marcus Clyne for providing this idea.\n\n* Add new variable $echo_random which always returns a random non-negative integer with the lower/upper limit specified by the new directives `echo_random_min` and `echo_random_max`. For example,\n\n```nginx\n\n   echo_random_min  10\n   echo_random_max  200\n   echo \"random number: $echo_random\";\n```\n\nThanks Marcus Clyne for providing this idea.\n\n[Back to TOC](#table-of-contents)\n\nGetting involved\n================\n\nYou'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.\n\n[Back to TOC](#table-of-contents)\n\nAuthor\n======\n\nYichun \"agentzh\" Zhang (章亦春) *\u0026lt;agentzh@gmail.com\u0026gt;*, OpenResty Inc.\n\nThis wiki page is also maintained by the author himself, and everybody is encouraged to improve this page as well.\n\n[Back to TOC](#table-of-contents)\n\nCopyright \u0026 License\n===================\n\nCopyright (c) 2009-2018, Yichun \"agentzh\" Zhang (章亦春) \u003cagentzh@gmail.com\u003e, OpenResty Inc.\n\nThis module is licensed under the terms of the BSD license.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions\nare met:\n\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n* 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.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n\"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\nLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\nA PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\nHOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\nSPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED\nTO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR\nPROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\nLIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING\nNEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n[Back to TOC](#table-of-contents)\n\nSee Also\n========\n\n* The original [blog post](http://agentzh.blogspot.com/2009/10/hacking-on-nginx-echo-module.html) about this module's initial development.\n* The standard [addition filter module](http://nginx.org/en/docs/http/ngx_http_addition_module.html).\n* The standard [proxy module](http://nginx.org/en/docs/http/ngx_http_proxy_module.html).\n* The [OpenResty](http://openresty.org) bundle.\n\n[Back to TOC](#table-of-contents)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fecho-nginx-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenresty%2Fecho-nginx-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fecho-nginx-module/lists"}