{"id":13486129,"url":"https://github.com/openresty/headers-more-nginx-module","last_synced_at":"2025-04-11T16:39:26.481Z","repository":{"id":726417,"uuid":"374483","full_name":"openresty/headers-more-nginx-module","owner":"openresty","description":"Set, add, and clear arbitrary output headers in NGINX http servers","archived":false,"fork":false,"pushed_at":"2024-08-17T13:18:35.000Z","size":533,"stargazers_count":1657,"open_issues_count":48,"forks_count":222,"subscribers_count":79,"default_branch":"master","last_synced_at":"2024-10-29T17:54:21.647Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"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":null,"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-11-16T08:26:27.000Z","updated_at":"2024-10-28T10:03:22.000Z","dependencies_parsed_at":"2024-06-18T15:33:37.182Z","dependency_job_id":"e40fd213-30c5-454c-a96c-92b95aa66059","html_url":"https://github.com/openresty/headers-more-nginx-module","commit_stats":{"total_commits":268,"total_committers":16,"mean_commits":16.75,"dds":"0.13059701492537312","last_synced_commit":"06dc0be56e5ec9f7fd814e881b066b5540a85bec"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fheaders-more-nginx-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fheaders-more-nginx-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fheaders-more-nginx-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fheaders-more-nginx-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openresty","download_url":"https://codeload.github.com/openresty/headers-more-nginx-module/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248441905,"owners_count":21104099,"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-07-31T18:00:40.124Z","updated_at":"2025-04-11T16:39:26.459Z","avatar_url":"https://github.com/openresty.png","language":"C","funding_links":[],"categories":["C","Modules","Third Modules","Third Party Modules"],"sub_categories":["C Modules"],"readme":"Name\n====\n\n**ngx_headers_more** - Set and clear input and output headers...more than \"add\"!\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* [Version](#version)\n* [Synopsis](#synopsis)\n* [Description](#description)\n* [Directives](#directives)\n    * [more_set_headers](#more_set_headers)\n    * [more_clear_headers](#more_clear_headers)\n    * [more_set_input_headers](#more_set_input_headers)\n    * [more_clear_input_headers](#more_clear_input_headers)\n* [Limitations](#limitations)\n* [Installation](#installation)\n* [Compatibility](#compatibility)\n* [Community](#community)\n    * [English Mailing List](#english-mailing-list)\n    * [Chinese Mailing List](#chinese-mailing-list)\n* [Bugs and Patches](#bugs-and-patches)\n* [Source Repository](#source-repository)\n* [Changes](#changes)\n* [Test Suite](#test-suite)\n* [TODO](#todo)\n* [Getting involved](#getting-involved)\n* [Authors](#authors)\n* [Copyright \u0026 License](#copyright--license)\n* [See Also](#see-also)\n\nVersion\n=======\n\nThis document describes headers-more-nginx-module [v0.34](https://github.com/openresty/headers-more-nginx-module/tags) released on 17 July 2022.\n\nSynopsis\n========\n\n```nginx\n\n # set the Server output header\n more_set_headers 'Server: my-server';\n\n # set and clear output headers\n location /bar {\n     more_set_headers 'X-MyHeader: blah' 'X-MyHeader2: foo';\n     more_set_headers -t 'text/plain text/css' 'Content-Type: text/foo';\n     more_set_headers -s '400 404 500 503' -s 413 'Foo: Bar';\n     more_clear_headers 'Content-Type';\n\n     # your proxy_pass/memcached_pass/or any other config goes here...\n }\n\n # set output headers\n location /type {\n     more_set_headers 'Content-Type: text/plain';\n     # ...\n }\n\n # set input headers\n location /foo {\n     set $my_host 'my dog';\n     more_set_input_headers 'Host: $my_host';\n     more_set_input_headers -t 'text/plain' 'X-Foo: bah';\n\n     # now $host and $http_host have their new values...\n     # ...\n }\n\n # replace input header X-Foo *only* if it already exists\n more_set_input_headers -r 'X-Foo: howdy';\n```\n\nDescription\n===========\n\nThis module allows you to add, set, or clear any output\nor input header that you specify.\n\nThis is an enhanced version of the standard\n[headers](http://nginx.org/en/docs/http/ngx_http_headers_module.html) module because it provides more utilities like\nresetting or clearing \"builtin headers\" like `Content-Type`,\n`Content-Length`, and `Server`.\n\nIt also allows you to specify an optional HTTP status code\ncriteria using the `-s` option and an optional content\ntype criteria using the `-t` option while modifying the\noutput headers with the [more_set_headers](#more_set_headers) and\n[more_clear_headers](#more_clear_headers) directives. For example,\n\n```nginx\n more_set_headers -s 404 -t 'text/html' 'X-Foo: Bar';\n```\n\nYou can also specify multiple MIME types to filter out in a single `-t` option.\nFor example,\n\n```nginx\nmore_set_headers -t 'text/html text/plain' 'X-Foo: Bar';\n```\n\nNever use other parameters like `charset=utf-8` in the `-t` option values; they will not\nwork as you would expect.\n\nInput headers can be modified as well. For example\n\n```nginx\n location /foo {\n     more_set_input_headers 'Host: foo' 'User-Agent: faked';\n     # now $host, $http_host, $user_agent, and\n     #   $http_user_agent all have their new values.\n }\n```\n\nThe option `-t` is also available in the\n[more_set_input_headers](#more_set_input_headers) and\n[more_clear_input_headers](#more_clear_input_headers) directives (for request header filtering) while the `-s` option\nis not allowed.\n\nUnlike the standard [headers](http://nginx.org/en/docs/http/ngx_http_headers_module.html) module, this module's directives will by\ndefault apply to all the status codes, including `4xx` and `5xx`.\n\n[Back to TOC](#table-of-contents)\n\nDirectives\n==========\n\n[Back to TOC](#table-of-contents)\n\nmore_set_headers\n----------------\n**syntax:** *more_set_headers [-t \u0026lt;content-type list\u0026gt;]... [-s \u0026lt;status-code list\u0026gt;]... [-a] \u0026lt;new-header\u0026gt;...*\n\n**default:** *no*\n\n**context:** *http, server, location, location if*\n\n**phase:** *output-header-filter*\n\nReplaces (if any) or adds (if not any) the specified output headers when the response status code matches the codes specified by the `-s` option *AND* the response content type matches the types specified by the `-t` option.\n\nIf the \"-a\" option is specified, the specified output headers can be appended directly without clearing the old fields. The behavior of builtin headers such as \"Content-Type\", \"Content-Length\", \"Server\", etc. cannot be changed.\n\nIf either `-s` or `-t` is not specified or has an empty list value, then no match is required. Therefore, the following directive set the `Server` output header to the custom value for *any* status code and *any* content type:\n\n```nginx\n\n   more_set_headers    \"Server: my_server\";\n```\n\nExisting response headers with the same name are always overridden. If you want to add headers incrementally, use the standard [add_header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header) directive instead.\n\nA single directive can set/add multiple output headers. For example\n\n```nginx\n\n   more_set_headers 'Foo: bar' 'Baz: bah';\n```\n\nMultiple occurrences of the options are allowed in a single directive. Their values will be merged together. For instance\n\n```nginx\n\n   more_set_headers -s 404 -s '500 503' 'Foo: bar';\n```\n\nis equivalent to\n\n```nginx\n\n   more_set_headers -s '404 500 503' 'Foo: bar';\n```\n\nThe new header should be the one of the forms:\n\n1. `Name: Value`\n1. `Name: `\n1. `Name`\n\nThe last two effectively clear the value of the header `Name`.\n\nNginx variables are allowed in header values. For example:\n\n```nginx\n\n    set $my_var \"dog\";\n    more_set_headers \"Server: $my_var\";\n```\n\nBut variables won't work in header keys due to performance considerations.\n\nMultiple set/clear header directives are allowed in a single location, and they're executed sequentially.\n\nDirectives inherited from an upper level scope (say, http block or server blocks) are executed before the directives in the location block.\n\nNote that although `more_set_headers` is allowed in *location* if blocks, it is *not* allowed in the *server* if blocks, as in\n\n```nginx\n\n   ?  # This is NOT allowed!\n   ?  server {\n   ?      if ($args ~ 'download') {\n   ?          more_set_headers 'Foo: Bar';\n   ?      }\n   ?      ...\n   ?  }\n```\n\nBehind the scene, use of this directive and its friend [more_clear_headers](#more_clear_headers) will (lazily) register an ouput header filter that modifies `r-\u003eheaders_out` the way you specify.\n\n[Back to TOC](#table-of-contents)\n\nmore_clear_headers\n------------------\n**syntax:** *more_clear_headers [-t \u0026lt;content-type list\u0026gt;]... [-s \u0026lt;status-code list\u0026gt;]... \u0026lt;new-header\u0026gt;...*\n\n**default:** *no*\n\n**context:** *http, server, location, location if*\n\n**phase:** *output-header-filter*\n\nClears the specified output headers.\n\nIn fact,\n\n```nginx\n\n    more_clear_headers -s 404 -t 'text/plain' Foo Baz;\n```\n\nis exactly equivalent to\n\n```nginx\n\n    more_set_headers -s 404 -t 'text/plain' \"Foo: \" \"Baz: \";\n```\n\nor\n\n```nginx\n\n    more_set_headers -s 404 -t 'text/plain' Foo Baz\n```\n\nSee [more_set_headers](#more_set_headers) for more details.\n\nThe wildcard character, `*`, can also be used at the end of the header name to specify a pattern. For example, the following directive\neffectively clears *any* output headers starting by \"`X-Hidden-`\":\n\n```nginx\n\n more_clear_headers 'X-Hidden-*';\n```\n\nThe `*` wildcard support was first introduced in [v0.09](#v009).\n\n[Back to TOC](#table-of-contents)\n\nmore_set_input_headers\n----------------------\n**syntax:** *more_set_input_headers [-r] [-t \u0026lt;content-type list\u0026gt;]... \u0026lt;new-header\u0026gt;...*\n\n**default:** *no*\n\n**context:** *http, server, location, location if*\n\n**phase:** *rewrite tail*\n\nVery much like [more_set_headers](#more_set_headers) except that it operates on input headers (or request headers) and it only supports the `-t` option.\n\nNote that using the `-t` option in this directive means filtering by the `Content-Type` *request* header, rather than the response header.\n\nBehind the scene, use of this directive and its friend [more_clear_input_headers](#more_clear_input_headers) will (lazily)\nregister a `rewrite phase` handler that modifies `r-\u003eheaders_in` the way you specify. Note that it always run at the *end* of\nthe `rewrite` phase so that it runs *after* the standard [rewrite module](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html)\nand works in subrequests as well.\n\nIf the `-r` option is specified, then the headers will be replaced to the new values *only if* they already exist.\n\n[Back to TOC](#table-of-contents)\n\nmore_clear_input_headers\n------------------------\n**syntax:** *more_clear_input_headers [-t \u0026lt;content-type list\u0026gt;]... \u0026lt;new-header\u0026gt;...*\n\n**default:** *no*\n\n**context:** *http, server, location, location if*\n\n**phase:** *rewrite tail*\n\nClears the specified input headers.\n\nIn fact,\n\n```nginx\n\n    more_clear_input_headers -t 'text/plain' Foo Baz;\n```\n\nis exactly equivalent to\n\n```nginx\n\n    more_set_input_headers -t 'text/plain' \"Foo: \" \"Baz: \";\n```\n\nor\n\n```nginx\n\n    more_set_input_headers -t 'text/plain' Foo Baz\n```\n\nTo remove request headers \"Foo\" and \"Baz\" for all incoming requests regardless of the content type, we can write\n\n```nginx\n\n    more_clear_input_headers \"Foo\" \"Baz\";\n```\n\nSee [more_set_input_headers](#more_set_input_headers) for more details.\n\nThe wildcard character, `*`, can also be used at the end of the header name to specify a pattern. For example, the following directive\neffectively clears *any* input headers starting by \"`X-Hidden-`\":\n\n```nginx\n\n     more_clear_input_headers 'X-Hidden-*';\n```\n\n[Back to TOC](#table-of-contents)\n\nLimitations\n===========\n\n* Unlike the standard [headers](http://nginx.org/en/docs/http/ngx_http_headers_module.html) module, this module does not automatically take care of the constraint among the `Expires`, `Cache-Control`, and `Last-Modified` headers. You have to get them right yourself or use the [headers](http://nginx.org/en/docs/http/ngx_http_headers_module.html) module together with this module.\n* You cannot remove the `Connection` response header using this module because the `Connection` response header is generated by the standard `ngx_http_header_filter_module` in the Nginx core, whose output header filter runs always *after* the filter of this module. The only way to actually remove the `Connection` header is to patch the Nginx core, that is, editing the C function `ngx_http_header_filter` in the `src/http/ngx_http_header_filter_module.c` file.\n\n[Back to TOC](#table-of-contents)\n\nInstallation\n============\n\nGrab the nginx source code from [nginx.org](http://nginx.org/), for example,\nthe version 1.17.8 (see [nginx compatibility](#compatibility)), and then build the source with this module:\n\n```bash\n\n wget 'http://nginx.org/download/nginx-1.17.8.tar.gz'\n tar -xzvf nginx-1.17.8.tar.gz\n cd nginx-1.17.8/\n\n # Here we assume you would install you nginx under /opt/nginx/.\n ./configure --prefix=/opt/nginx \\\n     --add-module=/path/to/headers-more-nginx-module\n\n make\n make install\n```\n\nDownload the latest version of the release tarball of this module from [headers-more-nginx-module file list](https://github.com/openresty/headers-more-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_headers_more_filter_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.21.x**                      (last tested: 1.21.4)\n* **1.19.x**                      (last tested: 1.19.9)\n* **1.17.x**                      (last tested: 1.17.8)\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**                       (last tested: 1.6.2)\n* **1.5.x**                       (last tested: 1.5.8)\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.44**             (last tested: 0.7.68)\n\nEarlier versions of Nginx like 0.6.x and 0.5.x will *not* work.\n\nIf you find that any particular version of Nginx above 0.7.44 does not work with this module, please consider [reporting a bug](#report-bugs).\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\nBugs and Patches\n================\n\nPlease submit bug reports, wishlists, or patches by\n\n1. creating a ticket on the [GitHub Issue Tracker](https://github.com/chaoslawful/lua-nginx-module/issues),\n1. or posting to the [OpenResty community](#community).\n\n[Back to TOC](#table-of-contents)\n\nSource Repository\n=================\n\nAvailable on github at [openresty/headers-more-nginx-module](https://github.com/openresty/headers-more-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/headers-more-nginx-module/tree/master/t/) are\n[declarative](https://github.com/openresty/headers-more-nginx-module/blob/master/t/sanity.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-headers-more-module:$PATH prove -r t\n```\n\nTo run the test suite with valgrind's memcheck, use the following commands:\n\n```bash\n\n $ export PATH=/path/to/your/nginx-with-headers-more-module:$PATH\n $ TEST_NGINX_USE_VALGRIND=1 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 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 [echo](https://github.com/openresty/echo-nginx-module) to be enabled as well when building Nginx.\n\n[Back to TOC](#table-of-contents)\n\nTODO\n====\n\n* Support variables in new headers' keys.\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\nAuthors\n=======\n\n* Yichun \"agentzh\" Zhang (章亦春) *\u0026lt;agentzh@gmail.com\u0026gt;*, OpenResty Inc.\n* Bernd Dorn ( \u003chttp://www.lovelysystems.com/\u003e )\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\nThe code base is borrowed directly from the standard [headers](http://nginx.org/en/docs/http/ngx_http_headers_module.html) module in Nginx 0.8.24. This part of code is copyrighted by Igor Sysoev.\n\nCopyright (c) 2009-2017, Yichun \"agentzh\" Zhang (章亦春) \u003cagentzh@gmail.com\u003e, OpenResty Inc.\n\nCopyright (c) 2010-2013, Bernd Dorn.\n\nThe license text is available in the [LICENSE](LICENSE) file located in the root directory of the project.\n\n[Back to TOC](#table-of-contents)\n\nSee Also\n========\n\n* The original thread on the Nginx mailing list that inspires this module's development: [\"A question about add_header replication\"](http://forum.nginx.org/read.php?2,11206,11738).\n* The orginal announcement thread on the Nginx mailing list: [\"The \"headers_more\" module: Set and clear output headers...more than 'add'!\"](http://forum.nginx.org/read.php?2,23460).\n* The original [blog post](http://agentzh.blogspot.com/2009/11/headers-more-module-scripting-input-and.html) about this module's initial development.\n* The [echo module](https://github.com/openresty/echo-nginx-module) for Nginx module's automated testing.\n* The standard [headers](http://nginx.org/en/docs/http/ngx_http_headers_module.html) module.\n\n[Back to TOC](#table-of-contents)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fheaders-more-nginx-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenresty%2Fheaders-more-nginx-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fheaders-more-nginx-module/lists"}