Nginx

Expanded USE flags[edit | edit source]

Nginx uses modules to enhance its features. To simplify the maintenance of this modular approach, the nginx ebuild uses expanded USE (USE_EXPAND) flags to denote which modules should be installed.

• HTTP related modules can be enabled through the NGINX_MODULES_HTTP variable
• Mail related modules can be enabled through the NGINX_MODULES_MAIL variable
• Third party modules can be enabled through the NGINX_ADD_MODULES variable

These variables need to be set in /etc/portage/make.conf. Their descriptions can be found in /var/db/repos/gentoo/profiles/desc/nginx_modules_http.desc and /var/db/repos/gentoo/profiles/desc/nginx_modules_mail.desc.

For example, to enable the fastcgi module:

NGINX_MODULES_HTTP="fastcgi"

The above will overwrite the default value of NGINX_MODULES_HTTP and set it to fastcgi. To enable the fastcgi module without overwriting the default NGINX_MODULES_HTTP value, the following USE flag notation can be specified in /etc/portage/package.use:

www-servers/nginx NGINX_MODULES_HTTP: fastcgi

USE flags[edit | edit source]

Emerge[edit | edit source]

With the USE flags set, install www-servers/nginx:

Installation verification[edit | edit source]

The default nginx configuration defines a virtual server with the root directory set to /var/www/localhost/htdocs. However due to bug #449136, the nginx ebuild will only create the /var/www/localhost directory and without an index file. To have a working default configuration, create the /var/www/localhost/htdocs directory and simple index file:

The nginx package installs an init service script allowing administrators to stop, start, or restart the service. Run the next command to start the nginx service:

To verify that nginx is properly running, point a web browser to the http://localhost address or use a command-line web tool like curl:

Single site access[edit | edit source]

The following example shows a single-site access, without dynamic capabilities (such as PHP).

user nginx nginx;
worker_processes 1;
 
error_log /var/log/nginx/error_log info;
 
events {
	worker_connections 1024;
	use epoll;
}
 
http {
	include /etc/nginx/mime.types;
	default_type application/octet-stream;
 
	log_format main
		'$remote_addr - $remote_user [$time_local] '
		'"$request" $status $bytes_sent '
		'"$http_referer" "$http_user_agent" '
		'"$gzip_ratio"';
 
	client_header_timeout 10m;
	client_body_timeout 10m;
	send_timeout 10m;
 
	connection_pool_size 256;
	client_header_buffer_size 1k;
	large_client_header_buffers 4 2k;
	request_pool_size 4k;
 
	gzip off;
 
	output_buffers 1 32k;
	postpone_output 1460;
 
	sendfile on;
	tcp_nopush on;
	tcp_nodelay on;
 
	keepalive_timeout 75 20;
 
	ignore_invalid_headers on;
 
	index index.html;
 
	server {
		listen 127.0.0.1;
		server_name localhost;
 
		access_log /var/log/nginx/localhost.access_log main;
		error_log /var/log/nginx/localhost.error_log info;
 
		root /var/www/localhost/htdocs;
	}
}

Multiple site access[edit | edit source]

It is possible to leverage the include directive to split the configuration in multiple files:

user nginx nginx;
worker_processes 1;
 
error_log /var/log/nginx/error_log info;
 
events {
	worker_connections 1024;
	use epoll;
}
 
http {
	include /etc/nginx/mime.types;
	default_type application/octet-stream;
 
	log_format main
		'$remote_addr - $remote_user [$time_local] '
		'"$request" $status $bytes_sent '
		'"$http_referer" "$http_user_agent" '
		'"$gzip_ratio"';
 
	client_header_timeout 10m;
	client_body_timeout 10m;
	send_timeout 10m;
 
	connection_pool_size 256;
	client_header_buffer_size 1k;
	large_client_header_buffers 4 2k;
	request_pool_size 4k;
 
	gzip off;
 
	output_buffers 1 32k;
	postpone_output 1460;
 
	sendfile on;
	tcp_nopush on;
	tcp_nodelay on;
 
	keepalive_timeout 75 20;
 
	ignore_invalid_headers on;
 
	index index.html;
 
	include /etc/nginx/conf.d/*.conf;
}

server {
        listen 127.0.0.1;
        server_name localhost;
  
        access_log /var/log/nginx/localhost.access_log main;
        error_log /var/log/nginx/localhost.error_log info;
  
        root /var/www/localhost/htdocs;
}

server {
    listen 443 ssl;
    server_name host.tld;
    ssl_certificate /etc/ssl/nginx/host.tld.pem;
    ssl_certificate_key /etc/ssl/nginx/host.tld.key;
}

PHP support[edit | edit source]

Add the following lines to the nginx configuration to enable PHP support. In this example nginx is exchanging information with the PHP process via a UNIX socket.

...
http {
...
    server { 
    ...
            location ~ \.php$ {
                       # Test for non-existent scripts or throw a 404 error
                       # Without this line, nginx will blindly send any request ending in .php to php-fpm
                       try_files $uri =404;
                       include /etc/nginx/fastcgi.conf;
                       fastcgi_pass unix:/run/php-fpm.socket;
           }
    }
}

To support this setup, PHP needs to be built with FastCGI Process Manager support (dev-lang/php), which is handled through the fpm USE flag:

Rebuild PHP with the fpm USE flag enabled:

For PHP 7.0 and newer PHP versions use following configuration:

listen = /run/php-fpm.socket
listen.owner = nginx

Set the timezone in the php-fpm php.ini file. Substitute the <PUT_TIMEZONE_HERE> text in the FileBox below with the appropriate timezone information:

date.timezone = <PUT_TIMEZONE_HERE>

Start the php-fpm daemon:

Add php-fpm to the default runlevel:

Reload nginx with changed configuration:

Alternatively, for systemd:

IP address access list[edit | edit source]

The next example shows how to allow access to a particular URL (in this case /nginx_status) only to:

• certain hosts (e.g. 192.0.2.1 127.0.0.1)
• and IP networks (e.g. 198.51.100.0/24)

http {
    server { 
            location /nginx_status {
                     stub_status on;
                     allow 127.0.0.1/32;
                     allow 192.0.2.1/32;
                     allow 198.51.100.0/24;
                     deny all;
             }
     }
}

Basic authentication[edit | edit source]

nginx allows limiting access to resources by validating the user name and password:

http {
    server { 
            location / {
                   auth_basic           "Authentication failed";
                   auth_basic_user_file conf/htpasswd;
             }
     }
}

The htpasswd file can be generated using:

Third party modules[edit | edit source]

Download third party module source and move it to /usr/src. Manually compile the selected Nginx module, then add the following line to /etc/portage/make.conf:

NGINX_ADD_MODULES="/usr/src/nginxmodule"

Rebuild nginx with the third party module enabled:

Service control[edit | edit source]

Validate configuration[edit | edit source]

Verify that the running nginx configuration has no errors:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

By running nginx with the -t option, it will validate the configuration file without actually starting the nginx daemon. Use the -c option with the full path to the file to test configuration files in non-default locations.

Verify processes are running[edit | edit source]

Check if nginx processes are running:

  PID TTY      STAT   TIME COMMAND
26092 ?        Ss     0:00 nginx: master process /usr/sbin/nginx -c /etc/nginx/nginx.conf
26093 ?        S      0:00 nginx: worker proces

Verify bound addresses and ports[edit | edit source]

Verify nginx daemon is listening on the right TCP port (such as 80 for HTTP or 443 for HTTPS):

tcp        0      0 127.0.0.1:80            0.0.0.0:*               LISTEN      0          12336835   -26092/nginx: master