====== Nginx HTTP Server ======

**General Information**

Installation and configuration of Nginx web server. 

**Checklist**
  * Distro(s): Enterprise Linux 6/7

----

====== Installation ======

Installation of Nginx can be completed via repo (Official Nginx, EPEL, or Software Collections) or compiling.

===== Repo: Official Nginx =====

[[http://nginx.org/en/linux_packages.html|Nginx.org]] has pre-built packages. You can select mainline (newer) or stable.

Versions as of 04/13/2016:
  * Mainline: 1.9.14
  * Stable: 1.8.1
  * Legacy: 1.6.3 and below

  - Import nginx gpg signing key<code bash>rpm --import http://nginx.org/keys/nginx_signing.key</code>
  - Add a nginx repo file
    * Stable Repo:<code bash>vim /etc/yum.repos.d/nginx.repo
[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/centos/7/$basearch/
gpgcheck=0
enabled=1</code>
    * Mainline Repo:<code bash>vim /etc/yum.repos.d/nginx.repo
[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/mainline/centos/7/$basearch/
gpgcheck=0
enabled=1</code>
  - Install<code bash>yum install nginx</code>

===== Repo: EPEL =====

Versions as of 04/13/2016
  * CentOS 7.2: Nginx 1.6.3

Procedure
  * Install the [[linux_wiki:repos#epel|EPEL repo]]
  * Install Nginx<code bash>yum install nginx</code>

===== Repo: Software Collections =====

Versions as of 04/13/2016:
  * nginx 1.4 (legacy)
  * nginx 1.6 (legacy)
  * nginx 1.8 (stable)

  - Add the [[linux_wiki:repos#software_collections|software collections repo]].
  - Install<code bash>yum install rh-nginx18</code>
  - Enable the software collection<code bash>scl enable rh-nginx18 bash</code>
    - Run signal commands (nginx -s signal) as normal from the Operation section below
===== Compile and Install =====

Building from source is usually done for specific functionality and is more time consuming.

  - Install pre-reqs<code bash>yum install gcc pcre-devel zlib-devel</code>
  - [[http://nginx.org/en/download.html|Download]] a tarball (Example: Stable)<code bash>wget http://nginx.org/download/nginx-1.8.1.tar.gz</code>
  - Unarchive/unpack<code bash>tar -zxvf nginx-1.8.1.tar.gz</code>
  - Change into directory<code bash>cd nginx-1.8.1/</code>
  - Configure nginx<code bash>./configure --prefix=/usr/local/nginx</code>
    - Available configuration options: http://nginx.org/en/docs/configure.html
  - Compile<code bash>make</code>
  - Install<code bash>make install</code>

----

====== Configuration ======

  * Main Config: /etc/nginx/nginx.conf
    * Alt Main (Compiled): /usr/local/nginx/conf/nginx.conf
    * Alt Main (Software Collections): /etc/opt/rh/rh-nginx18/nginx/nginx.conf
  * Additional Config: /etc/nginx/conf.d/
    * Alt Additional Config (Compiled): No default
    * Alt Additional Config (Software Collections): /etc/opt/rh/rh-nginx18/nginx/conf.d/

----

===== Main Config: nginx.conf ====

  * Default repo installed file location: /etc/nginx/nginx.conf

Main nginx.conf config file, in the http context
<code bash>## NGINX - Main Configuration ##

# Context: Main - General Server Configuration

# User that worker processes run as
user  nginx;

# Number of worker processes (auto = set to number of CPUs)
worker_processes  auto;

# Error Log and PID of main process
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;


# Context: Events - Connection Processing
events {
  # Max number of connections per worker process
  worker_connections  1024;
}

# Context: HTTP - HTTP Server Directives
http {
  # MIME - Include file and default type
  include       /etc/nginx/mime.types;
  default_type  application/octet-stream;

  # Logging: Format and Main Access Log
  log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
  access_log  /var/log/nginx/access.log  main;

  # server_tokens off - Disable nginx version on error pages and response headers
  server_tokens off;

  ## Headers - Add additional headers ##
  # X-Frame-Options SAMEORIGIN -> Page can only be displayed in a frame on same origin
  add_header X-Frame-Options SAMEORIGIN;

  # X-Content-Type-Options nosniff -> Prevent MIME Type Attacks
  add_header X-Content-Type-Options nosniff;

  # X-XSS-Protection "1; mode=block" -> Prevent Some Cross Site Scripting
  #   1;mode=block -> XSS filter enabled, prevent rendering the page if attack detected
  add_header X-XSS-Protection "1; mode=block" always;
  
  # Content-Security-Policy -> Prevent XSS, clickjacking, code injection
  add_header Content-Security-Policy "default-src 'self';" always;
  
  # Combined directives: sendfile, tcp_nopush, tcp_nodelay all on
  # sendfile+tcp_nopush = use kernel dma to fill packets up to MSS, then send
  # tcp_nodelay = once the last packet is reached, tcp_nopush auto turned off,
  #               then tcp_nodelay forces the fast sending of the last data

  # Sendfile - Send files directly in kernel space
  # on -> keep on for locally stored files
  # off -> turn off for files served over network mounted storage
  sendfile        on;

  # tcp_nopush - Do not send data until packet reaches MSS
  # Dependency: sendfile MUST be on for this to work
  #tcp_nopush     on;

  # tcp_nodelay -  Send packets in buffer as soon as they are available
  #tcp_nodelay on;

  # Server side keepalive timeout in seconds (default: 75)
  keepalive_timeout  65;

  # Gzip - Compress responses using gzip
  #gzip  on;

  # Include enabled configurations
  include /etc/nginx/conf.d/enabled/*.conf;
}</code>

----

===== Default Config: default.conf ====

  * Create the available/enabled directories<code bash>mkdir /etc/nginx/conf.d/{available,enabled}</code>
  * Remove default installed config<code bash>rm /etc/nginx/conf.d/default.conf</code>
  * Create new default site/catch all config file<code bash>vim /etc/nginx/conf.d/available/default.conf

## Default Config - Catch All Matches ##

# HTTP (Port 80)
server {
    listen 80 default_server;
    server_name  _;

    # Redirect everything to HTTPS
    return 301 https://$http_host$request_uri;
}

# HTTPS (Port 443)
server {
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    server_name _;

    # HSTS (HTTPS Strict Transport Security)
    # 63072000 seconds = 2 years
    add_header Strict-Transport-Security "max-age=63072000; includeSubdomains" always;

    # SSL - Certificate Config
    ssl on;
    ssl_certificate /etc/pki/tls/mycert.crt;
    ssl_certificate_key /etc/pki/tls/mykey.key;
    ssl_client_certificate /etc/pki/tls/myca.crt;

    # SSL - Session Config
    ssl_session_timeout 5m;
    ssl_session_cache shared:SSL:50m;

    # SSL - Protocols and Ciphers
    ssl_protocols TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "HIGH:!AECDH:!DHE:!EDH:!RC4:!ADH:!3DES:!MEDIUM";

    # Location: Webserver root
    location / {
      # autoindex off - Disable directory listing output
      autoindex off;
      root /usr/share/nginx/html;
      index index.html index.htm;
    }
}</code>
  * Create symlink in enabled directory to default config<code bash>ln -s /etc/nginx/conf.d/available/default.conf /etc/nginx/conf.d/enabled/default.conf</code>
  * Deploy your SSL certificates.

----

===== Site Specific Config ====

Once the base config is in place, site specific config can be added.
  * Copy the default config to a new file<code bash>cp /etc/nginx/conf.d/available/default.conf /etc/nginx/conf.d/available/mysite.org.conf</code>
  * Edit the new file<code bash>/etc/nginx/conf.d/available/mysite.org.conf</code>
    * Replace server_name directives with system's fully qualified hostname. Example:<code bash>server_name  mywebserver.org;</code>
    * Remove "default_server" from the listen directives<code bash>listen 80;
listen 443 ssl;</code>
    * Make any other additional site specific config changes.

  * Create symlink to enable the new site<code bash>ln -s /etc/nginx/conf.d/available/mysite.org.conf /etc/nginx/conf.d/enabled/mysite.org.conf</code>
  * Disable the default.conf catch all config if you don't want it to function on a non-match to your site specific config<code bash>unlink /etc/nginx/conf.d/enabled/default.conf</code>
  * Restart nginx for changes to take affect
    * CentOS 6<code bash>/etc/init.d/nginx restart</code>
    * CentOS 7<code bash>systemctl restart nginx</code>

----

===== Example: Reverse Proxy =====

Nginx can function as a reverse proxy. This is particularly useful for:
  * Accepting connections on secure standard ports and forwarding them to non-secure/standard ports for applications
  * Sitting in front of an application server (that might be listening on localhost)
  * Load balancing

==== Forward to Non Standard Port ====

This example accepts connections on standard port 443/tcp and forwards the request to a Java application listening on localhost, port 8080/tcp.
<code bash>
server {
....
# Location: Reverse Proxy to Java App
    location /myapp/ {
      # Forward /myapp/ requests to correct port
      proxy_pass http://127.0.0.1:8080/myapp/;

      # Additional headers to pass
      proxy_set_header        Host            $host;
      proxy_set_header        X-Real-IP       $remote_addr;
      proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
</code>

----

===== SSL: Enforce Strong Encryption =====

  * Default file location: /etc/nginx/nginx.conf OR an included file

==== SSL: All in One ====

All in one copy/paste most secure SSL settings.<code bash>ssl_protocols TLSv1.2;
ssl_ciphers "HIGH:!MEDIUM:!3DES:!ADH:!AECDH:!DHE:!EDH:!RC4";
ssl_prefer_server_ciphers on;</code>

----

==== SSL: Protocols ====

**Protocols** - Use only TLS (1.2 only if possible)
  * TLSv1.2 only (**Preferred**)<code bash>ssl_protocols TLSv1.2;</code>
  * TLS<code bash>ssl_protocols TLSv1.2 TLSv1.1 TLSv1;</code>

----

==== SSL: Ciphers ====

**Ciphers** - Config
<code bash>
ssl_ciphers "HIGH:!MEDIUM:!3DES:!ADH:!AECDH:!DHE:!EDH:!RC4";
</code>

\\
**Ciphers** - Server picks compatible cipher
<code bash>
ssl_prefer_server_ciphers on;
</code>

----

===== Other Settings =====

Other secure settings.

==== Redirect HTTP to HTTPS ====

Redirect all HTTP to HTTPS<code bash>
server {
    listen 80 default_server;
    server_name  _;
 
    # Redirect everything to HTTPS
    return 301 https://$http_host$request_uri;
}</code>

----

==== HSTS ====

Enabling HTTPS Strict Transport Security (HSTS).

Add the strict transport security header to the listening HTTPS server section
<code bash>server {
  listen 443 ssl;
  listen [::]:443 ssl;
  server_name HOSTNAME-HERE;

  # HSTS (HTTPS Strict Transport Security)
  # 63072000 seconds = 2 years
  add_header Strict-Transport-Security "max-age=63072000; includeSubdomains" always;
....
}</code>
  * max-age=63072000 -> Tell web browsers to connect to the site using HTTPS only for two years. Countdown is reset each time the site is visited.

----

====== Operation ======

Controlling the nginx web server.

Nginx can be controlled via the system's service commands or nginx executable signals.

  * Main nginx executable: /usr/sbin/nginx
    * Alt main nginx executable (Compiled): /usr/local/nginx/sbin/nginx
    * Alt main nginx executable (Software Collections): /opt/rh/rh-nginx18/root/sbin/nginx

**Note**: If using the software collections method, that environment must be enabled before you attempt to operate the web server.<code bash>scl enable rh-nginx18 bash</code>
  * This could be put in a user's .bashrc for easier use if needed.

----

==== Enable on Boot ====

  * Autostart the nginx web server upon system startup
<code bash>systemctl enable nginx</code>

----

==== Start ====

  * Evaluate config files; if syntax is ok, start
<code bash>systemctl start nginx</code>
or
<code bash>nginx</code>

----

==== Stop ====

  * Stop the nginx processes now
  * Kills current sessions
<code bash>systemctl stop nginx</code>
or
<code bash>nginx -s stop</code>

----

==== Reload Config ====

  * Equivalent to Apache httpd's "graceful" restart
  * Check syntax
    * if ok, then spawn new workers with new config and signal old workers to shutdown after current requests are complete
    * if NOT ok, continue using old configuration
<code bash>systemctl reload nginx</code>
or
<code bash>nginx -s reload</code>

----

==== Restart ====

  * Kill worker processes immediately
<code bash>systemctl restart nginx</code>
or
<code bash>nginx -s stop && nginx -s start</code>

----

==== Graceful Stop ====

  * Equivalent to Apache httpd's "graceful-stop"
  * Wait for worker processes to finish serving current requests, then stop.
  * Do not accept new requests
<code bash>nginx -s quit</code>

----