NGINX Integration Guide

AppSentinels supports NGINX integration through lightweight, linkable modules or plugins that can be incorporated into your existing web server deployments.

AppSentinels NGINX Deployment

🚀 Deployment Options

AppSentinels provides flexible deployment options to suit different infrastructure setups. You can integrate the modules into either host-based (baremetal) NGINX or container-based NGINX deployments.

NGINX or NGINX Running on Host - This option is suitable for environments where NGINX is installed directly on the host operating system (e.g., VM, physical server).

Container-Based NGINX Deployments - This option is intended for modern environments using Docker or container orchestration platforms like Kubernetes.

Server Host Icon

Baremetal NGINX or NGINX Running on Host

AppSentinels provides two loadable modules to be used with your existing host-based NGINX deployment:

These modules must be properly loaded and configured as explained in the steps below.

1. Load Modules

load_module /etc/nginx/modules/nginx_ext_auth_module.so;
load_module /etc/nginx/modules/nginx_ext_access_log_module.so;
thread_pool ext_access_log_thread_pool threads=1 max_queue=10000;
thread_pool ext_monitoring_thread_pool threads=1 max_queue=10;

After editing, restart NGINX to apply the changes and verify the modules are loaded correctly.

2. Configure the Application Server and Location Blocks

2.1 Out-of-Band (OOB) / Transparent Mode

Identify the application you wish to onboard and add the following configuration block into its NGINX server context: 

http {
        server {
          listen       9000;
          server_name  front-service;
      
          # AppSentinels config block start
          ext_auth_log_server http://onprem-controller:9004;
          ext_stats_server http://onprem-controller:9004;
          ext_instance "uat-region1";
          # AppSentinels config block end
      
          location / {
            proxy_pass http://localhost:3000;
          }
        }
      }

đź”— View Sample Transparent Mode NGINX Config

2.2 Service-Chaining / Enforcement Mode

Use this mode if inline enforcement is required. The incoming request is validated by the Edge Controller before being forwarded to the application. 

server {
        listen       9000;
        server_name  front-service;
      
        # AppSentinels config block start
        ext_auth_fail_allow on;
      
        location /auth {
          internal;
          proxy_pass http://onprem-controller:9004;
        }
      
        ext_stats_server http://onprem-controller:9004;
        ext_instance "uat-region1";
        # AppSentinels config block end
      
        location / {
          # AppSentinels config block start
          ext_auth_request /auth;
          # AppSentinels config block end
          proxy_pass http://localhost:3000;
        }
      }

đź”— View Sample Enforcement Mode NGINX Config

Container Icon

Container-Based NGINX Deployments

The integration approach used for baremetal deployments is equally applicable when NGINX is deployed as a container. AppSentinels modules can be mounted into or bundled within your container images.

1. Load Modules

openresty:
        image: openresty/openresty:alpine
        container_name: openresty
        ports:
          - 7001:7001
          - 9000:9000
        extra_hosts:
          - "onprem-controller:172.17.0.1"
        volumes:
          - ./nginx_ext_auth_module.so:/usr/local/openresty/nginx/modules/nginx_ext_auth_module.so
          - ./nginx_ext_access_log_module.so:/usr/local/openresty/nginx/modules/nginx_ext_access_log_module.so
          - ./openresty/nginx.conf:/usr/local/openresty/nginx/conf/nginx.conf
          - ./openresty/http.conf:/etc/nginx/conf.d/http.conf

đź”— View docker-compose.yaml reference 

load_module /etc/nginx/modules/nginx_ext_auth_module.so;
load_module /etc/nginx/modules/nginx_ext_access_log_module.so;
thread_pool ext_access_log_thread_pool threads=1 max_queue=10000;
thread_pool ext_monitoring_thread_pool threads=1 max_queue=10;

After configuration, restart the NGINX container to ensure modules are properly loaded.

2. Configure the Application Server and Location Blocks

Verify Icon

Verify Deployment

Once AppSentinels Edge Controllers are deployed and integrated with NGINX, their status can be verified via the AppSentinels Dashboard.

Note: Make sure the NGINX instance is configured correctly and the Edge Controller is reachable for API discovery.
Debugging Icon

Deployment / Debugging

tcpdump -i <ingress device eg: eth0, ens3> -A \\
      'port 9006 and (((ip[2:2] - ((ip[0]&0xf)<<2)) - ((tcp[12]&0xf0)>>2)) != 0)' | \\
      egrep --line-buffered "^........(GET |HTTP/|POST |HEAD )|^[A-Za-z0-9-]+: " | \\
      sed -r 's/^........(GET |HTTP/|POST |HEAD )/\\n\\1/g'
Note: Replace <ingress device> with the actual network interface name on your VM (e.g., eth0, ens3).
Upgrade Icon

Upgrading NGINX Version

If NGINX or OpenResty is upgraded to a newer version, the AppSentinels modules must be recompiled for compatibility with the updated binaries.

To initiate the recompilation process, please share the full output of the following system-level commands from the upgraded environment:

Once the updated modules are provided by AppSentinels, you can proceed with the integration and restart NGINX or your container as needed.

Tip: Always perform upgrades in a staging environment before applying them to production.