Configuring NGINX for PingIntelligence

Configure the nginx.conf setup NGINX and PingIntelligence sideband integration.

About this task

To configure NGINX for PingIntelligence:

Steps

Create a modules directory in NGINX:
```
# mkdir /usr/local/nginx/modules
```
Download the NGINX - PingIntelligence policy modules from the PingIntelligence Downloads site.

Untar the downloaded file.

tar -xvzf ubuntu_modules_1.14.2.tgz
modules/
modules/nginx-oss-list.txt
modules/ngx_ase_integration_module.so
modules/ngx_http_ase_integration_response_module.so
modules/ngx_http_ase_integration_request_module.so

Copy the three PingIntelligence modules for Ubuntu to the modules directory of NGINX.

The three PingIntelligence modules are:
- ngx_ase_integration_module.so
- ngx_http_ase_integration_request_module.so
- ngx_http_ase_integration_response_module.so
  # cp ngx_ase_integration_module.so /usr/local/nginx/modules # cp ngx_http_ase_integration_request_module.so /usr/local/nginx/modules # cp ngx_http_ase_integration_response_module.so /usr/local/nginx/modules

Edit the nginx.conf file to load the PingIntelligence modules.

Example:

The following is a snippet of the nginx.conf file showing the loaded PingIntelligence modules. IP:PORT is the IP address of primary and secondary ASE.

worker_processes  1;

error_log  /usr/local/nginx/logs/error.log debug;
worker_rlimit_core  500M;
working_directory  /usr/local/nginx;

pid        /usr/local/nginx/pid/nginx.pid;

load_module modules/ngx_ase_integration_module.so; load_module modules/ngx_http_ase_integration_request_module.so; load_module modules/ngx_http_ase_integration_response_module.so;
events {
    worker_connections  1024;
}

