HTTP v2 Support

The PerimeterX NGINX module supports HTTP v2 for both Third-Party and First-Party implementations. To verify that your NGINX is running with HTTP v2 support, run:

nginx -V

For NGINX modules that support HTTP v2, the flag --with-http_v2_module will be listed. For example:

# nginx -V
nginx version: nginx/1.13.3
built by gcc 5.4.0 20160609 (Ubuntu 5.4.0-6ubuntu1~16.04.10)
built with OpenSSL 1.0.2g  1 Mar 2016
TLS SNI support enabled
configure arguments: --prefix=/nginx --with-ld-opt=-Wl,-rpath,/usr/local/lib --add-module=/ngx_devel_kit-0.3.0 --add-module=/lua-nginx-module-0.10.10 --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-ipv6 --with-http_v2_module

If you are running in Third-Party mode, you do not need to take any additional actions for the PerimeterX NGINX module to support HTTP v2.

If you are running in First-Party mode, add the following location to your nginx.conf file:

location /<app id without PX prefix>/xhr/ {
    proxy_buffering on;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $server_name;
    proxy_set_header X-PX-Enforcer-True-IP $remote_addr;
    proxy_set_header X-PX-First-Party 1;
    set $pxcookie "";
    if ($cookie__pxvid != "") {
        set $pxcookie pxvid=$cookie__pxvid;
    }
    if ($cookie_pxvid != "") {
        set $pxcookie pxvid=$cookie_pxvid;
    }
    proxy_set_header cookie $pxcookie;
    proxy_pass https://collector-<app_id>.perimeterx.net/;
}

Note: Make sure you replace the <app id without PX prefix> and <app_id> with your PerimeterX appId value.

NGINX Plus

The PerimeterX NGINX module is compatible with NGINX Plus. Users or administrators should install the NGINX Plus Lua dynamic module (LuaJIT).

NGINX Dynamic Modules

If you are using NGINX with dynamic module support you can load the Lua module with the following lines at the beginning of your NGINX configuration file.

load_module modules/ndk_http_module.so;
load_module modules/ngx_http_lua_module.so;

Multiple App Support

The PerimeterX Enforcer allows multiple configurations for different applications.

If your PerimeterX account contains several applications (as defined in the Portal), you can create different configurations for each application.

NOTE: The application initializes a timed Enforcer. The Enforcer must be initialized with one of the applications in your account. The the correct configuration file name must be passed to the require ("px.utils.pxtimer").application("AppName"|empty) block in the server initialization.

  1. Open the nginx.conf file, and locate the require("px.pxnginx").application() line inside your location block.
  2. Pass the desired application name into the application() function.

    For example: require("px.pxnginx").application("mySpecialApp")
  3. Locate the pxconfig.lua file, and create a copy of it.
    The copy name should follow the pattern:
    pxconfig-<AppName>.lua (e.g. pxconfig-mySpecialApp.lua)
    The < AppName > placeholder must be replaced by the exact name provided to the application function in step 1.
  4. Change the configuration in file created in step 3.
  5. Save the file in the location where pxnginx.lua file is located.
    (Default location: /usr/local/lib/lua/px/<yourFile>)
  6. For every location block of your app, replace the code mentioned in step 2 with the correct < AppName >.

Setting Up A First Party Prefix

In some cases you may need to define a prefix to the Enforcer's First-Party routes. The custom prefix must be defined both in the Enforcer's config file and in the PerimeterX console.

To define the First-Party Prefix:

  1. In your pxconfig.lua file, set the _M.first_party_prefix property to the desired prefix value. For example:
_M.first_party_prefix = 'resources'
  1. Open the PerimeterX Console.

  2. Go to Admin -> Applications.

  3. Open the Snippet section. Activate First-Party (if not in First-Party already), and click Edit next to the Copy Snippet button.

  4. In the pop-up that opens there are two routes beginning with /<appId without PX>. Copy both routes to a side document to use in the next steps.

  5. Click Advanced Configuration.

  6. Under Sensor, copy the first route from step 5 and add the prefix you added in step 1 to the beginning of of the route.
    For example: /resources/<appId without PX>/init.js

  7. Under Server copy the second route from step 5 and the prefix you added in step 1 to the beginning of the route.

    For example: /resources/<appId without PX>/xhr

  8. Click Save Changes.

  9. Click Copy Snippet and update the JS Sensor snippet of your site with the updated one.


Did this page help you?