nginx

This page contains changes which are not marked for translation.

Other languages:

Resources

nginx is a robust, small, high performance web server and reverse proxy server. It is a good alternative to popular web servers like Apache and lighttpd.

Installation

Before immediately installing the www-servers/nginx package, first take a good look at the USE flags for Nginx.

Expanded USE flags

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:

FILE /etc/portage/make.conf

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:

FILE /etc/portage/package.use

www-servers/nginx NGINX_MODULES_HTTP: fastcgi

USE flags

USE flags for www-servers/nginx Robust, small and high performance http and reverse proxy server

`+http`	Enable HTTP core support
`+http-cache`	Enable HTTP cache support
`+http2`	Enable HTTP2 module support
`+pcre2`	Enable support for pcre2
`aio`	Enables file AIO support
`debug`	Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
`http3`	Enable HTTP3 module support
`ktls`	Enable Kernel TLS offload (kTLS)
`libatomic`	Use libatomic instead of builtin atomic operations
`pcre`	Add support for Perl Compatible Regular Expressions
`pcre-jit`	Enable JIT for pcre
`rtmp`	NGINX-based Media Streaming Server
`selinux`	!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
`ssl`	Enable HTTPS module for http. Enable SSL/TLS support for POP3/IMAP/SMTP for mail.
`test`	Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
`threads`	Add threads support for various packages. Usually pthreads
`vim-syntax`	Pulls in related vim syntax scripts

Data provided by the Gentoo Package Database · Last update: 2024-10-22 22:30 More information about USE flags

Emerge

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

root #emerge --ask www-servers/nginx

Installation verification

The default nginx configuration defines a virtual server with the root directory set to /var/www/localhost/htdocs. You can find the default index file in this folder at /var/www/localhost/htdocs/index.html.

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:

root #/etc/init.d/nginx start

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:

user $curl http://localhost

Configuration

The nginx configuration is handled through the /etc/nginx/nginx.conf file.

Single site access

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

FILE /etc/nginx/nginx.confGentoo's default configuration

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

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

FILE /etc/nginx/nginx.confMultisite configuration

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;
}

FILE /etc/nginx/conf.d/local.confSimple host

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;
}

FILE /etc/nginx/conf.d/local-ssl.confSimple SSL host

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

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.

FILE /etc/nginx/nginx.confEnabling PHP support

...
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:

root #echo "dev-lang/php fpm" >> /etc/portage/package.use

Rebuild PHP with the fpm USE flag enabled:

root #emerge --ask dev-lang/php

Note
Using UNIX socket communication is the preferred and recommended configuration

For PHP 7.0 and newer PHP versions use following configuration:

FILE /etc/php/fpm-php8.2/fpm.d/www.confRunning PHP with UNIX socket support

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:

FILE /etc/php/fpm-php8.2/php.iniSetup timezone in php.ini

date.timezone = <PUT_TIMEZONE_HERE>

Start the php-fpm daemon:

root #/etc/init.d/php-fpm start

Add php-fpm to the default runlevel:

root #rc-update add php-fpm default

Reload nginx with changed configuration:

root #/etc/init.d/nginx reload

Alternatively, for systemd:

root #

systemctl enable php-fpm@8.2

root #systemctl start php-fpm@8.2

IP address access list

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)

FILE /etc/nginx/nginx.confEnabling and configuring an IP access lists for /nginx_status page

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

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

FILE /etc/nginx/nginx.confEnabling and configuring user authentication for the / location

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

The htpasswd file can be generated using:

user $echo -n 'foo:' >> domain.htpasswd

This will create the domain.htpasswd file, containing a row for the user 'foo'.

Note
The string with the user name should end with ':', this is the separator field between the user name and the password.

user $openssl passwd >> domain.htpasswd

This will add the password to the line for the user 'foo'. The password will be asked in the prompt, once it's over, the file could be opened and will contain something like this:

FILE /etc/nginx/conf/domain.htpasswdContent of the domain.htpasswd file, for user foo with a ciphered password

foo:$1$lpC3de5Y$dnh6jegS1qlfZVo7rGExz/

The password is not in plain text, but it's ciphered with the OpenSSL utility. Even if the file is stolen, it will be no use to determine the password.

