PingIntelligence

Configuring NGINX

Configure NGINX for your operating system and then for PingIntelligence.

About this task

To configure NGINX, complete the following configuration steps:

  1. Configure NGINX for either RHEL 7.6 or Ubuntu 16.04.

  2. Configure NGINX for PingIntelligence.

  • RHEL 7.6

  • Ubuntu 16.04

Configuring NGINX for RHEL 7.6

Configure NGINX for RHEL 7.6.

About this task

To compile NGINX Community Edition 1.14.2 for PingIntelligence for APIs:

Steps

  1. Download the NGINX community version:

    # wget https://nginx.org/download/nginx-1.14.2.tar.gz
  2. Untar the NGINX file:

    # tar -xvzf nginx-1.14.2.tar.gz
  3. Change the directory to nginx-1.14.2:

    # cd nginx-1.14.2
  4. Compile and install NGINX by running the following command.

    These options for compiling NGINX are in addition to your environment specific options.

    # ./configure --with-compat --with-http_ssl_module
    • --with-compat: This option enables NGINX to load dynamic modules.

    • --with_http_ssl_module: This flag is used configure SSL support in NGINX.

  5. Run the make command to compile NGINX:

    # make
  6. Run the make install command to install NGINX:

    # sudo make install
  7. Verify the compilation by entering the following command:

    # sudo /usr/local/nginx/sbin/nginx -V

    Result:

    The output of the above command should display --with-compat and --with_http_ssl_module flags.

Configuring NGINX for Ubuntu 16.04

Configure NGINX for Ubuntu 16.04.

About this task

To compile NGINX Community Edition 1.14.2 for PingIntelligence for APIs:

Steps

  1. Download the NGINX community version:

    # wget https://nginx.org/download/nginx-1.14.2.tar.gz
  2. Untar the NGINX file:

    # tar -xvzf nginx-1.14.2.tar.gz
  3. Change the directory to nginx-1.14.2:

    # cd nginx-1.14.2
  4. Compile and install NGINX by running the following command.

    These options for compiling NGINX are in addition to your environment-specific options:

    • --with-compat: This option enables NGINX to load dynamic modules.

    • --with_http_ssl_module: This flag is used configure Secure Sockets Layer (SSL) support in NGINX.

    # ./configure --with-compat --with-http_ssl_module
  5. Run the make command to compile NGINX:

    # make
  6. Run the make install command to install NGINX:

    # sudo make install
  7. Verify the compilation by entering the following command:

    # sudo /usr/local/nginx/sbin/nginx -V

    Result:

    The output of the above command should display --with-compat and --with_http_ssl_module flags.

Configuring NGINX for PingIntelligence

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

About this task

To configure NGINX for PingIntelligence:

Steps

  1. Create a modules directory in NGINX:

    # mkdir /usr/local/nginx/modules
  2. Download the NGINX - PingIntelligence policy modules from the PingIntelligence Downloads 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
  4. 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
  5. 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
  6. 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;
       }
  7. 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 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>;
  8. 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;
  9. 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.

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

    # sudo /usr/local/nginx/sbin/nginx -s stop
    # sudo /usr/local/nginx/sbin/nginx
  12. 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
  13. 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;
        }
    }