NGINX Modules Reference
Total Page:16
File Type:pdf, Size:1020Kb
Nginx, Inc. NGINX Plus Reference Guide NGINX Plus - release 8, based on 1.9.9 core December 24, 2015 Copyright Notice © 2012-2015 Nginx, Inc. All rights reserved. NGINX, NGINX Plus and any Nginx, Inc. product or service name or logo used herein are trademarks of Nginx, Inc. All other trademarks used herein belong to their respective owners. The trademarks and logos displayed herein may not be used without the prior written consent of Nginx, Inc. or their respective owners. This documentation is provided \AS IS" and is subject to change without notice and should not be interpreted as a commitment by Nginx, Inc. This documentation may not be copied, modified or distributed without authorization of Nginx, Inc. and may be used only in connection with Nginx, Inc. products and services. Nginx, Inc. assumes no responsibility or liability for any errors or inaccuracies that may appear in this documentation. 1 Preface About NGINX NGINX® (\engine x") is a high performance, high concurrency web server excelling at large scale content delivery, web acceleration and protecting application containers. Its precise integration with modern operating systems allows unprecedented levels of efficiency even when running on commodity hardware. Nginx, Inc. develops and maintains NGINX open source distribution, and offers commercial support and professional services for NGINX. About NGINX Plus • Offers additional features on top of the free open source NGINX version. • Prepared, tested and supported by NGINX core engineering team led by the original author Igor Sysoev. For more information • Find more details about NGINX products and support at https://www.nginx.com/. • For online NGINX documentation visit http://nginx.org/en/docs. • NGINX and NGINX Plus Tutorial and Admin Guide is available here: https://www.nginx.com/resources/admin-guide/. • For general inquiries, please use: [email protected] 2 Contents Title1 Preface2 Table of Contents3 1 Core modules6 1.1 Core functionality..........................6 1.2 Setting up hashes.......................... 15 1.3 Connection processing methods.................. 16 1.4 Logging to syslog.......................... 17 2 HTTP server modules 18 2.1 Module ngx http core module................... 18 2.2 Module ngx http access module.................. 54 2.3 Module ngx http addition module................. 56 2.4 Module ngx http auth basic module............... 58 2.5 Module ngx http auth request module.............. 60 2.6 Module ngx http autoindex module................ 62 2.7 Module ngx http browser module................. 64 2.8 Module ngx http charset module................. 66 2.9 Module ngx http dav module................... 69 2.10 Module ngx http empty gif module................ 72 2.11 Module ngx http f4f module.................... 73 2.12 Module ngx http fastcgi module.................. 74 2.13 Module ngx http flv module.................... 93 2.14 Module ngx http geo module................... 94 2.15 Module ngx http geoip module.................. 97 2.16 Module ngx http gunzip module................. 100 2.17 Module ngx http gzip module................... 101 2.18 Module ngx http gzip static module............... 105 2.19 Module ngx http headers module................. 106 2.20 Module ngx http hls module.................... 108 2.21 Module ngx http image filter module............... 112 2.22 Module ngx http index module.................. 115 2.23 Module ngx http limit conn module............... 116 2.24 Module ngx http limit req module................ 119 3 CONTENTS CONTENTS 2.25 Module ngx http log module.................... 122 2.26 Module ngx http map module................... 126 2.27 Module ngx http memcached module............... 129 2.28 Module ngx http mp4 module................... 133 2.29 Module ngx http perl module................... 136 2.30 Module ngx http proxy module.................. 142 2.31 Module ngx http random index module............. 168 2.32 Module ngx http realip module.................. 169 2.33 Module ngx http referer module.................. 171 2.34 Module ngx http rewrite module................. 173 2.35 Module ngx http scgi module................... 179 2.36 Module ngx http secure link module............... 195 2.37 Module ngx http session log module............... 198 2.38 Module ngx http slice module................... 200 2.39 Module ngx http split clients module............... 202 2.40 Module ngx http ssi module.................... 203 2.41 Module ngx http ssl module.................... 208 2.42 Module ngx http status module.................. 218 2.43 Module ngx http stub status module............... 227 2.44 Module ngx http sub module................... 229 2.45 Module ngx http upstream module................ 231 2.46 Module ngx http upstream conf module............. 246 2.47 Module ngx http userid module.................. 250 2.48 Module ngx http uwsgi module.................. 253 2.49 Module ngx http v2 module.................... 273 2.50 Module ngx http xslt module................... 276 3 Stream proxy modules 279 3.1 Module ngx stream core module................. 279 3.2 Module ngx stream access module................ 284 3.3 Module ngx stream limit conn module.............. 285 3.4 Module ngx stream proxy module................. 287 3.5 Module ngx stream ssl module.................. 294 3.6 Module ngx stream upstream module............... 299 4 Mail server modules 306 4.1 Module ngx mail core module................... 306 4.2 Module ngx mail auth http module................ 311 4.3 Module ngx mail proxy module.................. 315 4.4 Module ngx mail ssl module.................... 317 4.5 Module ngx mail imap module.................. 324 4.6 Module ngx mail pop3 module.................. 325 4.7 Module ngx mail smtp module.................. 326 5 Miscellaneous 327 5.1 High Availability support for NGINX Plus............ 327 5.2 Command-line parameters..................... 333 Nginx, Inc. p.4 of 351 CONTENTS CONTENTS A Changelog for NGINX Plus 334 B Legal Notices 338 Index 345 Nginx, Inc. p.5 of 351 Chapter 1 Core modules 1.1 Core functionality 1.1.1 Example Configuration...................7 1.1.2 Directives..........................7 accept mutex........................7 accept mutex delay.....................7 daemon...........................7 debug connection......................7 debug points........................8 error log...........................8 env..............................9 events............................ 10 include............................ 10 lock file........................... 10 master process....................... 10 multi accept......................... 10 pcre jit........................... 11 pid.............................. 11 ssl engine.......................... 11 thread pool......................... 11 timer resolution....................... 12 use.............................. 12 user............................. 12 worker aio requests..................... 12 worker connections..................... 13 worker cpu affinity..................... 13 worker priority....................... 13 worker processes...................... 14 worker rlimit core...................... 14 worker rlimit nofile..................... 14 working directory...................... 14 6 CHAPTER 1. CORE MODULES 1.1. CORE FUNCTIONALITY 1.1.1 Example Configuration user www www; worker_processes 2; error_log /var/log/nginx-error.log info; events { use kqueue; worker_connections 2048; } ... 1.1.2 Directives accept mutex Syntax: accept_mutex on j off; Default on Context: events If accept_mutex is enabled, worker processes will accept new connections by turn. Otherwise, all worker processes will be notified about new connections, and if volume of new connections is low, some of the worker processes may just waste system resources. accept mutex delay Syntax: accept_mutex_delay time; Default 500ms Context: events If accept mutex is enabled, specifies the maximum time during which a worker process will try to restart accepting new connections if another worker process is currently accepting new connections. daemon Syntax: daemon on j off; Default on Context: main Determines whether nginx should become a daemon. Mainly used during development. debug connection Syntax: debug_connection address j CIDR j unix:; Default | Context: events Nginx, Inc. p.7 of 351 CHAPTER 1. CORE MODULES 1.1. CORE FUNCTIONALITY Enables debugging log for selected client connections. Other connections will use logging level set by the error log directive. Debugged connections are specified by IPv4 or IPv6 (1.3.0, 1.2.1) address or network. A connection may also be specified using a hostname. For connections using UNIX-domain sockets (1.3.0, 1.2.1), debugging log is enabled by the \unix:" parameter. events { debug_connection 127.0.0.1; debug_connection localhost; debug_connection 192.0.2.0/24; debug_connection ::1; debug_connection 2001:0db8::/32; debug_connection unix:; ... } For this directive to work, nginx needs to be built with --with-debug, see \A debugging log". debug points Syntax: debug_points abort j stop; Default | Context: main This directive is used for debugging. When internal error is detected, e.g. the leak of sockets on restart of working processes, enabling debug_points leads to a core file creation (abort) or to stopping of a process (stop) for further analysis using a system debugger. error log Syntax: error_log file j stderr j syslog:server=address[,parameter=value] j memory:size [debug j info j notice j warn j error j crit j alert j emerg]; Default logs/error.log error