http \{ keepalive_timeout 65; upstream pi.ase \{ server IP:PORT max_fails=1 max_conns=1024 fail_timeout=10; server IP:PORT max_fails=1 max_conns=1024 fail_timeout=10 backup; keepalive 32; }
 truncated nginx.conf

Add primary and secondary ASE hosts in nginx.conf in the upstream section.

Example:

The following is a snippet of the nginx.conf file with an ASE primary and secondary host configuration:

http {
    keepalive_timeout  65;
    upstream pi.ase {
        server 192.168.11.12:443 max_fails=3 max_conns=1024 fail_timeout=10; server 192.168.11.13:443 max_fails=3 max_conns=1024 fail_timeout=10 backup;
       keepalive 32;
   }

Configure an SSL certificate location and ASE sideband authentication token in nginx.conf. Copy the certificate to /usr/local/nginx/ssl/test.ase.pi on the NGINX machine and configure the certificate path in nginx.conf file.

The ASE certificate was extracted from ASE in Preparing to deploy the PingIntelligence policy. The sideband authentication token was created in step 1c of Preparing to deploy the PingIntelligence policy.

You can also use your own Secure Sockets Layer (SSL) certificate by providing the path to the certificate in set $certificate. Make sure that ASE has the updated certificate.

Example:

The following is a snippet the showing certificate location and sideband authentication token:

#Certificiate location of ASE
     set $certificate /usr/local/nginx/ssl/test.ase.pi;
    #ASE Token for sideband authentication
     set $ase_token <YOUR ASE SIDEBAND TOKEN>;

Configure ASE request and response API endpoints in nginx.conf.

ase_integration_ssl_verify is optional for non-SSL ASE connection.

Example:

The following snippet of nginx.conf shows ASE request and response:

                   #ASE Request Proxy Configuration     location = /ase/request {
       internal;
       ase_integration https://pi.ase;
       ase_integration_method "POST";
       ase_integration_http_version 1.1;
       ase_integration_ase_token $ase_token;
       ase_integration_correlation_id $correlationid;
       ase_integration_host pi.ase;
       ase_integration_ssl_trusted_certificate /usr/local/nginx/ssl/test.ase.pi;
       ase_integration_ssl_verify    off;
       ase_integration_ssl_verify_depth 1;
       ase_integration_ssl_server_name on;
       ase_integration_ssl_name test.ase.pi;
       ase_integration_next_upstream error timeout non_idempotent;

     #ASE Response Proxy Configuration     location = /ase/response {
       internal;
       ase_integration https://pi.ase;
       ase_integration_method "POST";
       ase_integration_http_version 1.1;
       ase_integration_ase_token $ase_token;
       ase_integration_correlation_id $correlationid;
       ase_integration_host pi.ase;
       ase_integration_ssl_trusted_certificate /usr/local/nginx/ssl/test.ase.pi;
       ase_integration_ssl_verify    off;
       ase_integration_ssl_verify_depth 1;
       ase_integration_ssl_server_name on;
       ase_integration_ssl_name test.ase.pi;
       ase_integration_next_upstream error timeout non_idempotent;

Apply PingIntelligence modules for APIs by configuring location in nginx.conf.

ase_integration_request should be the first, and an ase_integration_response should be the last.
```
location /shop {
       ase_integration_request;
       proxy_pass http://localhost:8000/;
       ase_integration_response;
}
```
If you have more than more than one API, configure a location for each API as shown above.

Verify that nginx.conf is syntactically correct by running the following command:

# sudo /usr/local/nginx/sbin/nginx -t
nginx: the configuration file /usr/local/nginx/conf/nginx.conf syntax is ok
nginx: configuration file /usr/local/nginx/conf/nginx.conf test is successful

Restart NGINX by entering the following command:

# sudo /usr/local/nginx/sbin/nginx -s stop
# sudo /usr/local/nginx/sbin/nginx

Run the following command to verify if --with-compat and --with-http_ssl_module is in the list of flags under configured arguments:

# sudo /usr/local/nginx/sbin/nginx -V
nginx version: nginx/1.14.2
built by gcc 5.4.0 20160609 (Ubuntu 5.4.0-6ubuntu1~16.04.11)
built with OpenSSL 1.0.2g  1 Mar 2016
TLS SNI support enabled
configure arguments: --with-compat --with-http_ssl_module

Verify that NGINX has restarted by entering the following command:

# netstat -tulpn | grep 4443

Example:

The following is a sample nginx.conf for reference:

worker_processes 1; error_log /usr/local/nginx/logs/error.log debug; worker_rlimit_core 500M; working_directory /usr/local/nginx; pid /usr/local/nginx/pid/nginx.pid; load_module modules/ngx_ase_integration_module.so; load_module modules/ngx_http_ase_integration_request_module.so; load_module modules/ngx_http_ase_integration_response_module.so;

events {
    worker_connections  1024;
}

http \{ keepalive_timeout 65; upstream pi.ase \{ server IP:PORT max_fails=1 max_conns=100 fail_timeout=10; server IP:PORT max_fails=1 max_conns=100 fail_timeout=10 backup; keepalive 32; }

server {
    # remove "ssl" from the below line for a non-SSL frontend
    listen              4443 ssl bind;
    server_name         localhost;

    # Comment out the next 5-lines for a non-SSL frontend
    ssl_certificate     /usr/local/nginx/ssl/cert.pem;
    ssl_certificate_key /usr/local/nginx/ssl/key.pem;
    ssl_password_file   /usr/local/nginx/ssl/password_file;
    ssl_protocols       TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    #root                /usr/share/nginx/html;
    #charset koi8-r;
    #access_log  /var/log/nginx/host.access.log  main;
    resolver 8.8.8.8 ipv6=off;

    #The following location configuration is to configure your application. A corresponding API JSON should be present in ASE.
    location / {
       ase_integration_request;
       proxy_pass http://localhost:8080/;
       ase_integration_response;
       }
    #The following configuration is a Ping Intelligence configuration and do not edit
    set $correlationid $pid-$request_id-$server_addr-$remote_addr-$remote_port-$request_length-$connection;

# ASE token must be configured
# ASE certificate must be copied under /usr/local/nginx/ssl/ and update the set $certificate to the # certificate file path
#Certificate location of ASE
    set $certificate /usr/local/nginx/ssl/test.ase.pi;
    #ASE Token for sideband authentication
    set $ase_token <YOUR ASE SIDEBAND TOKEN HERE>;
    #Host header which should be send to ASE
    set $ase_host pi.ase;
    #SNI value to use for ASE
    set $ase_ssl_host pi.ase;
    #ASE Request Proxy Configuration
    location = /ase/request {
       internal;
       ase_integration https://pi.ase;
       ase_integration_method "POST";
       ase_integration_http_version 1.1;
       ase_integration_ase_token $ase_token;
       ase_integration_correlation_id $correlationid;
       ase_integration_host $ase_host;
       ase_integration_ssl_trusted_certificate $certificate;
       ase_integration_ssl_verify    off;
       ase_integration_ssl_verify_depth 1;
       ase_integration_ssl_server_name off;
       ase_integration_ssl_name $ase_ssl_host;
       ase_integration_next_upstream error timeout non_idempotent;
    }
    #ASE Response Proxy Configuration
    location = /ase/response {
       internal;
       ase_integration https://pi.ase;
       ase_integration_method "POST";
       ase_integration_http_version 1.1;
       ase_integration_ase_token $ase_token;
       ase_integration_correlation_id $correlationid;
       ase_integration_host $ase_host;
       ase_integration_ssl_trusted_certificate $certificate;
       ase_integration_ssl_verify    off;
       ase_integration_ssl_verify_depth 1;
       ase_integration_ssl_server_name off;
       ase_integration_ssl_name $ase_ssl_host;
       ase_integration_next_upstream error timeout non_idempotent;
    }
}