Nginx, Inc. NGINX Plus Reference Guide NGINX Plus - release 4, based on 1.7.3 core July 17, 2014 Copyright Notice © 2012-2014 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 http://nginx.com. • For online NGINX documentation visit http://nginx.org/en/docs. • For general inquiries, please use: [email protected] 2 Contents Title1 Preface2 Table of Contents3 1 Core modules5 1.1 Core functionality..........................5 1.2 Setting up hashes.......................... 15 1.3 Connection processing methods.................. 16 2 HTTP server modules 17 2.1 Module ngx http core module................... 17 2.2 Module ngx http access module.................. 53 2.3 Module ngx http addition module................. 55 2.4 Module ngx http auth basic module............... 57 2.5 Module ngx http auth request module.............. 59 2.6 Module ngx http autoindex module................ 61 2.7 Module ngx http browser module................. 62 2.8 Module ngx http charset module................. 64 2.9 Module ngx http dav module................... 67 2.10 Module ngx http empty gif module................ 70 2.11 Module ngx http f4f module.................... 71 2.12 Module ngx http fastcgi module.................. 72 2.13 Module ngx http flv module.................... 88 2.14 Module ngx http geo module................... 89 2.15 Module ngx http geoip module.................. 92 2.16 Module ngx http gunzip module................. 95 2.17 Module ngx http gzip module................... 96 2.18 Module ngx http gzip static module............... 100 2.19 Module ngx http headers module................. 101 2.20 Module ngx http hls module.................... 103 2.21 Module ngx http image filter module............... 107 2.22 Module ngx http index module.................. 110 2.23 Module ngx http limit conn module............... 111 2.24 Module ngx http limit req module................ 114 2.25 Module ngx http log module.................... 117 3 CONTENTS CONTENTS 2.26 Module ngx http map module................... 122 2.27 Module ngx http memcached module............... 125 2.28 Module ngx http mp4 module................... 129 2.29 Module ngx http perl module................... 132 2.30 Module ngx http proxy module.................. 138 2.31 Module ngx http random index module............. 161 2.32 Module ngx http realip module.................. 162 2.33 Module ngx http referer module.................. 164 2.34 Module ngx http rewrite module................. 166 2.35 Module ngx http scgi module................... 172 2.36 Module ngx http secure link module............... 185 2.37 Module ngx http session log module............... 188 2.38 Module ngx http spdy module................... 190 2.39 Module ngx http split clients module............... 192 2.40 Module ngx http ssi module.................... 193 2.41 Module ngx http ssl module.................... 198 2.42 Module ngx http status module.................. 208 2.43 Module ngx http sub module................... 213 2.44 Module ngx http upstream module................ 215 2.45 Module ngx http userid module.................. 231 2.46 Module ngx http uwsgi module.................. 234 2.47 Module ngx http xslt module................... 250 3 Mail server modules 253 3.1 Module ngx mail core module................... 253 3.2 Module ngx mail auth http module................ 258 3.3 Module ngx mail proxy module.................. 261 3.4 Module ngx mail ssl module.................... 263 3.5 Module ngx mail imap module.................. 267 3.6 Module ngx mail pop3 module.................. 268 3.7 Module ngx mail smtp module.................. 269 A Changelog for NGINX Plus 270 B High Availability support 272 C Legal Notices 273 Index 277 Nginx, Inc. p.4 of 282 Chapter 1 Core modules 1.1 Core functionality 1.1.1 Example Configuration...................6 1.1.2 Directives..........................6 accept mutex........................6 accept mutex delay.....................6 daemon...........................6 debug connection......................7 debug points........................7 error log...........................7 env..............................8 events............................9 include............................9 lock file...........................9 master process....................... 10 multi accept......................... 10 pcre jit........................... 10 pid.............................. 11 ssl engine.......................... 11 timer resolution....................... 11 use.............................. 11 user............................. 12 worker aio requests..................... 12 worker connections..................... 12 worker cpu affinity..................... 12 worker priority....................... 13 worker processes...................... 13 worker rlimit core...................... 13 worker rlimit nofile..................... 14 worker rlimit sigpending.................. 14 working directory...................... 14 5 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. The use of rtsig connection processing method requires accept_mutex to be enabled. 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. Nginx, Inc. p.6 of 282 CHAPTER 1. CORE MODULES 1.1. CORE FUNCTIONALITY debug connection Syntax: debug_connection address j CIDR j unix:; Default | Context: events 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] [debug j info j notice j warn j error j crit j alert j emerg]; Default logs/error.log error Context: main, http, server, location Configures logging. Several logs can be specified on the same level (1.5.2). The first parameter defines a file that will store the log. The special value stderr selects the standard error file. Logging to syslog can be configured by specifying the \syslog:" prefix. The second parameter determines the level of logging. Log levels above are listed in the order of increasing severity. Setting a certain log level will cause all messages of the specified and more severe log levels to be logged. For Nginx, Inc. p.7 of 282 CHAPTER 1. CORE MODULES 1.1. CORE FUNCTIONALITY example, the default level error will cause error, crit, alert, and emerg messages to be logged. If this parameter is omitted then error is used. For debug logging to work, nginx needs