Geolocation using GeoIP2

The GeoIP2 module makes use of GeoIP2 databases by Maxmind or similar. Using Maxmind is already supported in Gentoo through net-misc/geoipupdate. However, registration of an account is required in order to obtain a free license key and download the free database.

Downloading Maxmind GeoIP2 databases

Once an account is created, install and configure geoipupdate:

root #emerge --ask net-misc/geoipupdate

Enter the account and license key:

FILE /etc/GeoIP.confAdd your account info

AccountID YOURID
LicenseKey YOURKEY
EditionIDs GeoLite2-ASN GeoLite2-City GeoLite2-Country

After that, you'll need to download the databases:

root #

geoipupdate

In order receive updates automatically in the future, add this command to a weekly cronjob or systemd timer.

Add GeoIP2 support to Nginx

To enable to modules and rebuild Nginx:

FILE /etc/portage/package.use/nginxAdd the modules to Nginx

www-servers/nginx NGINX_MODULES_HTTP: geo geoip2

Note
The geoip module only supports the GeoIP legacy database.

Rebuild nginx with the third party modules enabled:

root #emerge --ask www-servers/nginx

Once Nginx has been rebuild, point Nginx to the databases and the GeoIP2 variables:

FILE /etc/nginx/nginx.confPointing to the GeoIP2 databases and its values

http {
...
    geoip2 /usr/share/GeoIP/GeoLite2-City.mmdb {
        auto_reload 5m;
        $geoip2_metadata_city_build metadata build_epoch;
        $geoip2_data_city_name city names en;
        $geoip2_data_city_geonameid city geoname_id;
        $geoip2_data_continent_code continent code;
        $geoip2_data_continent_geonameid continent geoname_id;
        $geoip2_data_continent_name continent names en;
        $geoip2_data_country_geonameid country geoname_id;
        $geoip2_data_country_code iso_code;
        $geoip2_data_country_name names en;
        $geoip2_data_country_is_eu is_in_european_union;
        $geoip2_data_location_accuracyradius location accuracy_radius;
        $geoip2_data_location_latitude location latitude;
        $geoip2_data_location_longitude location longitude;
        $geoip2_data_location_metrocode location metro_code;
        $geoip2_data_location_timezone location time_zone;
        $geoip2_data_postal_code postal code;
        $geoip2_data_rcountry_geonameid registered_country geoname_id;
        $geoip2_data_rcountry_iso registered_country iso_code;
        $geoip2_data_rcountry_name registered_country names en;
        $geoip2_data_rcountry_is_eu registered_country is_in_european_union;
        $geoip2_data_region_geonameid subdivisions 0 geoname_id;
        $geoip2_data_region_iso subdivisions 0 iso_code;
        $geoip2_data_region_name subdivisions 0 names en;
    }

    geoip2 /usr/share/GeoIP/GeoLite2-ASN.mmdb {
        auto_reload 5m;
        $geoip2_data_autonomous_system_number autonomous_system_number;
        $geoip2_data_autonomous_system_organization autonomous_system_organization;
    }
...
}

The auto_reload option will allow updating the database without restarting Nginx.

For the GeoIP2 values to show up in a PHP application, assign them as fastcgi_param values:

FILE /etc/nginx/fastcgi.confAdd GeoIP2 support to PHP

