nginx Tutorial

By Xah Lee. Date:

This is a basic tutorial of the nginx web Server. NGINX is a modern HTTP server, faster than good old Apache, and uses less memory.

Install, Start, Run, Stop

here's the most basic intro.

here's the basics of what nginx is:

Install and Versions

On Ubuntu Linux, do one of:

to read the man page, do man nginx, or nginx -h.

◆ nginx -h

nginx version: nginx/1.1.19
Usage: nginx [-?hvVtq] [-s signal] [-c filename] [-p prefix] [-g directives]

Options:
  -?,-h         : this help
  -v            : show version and exit
  -V            : show version and configure options then exit
  -t            : test configuration and exit
  -q            : suppress non-error messages during configuration testing
  -s signal     : send signal to a master process: stop, quit, reopen, reload
  -p prefix     : set prefix path (default: /etc/nginx/)
  -c filename   : set configuration file (default: /etc/nginx/nginx.conf)
  -g directives : set global directives out of configuration file

The above is very short and simple, and that's all there is to it. Unlike apache or mysql, there is no other binaries, no other helper scripts, etc. The complexity of controlling nginx behavior is in the config syntax/semantics for modules.

to see your version, type nginx -v. As of today , the latest on Ubuntu is “1.1.19”, and current version is “1.2.0”.

by default, it's installed at /usr/sbin/nginx. Type which nginx to find out.

starting and stopping

to start, sudo nginx. In general, you should be root.

here's the common options:

nginx processes

there is one “master process”, and a number of “worker process”. You specify the number of worker processes in the config file.

here's a sample output of nginx processes.

◆ ps -ef | grep nginx

root      2940     1  0 Mar20 ?        00:00:00 nginx: master process nginx
www-data  2941  2940  0 Mar20 ?        00:00:01 nginx: worker process
www-data  2942  2940  0 Mar20 ?        00:00:03 nginx: worker process
www-data  2943  2940  0 Mar20 ?        00:00:02 nginx: worker process
www-data  2944  2940  0 Mar20 ?        00:00:03 nginx: worker process

nginx master process responds meaningfully to some unix signals. You can send signal by nginx -s command, or the normal unix way by kill -s signal_name pid

modules

nginx is modular. The most basic functionality of nginx is done by the following modules:

these modules are sometimes called “core modules” or “base modules”.

Note: the terms {“base module”, “core module”, “core”} is confusing, because there are renaming between versions and the terms used sloppily. But, just remember, by default, there are 2 or 3 modules that are built-in, without them there is no server. These may be called “core modules” or “base module”, and in this set, one of the module has a name of “Main” or “Core”. Then, by default, there are 10 or so other modules that are typically always included, for example: {FastCGI, Auth Basic, Charset, Gzip, Log, Proxy, …}. Then, there are other optional modules that usually are not bundled in a default binary. Then, there are 3rd party modules.

Module must be compiled-in. (cannot be loaded at run-time) You can see what modules your nginx binary is compiled with, by sudo nginx -V. Here's a sample output (line-break added):

◆ nginx -V

nginx version: nginx/1.1.19
TLS SNI support enabled

configure arguments:
--prefix=/etc/nginx
--conf-path=/etc/nginx/nginx.conf
--error-log-path=/var/log/nginx/error.log
--http-client-body-temp-path=/var/lib/nginx/body
--http-fastcgi-temp-path=/var/lib/nginx/fastcgi
--http-log-path=/var/log/nginx/access.log
--http-proxy-temp-path=/var/lib/nginx/proxy
--http-scgi-temp-path=/var/lib/nginx/scgi
--http-uwsgi-temp-path=/var/lib/nginx/uwsgi
--lock-path=/var/lock/nginx.lock
--pid-path=/var/run/nginx.pid
--with-debug
--with-http_addition_module
--with-http_dav_module
--with-http_geoip_module
--with-http_gzip_static_module
--with-http_image_filter_module
--with-http_realip_module
--with-http_stub_status_module
--with-http_ssl_module
--with-http_sub_module
--with-http_xslt_module
--with-ipv6
--with-sha1=/usr/include/openssl
--with-md5=/usr/include/openssl
--with-mail
--with-mail_ssl_module
--add-module=/build/buildd/nginx-1.1.19/debian/modules/nginx-auth-pam
--add-module=/build/buildd/nginx-1.1.19/debian/modules/nginx-echo
--add-module=/build/buildd/nginx-1.1.19/debian/modules/nginx-upstream-fair
--add-module=/build/buildd/nginx-1.1.19/debian/modules/nginx-dav-ext-module

for a list of available modules and their documentation, see: http://wiki.nginx.org/Modules

Module is a important concept. Because, nginx is made of modules, and each module has config directives. The config controls nginx's behavior. Working with nginx is mostly knowing about the modules and its config directive.

Config File and Directives

by default, the config file is at /etc/nginx/nginx.conf.

you can find the config location by nginx -V. Look for --conf-path.

config file content is made of “directives”. There are 2 forms of directives: line based and block based.

example of line directives:

user www-data;
worker_processes 4;
pid /var/run/nginx.pid;

example of block directives:

events {
        worker_connections 768;
        # multi_accept on;
}

block directive might be nested.

Each module has its own set of directives, usually block directive. For example, the “events” above is directives from “event” module.

the syntax and meaning of each directive is different. You need to lookup the documentation to see each module's directive's {purpose, syntax, default value, …}.

Here's one example of a directive: include another_config_file_path;. It is like inserting the file content, like C lang.

if config file has bad syntax, nginx won't start.

use nginx -t to check syntax of config file.

directives may contain predefined variables. For example, $pid

for a list of available modules and their documentation, see: http://wiki.nginx.org/Modules

documentation root dir

doc root is specified in the config file. If you installed nginx 1.1.19 in Ubuntu, it's at /usr/share/nginx/www/.

You can see the config spec from your main config (default /etc/nginx/nginx.conf) which contains the line include /etc/nginx/sites-enabled/*;, and the file there is a link to /etc/nginx/sites-enabled/default, which specifies the following:

server {
# …
        root /usr/share/nginx/www;
# …
}

Core Modules Config Spec

the most important part of using nginx is understanding its config files. So, now you should read up on the core module's config doc.

here's the default, most basic config file:

user www-data;                  # user and group for worker process
worker_processes 4;
pid /var/run/nginx.pid;         # process id file location

events {
        worker_connections 768; # number of tcp connection per worker process
}

http {
        sendfile on;
        tcp_nopush on;
        tcp_nodelay on;
        keepalive_timeout 65;
        types_hash_max_size 2048;

        include /etc/nginx/mime.types;
        default_type application/octet-stream;

        access_log /var/log/nginx/access.log;
        error_log /var/log/nginx/error.log;

        gzip on;
        gzip_disable "msie6";

        include /etc/nginx/conf.d/*.conf;
        include /etc/nginx/sites-enabled/*;
}