PingIntelligence

Configure NGINX for PingIntelligence

Configure the nginx.conf setup NGINX and PingIntelligence sideband integration. Following is a summary of steps to configure NGINX for PingIntelligence:

  1. Create modules directory inside NGINX

  2. Download PingIntelligence modules

  3. Copy PingIntelligence modules in the modules directory

  4. Edit nginx.conf for PingIntelligence

Create modules directory and download PingIntelligence modules

  1. Create a modules directory in NGINX:

    # mkdir /usr/local/nginx/modules
  2. Download the NGINX - PingIntelligence modules from the download site

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

    The PingIntelligence modules are:

    • ngx_ase_integration_module.so

    • ngx_http_ase_integration_request_module.so

    • ngx_http_ase_integration_response_module.so

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

      # 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

Configure nginx.conf:

Complete the following steps to configure nginx.conf for PingIntelligence. Make sure that the PingIntelligence module and other configurations are added at the correct place in nginx.conf as shown in the sample file at the end of the section.

  1. Load PingIntelligence modules: Edit the nginx.conf file to load the PingIntelligence modules. Following is a snippet of nginx.conf file showing the loaded PingIntelligence modules:

    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

    IP:PORT is the IP address of primary and secondary ASE.

  2. Add primary and secondary ASE hosts in nginx.conf in the upstream section. Following is a snippet of 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;
       }
  3. Configure SSL certificate: Configure a SSL certificate location and ASE sideband authentication token in nginx.conf. ASE certificate was extracted from ASE in Prerequisites. 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 sideband authentication token was created as part of the Prerequisites in the PingIntelligence section. 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>;

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

  4. Configure ASE request and response: Configure ASE request and response API endpoints in nginx.conf. 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;
    [.codeph]``ase_integration_ssl_verify`` is optional for non-SSL ASE connection.
  5. Apply PingIntelligence policy: Apply PingIntelligence modules for APIs by configuring location in nginx.conf. ase_integration_request should be the first and aase_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.

  6. Verify: 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
  7. Restart: Restart NGINX by entering the following command:

    # sudo /usr/local/nginx/sbin/nginx -s stop
    # sudo /usr/local/nginx/sbin/nginx
  8. 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
  9. Verify that NGINX has restarted by entering the following command:

    # netstat -tulpn | grep 4443

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