Nginx, Inc. NGINX Plus Reference Guide NGINX Plus - release 11, based on 1.11.5 core October 19, 2016 Copyright Notice © 2012-2016 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.......................... 16 1.3 Connection processing methods.................. 17 1.4 Logging to syslog.......................... 18 2 HTTP server modules 19 2.1 Module ngx http core module................... 19 2.2 Module ngx http access module.................. 56 2.3 Module ngx http addition module................. 58 2.4 Module ngx http auth basic module............... 60 2.5 Module ngx http auth jwt module................ 62 2.6 Module ngx http auth request module.............. 64 2.7 Module ngx http autoindex module................ 66 2.8 Module ngx http browser module................. 68 2.9 Module ngx http charset module................. 70 2.10 Module ngx http dav module................... 73 2.11 Module ngx http empty gif module................ 76 2.12 Module ngx http f4f module.................... 77 2.13 Module ngx http fastcgi module.................. 78 2.14 Module ngx http flv module.................... 97 2.15 Module ngx http geo module................... 98 2.16 Module ngx http geoip module.................. 101 2.17 Module ngx http gunzip module................. 104 2.18 Module ngx http gzip module................... 105 2.19 Module ngx http gzip static module............... 109 2.20 Module ngx http headers module................. 110 2.21 Module ngx http hls module.................... 112 2.22 Module ngx http image filter module............... 116 2.23 Module ngx http index module.................. 119 2.24 Module ngx http limit conn module............... 120 3 CONTENTS CONTENTS 2.25 Module ngx http limit req module................ 123 2.26 Module ngx http log module.................... 126 2.27 Module ngx http map module................... 130 2.28 Module ngx http memcached module............... 133 2.29 Module ngx http mp4 module................... 138 2.30 Module ngx http perl module................... 141 2.31 Module ngx http proxy module.................. 147 2.32 Module ngx http random index module............. 174 2.33 Module ngx http realip module.................. 175 2.34 Module ngx http referer module.................. 177 2.35 Module ngx http rewrite module................. 179 2.36 Module ngx http scgi module................... 185 2.37 Module ngx http secure link module............... 202 2.38 Module ngx http session log module............... 205 2.39 Module ngx http slice module................... 207 2.40 Module ngx http split clients module............... 209 2.41 Module ngx http ssi module.................... 210 2.42 Module ngx http ssl module.................... 215 2.43 Module ngx http status module.................. 225 2.44 Module ngx http stub status module............... 234 2.45 Module ngx http sub module................... 236 2.46 Module ngx http upstream module................ 238 2.47 Module ngx http upstream conf module............. 254 2.48 Module ngx http userid module.................. 258 2.49 Module ngx http uwsgi module.................. 261 2.50 Module ngx http v2 module.................... 281 2.51 Module ngx http xslt module................... 284 3 Stream server modules 287 3.1 Module ngx stream core module................. 287 3.2 Module ngx stream access module................ 295 3.3 Module ngx stream geo module.................. 296 3.4 Module ngx stream geoip module................. 298 3.5 Module ngx stream limit conn module.............. 301 3.6 Module ngx stream log module.................. 303 3.7 Module ngx stream map module................. 306 3.8 Module ngx stream proxy module................. 309 3.9 Module ngx stream realip module................. 316 3.10 Module ngx stream return module................ 317 3.11 Module ngx stream split clients module............. 318 3.12 Module ngx stream ssl module.................. 319 3.13 Module ngx stream ssl preread module.............. 325 3.14 Module ngx stream upstream module............... 327 Nginx, Inc. p.4 of 379 CONTENTS CONTENTS 4 Mail server modules 336 4.1 Module ngx mail core module................... 336 4.2 Module ngx mail auth http module................ 341 4.3 Module ngx mail proxy module.................. 345 4.4 Module ngx mail ssl module.................... 347 4.5 Module ngx mail imap module.................. 355 4.6 Module ngx mail pop3 module.................. 356 4.7 Module ngx mail smtp module.................. 357 5 Miscellaneous 358 5.1 High Availability support for NGINX Plus............ 358 5.2 Command-line parameters..................... 364 A Changelog for NGINX Plus 365 B Legal Notices 370 Index 373 Nginx, Inc. p.5 of 379 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......................8 debug points........................8 error log...........................8 env..............................9 events............................ 10 include............................ 10 load module......................... 10 lock file........................... 10 master process....................... 11 multi accept......................... 11 pcre jit........................... 11 pid.............................. 11 ssl engine.......................... 11 thread pool......................... 12 timer resolution....................... 12 use.............................. 12 user............................. 13 worker aio requests..................... 13 worker connections..................... 13 worker cpu affinity..................... 13 worker priority....................... 14 worker processes...................... 14 worker rlimit core...................... 15 worker rlimit nofile..................... 15 working directory...................... 15 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 off 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. There is no need to enable accept_mutex on systems that support the EPOLLEXCLUSIVE flag (1.11.3) or when using reuseport. Prior to version 1.11.3, the default value was on. 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.7 of 379 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