{"id":11394,"date":"2016-10-25T21:53:28","date_gmt":"2016-10-25T12:53:28","guid":{"rendered":"https:\/\/jirak.net\/wp\/compiling-dynamic-modules-for-nginx-plus\/"},"modified":"2016-10-25T22:34:40","modified_gmt":"2016-10-25T13:34:40","slug":"compiling-dynamic-modules-for-nginx-plus","status":"publish","type":"post","link":"https:\/\/jirak.net\/wp\/compiling-dynamic-modules-for-nginx-plus\/","title":{"rendered":"Compiling Dynamic Modules for NGINX Plus"},"content":{"rendered":"

Compiling Dynamic Modules for NGINX Plus<\/p>\n

NGINX Plus Release R11<\/a> introduces binary compatibility for dynamic modules. This article describes the build process, explaining how to compile third‑party NGINX modules so that they can be used in the NGINX Plus product.<\/p>\n

NGINX Modules Overview<\/h2>\n

NGINX modules are written in C and conform to the API described in Extending NGINX<\/a> on the NGINX Wiki. There is a large ecosystem of third‑party modules<\/a>, ranging from language interpreters to security solutions, and some of these are included and supported<\/a> in NGINX Plus.<\/p>\n

Other third‑party modules, and modules that you have created yourself, need to be compiled independently and loaded into NGINX Plus at runtime. You can compile these modules for use with NGINX Plus by building them against the open source NGINX software as described below:<\/p>\n

    \n
  1. Obtain the matching open source NGINX release<\/a><\/li>\n
  2. Obtain the module sources<\/a>, and update the config shell script if necessary to support the NGINX dynamic modules capability introduced in NGINX 1.9.11<\/li>\n
  3. Build the dynamic module<\/a> against the open source NGINX release, with the ‑‑with‑compat<\/code> argument to the configure<\/code> command<\/li>\n
  4. Load the resulting dynamic module<\/a> (the .so<\/strong> file) into NGINX Plus and use it as if it were a built‑in module<\/li>\n<\/ol>\n

    Example: A Simple \u201cHello World\u201d Module<\/h2>\n

    This example uses a simple Hello World module<\/a> to show how to update the source for a module and load it in NGINX Plus. The \u201cHello World\u201d module implements a simple directive (hello_world<\/code>) that responds to requests with a simple message.<\/p>\n

    Step 1: Obtain the Open Source NGINX Release<\/h3>\n

    Determine the open source NGINX version that corresponds to your NGINX Plus installation:<\/p>\n

    $ nginx -v<\/strong>
    \nnginx version: nginx\/1.11.5 (nginx-plus-r11)<\/pre>\n
    <\/code><\/p>\n
    In this example, it\u2019s NGINX 1.11.5. Download the corresponding open source NGINX package from build repository<\/a> at nginx.org<\/strong>:<\/p>\n
    $ wget http:\/\/nginx.org\/download\/nginx-1.11.5.tar.gz<\/strong>
    \n$ tar -xzvf nginx-1.11.5.tar.gz<\/strong><\/pre>\n
    <\/code><\/p>\n
    Step 2: Obtain the Module Sources<\/h3>\n
    Obtain the source for the \u2018Hello World\u2019 NGINX module from GitHub<\/a>:<\/p>\n
    $ git clone https:\/\/github.com\/perusio\/nginx-hello-world-module.git<\/strong><\/pre>\n
    <\/code><\/p>\n
    When dynamic modules were introduced, it was necessary to change the config shell file<\/a> that defines parameters for the module build process. It\u2019s straightforward to update old‑style config shell files to support the new parameters, as documented on the NGINX Wiki<\/a>.<\/p>\n
    Modify the file nginx‑hello‑world‑module\/config<\/strong> to contain the following:<\/p>\n
    ngx_addon_name=ngx_http_hello_world_module<\/p>\n
    if test -n \"$ngx_module_link\"; then
    \n    ngx_module_type=HTTP
    \n    ngx_module_name=ngx_http_hello_world_module
    \n    ngx_module_srcs=\"$ngx_addon_dir\/ngx_http_hello_world_module.c\"<\/p>\n
        . auto\/module
    \nelse
    \n    HTTP_MODULES=\"$HTTP_MODULES ngx_http_hello_world_module\"
    \n    NGX_ADDON_SRCS=\"$NGX_ADDON_SRCS $ngx_addon_dir\/ngx_http_hello_world_module.c\"
    \nfi<\/pre>\n
    <\/code><\/p>\n
    Step 3: Compile the Dynamic Module<\/h3>\n
    Compile the module by first running the configure<\/code><\/a> script with the new ‑‑with‑compat<\/code> argument, which creates a standard build environment supported by both open source NGINX and NGINX Plus. Then run make<\/code> modules<\/code> to build the module:<\/p>\n
    $ cd nginx-1.11.5\/<\/strong>
    \n$ .\/configure --with-compat --add-dynamic-module=..\/nginx-hello-world-module<\/strong>
    \n$ make modules<\/strong><\/pre>\n
    <\/code><\/p>\n
    Copy the module library (.so<\/strong> file) to \/etc\/nginx\/modules<\/strong>:<\/p>\n
    $ sudo cp objs\/ngx_http_hello_world_module.so \/etc\/nginx\/modules\/<\/strong><\/pre>\n
    <\/code><\/p>\n
    Step 4: Load and Use the Module<\/h3>\n
    To load the module into NGINX Plus, add the load_module<\/code><\/a> directive in the top‑level (main) context of your nginx.conf<\/strong> configuration file (not within the http<\/code> or stream<\/code> context):<\/p>\n
    load_module modules\/ngx_http_hello_world_module.so;<\/pre>\n
    <\/code><\/p>\n
    The module provides a hello_world<\/code> directive that returns the response \u2018hello world\u2019 from a location<\/code> block:<\/p>\n
    server {
    \n    listen 80;<\/p>\n
        location \/ {
    \n         hello_world;
    \n    }
    \n}<\/pre>\n
    <\/code><\/p>\n
    Reload your NGINX Plus configuration and test it with a simple request:<\/p>\n
    $ nginx -s reload<\/strong>
    \n$ curl http:\/\/localhost\/<\/strong>
    \nhello world<\/pre>\n
    <\/code><\/p>\n
    Example 2: The NAXSI Web Application Firewall<\/h2>\n
    NAXSI<\/a> is an easy‑to‑use, high‑performance web application firewall (WAF) that uses heuristics and a scoring system to identify suspicious requests such as XSS and SQL Injection attacks.<\/p>\n
    The NAXSI source has been updated to comply with the new format for the configuration shell file, so building a dynamic module for NGINX Plus is straightforward. The process is based on the NAXSI installation instructions<\/a>:<\/p>\n
    $ git clone https:\/\/github.com\/nbs-system\/naxsi.git<\/strong>
    \n$ cd nginx-1.11.5\/<\/strong>
    \n$ .\/configure --with-compat --add-dynamic-module=..\/naxsi\/naxsi_src<\/strong>
    \n$ make modules<\/strong>
    \n$ sudo cp objs\/ngx_http_naxsi_module.so \/etc\/nginx\/modules<\/strong><\/pre>\n
    <\/code><\/p>\n
    Using the NAXSI Module with NGINX Plus<\/h3>\n
    Load the module into the NGINX Plus core by adding the load_module<\/code> directive to the main context in your nginx.conf<\/strong> file:<\/p>\n
    load_module modules\/ngx_http_naxsi_module.so;<\/pre>\n
    <\/code><\/p>\n
    NAXSI configuration is described in detail in the project documentation<\/a>. The following NGINX configuration illustrates the module in action:<\/p>\n
    # Edit this 'include' directive to point to your naxsi_core.rules file
    \ninclude \/home\/owen\/src\/naxsi\/naxsi_config\/naxsi_core.rules;<\/p>\n
    server {
    \n    listen 80;<\/p>\n
        location \/ {
    \n        root \/usr\/share\/nginx\/html;<\/p>\n
            # Enable NAXSI
    \n        SecRulesEnabled;<\/p>\n
            # Define where blocked requests go
    \n        DeniedUrl \"\/50x.html\";<\/p>\n
            # CheckRules, determining when NAXSI needs to take action
    \n        CheckRule \"$SQL >= 8\" BLOCK;
    \n        CheckRule \"$RFI >= 8\" BLOCK;
    \n        CheckRule \"$TRAVERSAL >= 4\" BLOCK;
    \n        CheckRule \"$EVADE >= 4\" BLOCK;
    \n        CheckRule \"$XSS >= 8\" BLOCK;<\/p>\n
            # Don\u2019t forget the error_log, where blocked requests are logged
    \n        error_log \/tmp\/naxsi.log;
    \n    }<\/p>\n
        error_page   500 502 503 504  \/50x.html;
    \n}<\/pre>\n
    <\/code><\/p>\n
    You can verify the correct operation of NAXSI with a pair of simple HTTP requests:<\/p>\n