...
fastcgi_param GEOIP2_CITY_BUILD_DATE $geoip2_metadata_city_build;
fastcgi_param GEOIP2_CITY $geoip2_data_city_name;
fastcgi_param GEOIP2_CITY_GEONAMEID $geoip2_data_city_geonameid;
fastcgi_param GEOIP2_CONTINENT_CODE $geoip2_data_continent_code;
fastcgi_param GEOIP2_CONTINENT_GEONAMEID $geoip2_data_continent_geonameid;
fastcgi_param GEOIP2_CONTINENT_NAME $geoip2_data_continent_name;
fastcgi_param GEOIP2_COUNTRY_GEONAMEID $geoip2_data_country_geonameid;
fastcgi_param GEOIP2_COUNTRY_CODE $geoip2_data_country_code;
fastcgi_param GEOIP2_COUNTRY_NAME $geoip2_data_country_name;
fastcgi_param GEOIP2_COUNTRY_IN_EU $geoip2_data_country_is_eu;
fastcgi_param GEOIP2_LOCATION_ACCURACY_RADIUS $geoip2_data_location_accuracyradius;
fastcgi_param GEOIP2_LATITUDE $geoip2_data_location_latitude;
fastcgi_param GEOIP2_LONGITUDE $geoip2_data_location_longitude;
fastcgi_param GEOIP2_LOCATION_METROCODE $geoip2_data_location_metrocode;
fastcgi_param GEOIP2_LOCATION_TIMEZONE $geoip2_data_location_timezone;
fastcgi_param GEOIP2_POSTAL_CODE $geoip2_data_postal_code;
fastcgi_param GEOIP2_REGISTERED_COUNTRY_GEONAMEID $geoip2_data_rcountry_geonameid;
fastcgi_param GEOIP2_REGISTERED_COUNTRY_ISO $geoip2_data_rcountry_iso;
fastcgi_param GEOIP2_REGISTERED_COUNTRY_NAME $geoip2_data_rcountry_name;
fastcgi_param GEOIP2_REGISTERED_COUNTRY_IN_EU $geoip2_data_rcountry_is_eu;
fastcgi_param GEOIP2_REGION_GEONAMEID $geoip2_data_region_geonameid;
fastcgi_param GEOIP2_REGION $geoip2_data_region_iso;
fastcgi_param GEOIP2_REGION_NAME $geoip2_data_region_name;

fastcgi_param GEOIP2_ASN $geoip2_data_autonomous_system_number;
fastcgi_param GEOIP2_ASN_ORG $geoip2_data_autonomous_system_organization;

Third party modules

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:

FILE /etc/portage/make.confAdding third party module

NGINX_ADD_MODULES="/usr/src/nginxmodule"

Rebuild nginx with the third party module enabled:

root #emerge --ask www-servers/nginx

Usage

Service control

OpenRC

Start nginx web server:

root #rc-service nginx start

Stop nginx web server:

root #rc-service nginx stop

Add nginx to the default runlevel so that the service starts automatically on system reboot:

root #rc-update add nginx default

Reload nginx configuration without dropping connections:

root #rc-service nginx reload

Restart the nginx service:

root #rc-service nginx restart

systemd

Start nginx web server:

root #systemctl start nginx

Stop nginx web server:

root #systemctl stop nginx

Check the status of the service:

root #systemctl status nginx

Enable service to start automatically on system reboot:

root #systemctl enable nginx

Reload nginx configuration without dropping connections:

root #systemctl reload nginx

Restart the nginx service:

root #systemctl restart nginx

Troubleshooting

In case of problems, the following commands can help troubleshoot the situation.

Validate configuration

Verify that the running nginx configuration has no errors:

root #/usr/sbin/nginx -t

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

Check if nginx processes are running:

user $ps aux | egrep 'nginx|PID'

  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

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

root #ss -tulpn | grep :80

tcp   LISTEN 0      0          0.0.0.0:80         0.0.0.0:*    users:(("nginx",pid=6253,fd=52),("nginx",pid=6252,fd=52))

External resources

https://nginx.org/en/docs/beginners_guide.html - A nginx beginner's guide. Helpful for those who do not know much about nginx.
https://nginx.com/resources/admin-guide/ - The ngnix administration guide. Helpful for web administrators who have been working in the field.
https://wiki.nginx.org/Main - The nginx wiki.
https://github.com/h5bp/server-configs-nginx - H5BP nginx config.

nginx

Contents

Installation

Expanded USE flags

USE flags

USE flags for www-servers/nginx Robust, small and high performance http and reverse proxy server

Emerge

Installation verification

Configuration

Single site access

Multiple site access

PHP support

IP address access list

Basic authentication

Geolocation using GeoIP2

Downloading Maxmind GeoIP2 databases

Add GeoIP2 support to Nginx

Third party modules

Usage

Service control

OpenRC

systemd

Troubleshooting

Validate configuration

Verify processes are running

Verify bound addresses and ports

See also

External resources