NGINX.COM
Web Server Load Balancing with NGINX Plus

This document describes requirements and processes for the NGINX Plus Certified Module Program. It is intended for authors of dynamic modules who wish to have them certified.

Overview

The NGINX Plus Certified Module Program is designed for third‑party partners who create software modules that augment or enhance NGINX Plus functionality, and want to broaden their use among NGINX Plus customers. NGINX Plus Certified Modules provide the assurance that the partner solution has undergone NGINX’s development and review process, and comes with business‑level support available from the partner.

To be considered for certification, partners design and build their modules, building features into NGINX Plus, then they submit their modules to NGINX, Inc. for testing and verification, so that customers can deploy the modules with confidence that they do not affect functionality in other parts of the NGINX Plus application delivery platform. The program builds on the support for dynamic modules introduced with the release of NGINX Plus R11 in October 2016.

After building and functionally testing the candidate module, the partner self‑certifies it by running a suite of fault‑tolerance tests provided by NGINX, Inc. to demonstrate that the module has no negative effect on existing NGINX Plus features or functionality. When all tests are passed successfully, the partner submits the module to NGINX, Inc. for additional testing against the NGINX Plus platform. A module that passes all tests is classified as an NGINX Plus Certified Module and listed on the NGINX, Inc. website for easy access by customers. The partner remains responsible for distributing and supporting the module.

Eligibility Requirements for Modules and Partners

Like all other dynamic modules for NGINX Plus, an NGINX Plus Certified Module must be a binary‑compatible module that can be loaded by NGINX Plus at runtime. The program does not extend to Lua‑based scripts or modules. The Lua module is already certified with NGINX Plus, so there is no need to further certify scripts that use it. Partners can, however, port functionality from existing Lua scripts to a binary module and submit the module for certification.

Partners in the NGINX Plus Certified Module program must have a professional organization in place to provide support to NGINX Plus customers who deploy the partner’s module. Community modules distributed and maintained only by volunteers are not eligible for certification.

The NGINX Plus Certified Module program is open both to partners who have an existing dynamic module for open source NGINX that they want to extend to NGINX Plus, and to partners creating a module from scratch. Time to reach certification and the type of assistance available from NGINX, Inc. varies depending on the module’s level of maturity.

Module Certification Process

This section is a detailed walk‑through of the stages in the NGINX Plus Certified Module Program, including requirements and procedures.

Discussion of Module Design and Deployment

Upon receipt of the partner’s request for certification, NGINX, Inc. meets with the partner to discuss the module’s intended use cases, design, and plans for deployment and support. Not all technical use cases require a certified module. Topics for discussion include:

  1. Use cases addressed by the module.

  2. Confirmation that it’s technically feasible for a module to address the use cases.

  3. Discussion of the platforms the module supports and methods for distributing the certified module to end customers. Preferably, the partner makes the module available on all platforms supported in the current NGINX Plus release.

  4. Expectations for support in future versions of NGINX Plus. Preferably the partner will extend support to additional platforms as NGINX Plus becomes available on them in future releases. In addition, it is expected that the partner:

    • Provide documentation to customers that explains the module’s features, how to configure them, and how they interact with NGINX Plus.
    • Manage discrete versions of the module for specific releases of NGINX Plus, as well as for different platforms.
    • Release a new version of the module at the same time NGINX, Inc. releases a new version of NGINX Plus. NGINX, Inc. will make prerelease binaries and configuration files available to the partner in advance of the release to help the partner prepare the new version.

  5. Plans for distributing the module. The usual expectation is that the partner (rather than NGINX, Inc.) makes the module available to customers.

    NGINX, Inc. can provide advice on the pros and cons of various distribution channels, including direct file download from the partner website or other repository, inclusion in OS vendor distributions, and so on.

  6. Marketing support. NGINX, Inc. lists all certified modules on the Dynamic Modules page on its website, marked with the Certified Modules “bug”.

    • The partner provides its corporate or product logo and the standard information about the module that is listed on the page.
    • Other marketing support can be provided.

  7. Non‑disclosure agreement (NDA) and Program agreement.

Partner Build, Functional Testing, and Self‑Certification Process

In this phase, the partner builds the module against one or more versions of the open source NGINX software, each one corresponding to an NGINX Plus release. The partner performs functional testing and also runs compatibility tests provided by NGINX, Inc., which also provides technical assistance as necessary.

  1. Partner decides which NGINX Plus releases to support initially. At minimum, the partner must support the release that is current at the time the module is to be made available to customers. The partner can choose to support earlier releases as a courtesy to customers who have not yet upgraded. The corresponding open source NGINX versions are listed on the NGINX Plus Releases page.

  2. NGINX, Inc. provides documentation for the build process, along with NGINX Plus Developer licenses.

  3. Partner develops the module, builds it against all open source NGINX versions chosen in Step 1, and performs functional testing. During these phases, the partner directs questions and requests for advice to the community support sites for open source NGINX.

  4. Partner runs the self‑certification tests provided by NGINX, Inc., which additionally can provide technical assistance for creating the self‑certification testing environment.

NGINX, Inc. Certification Process

In this phase, NGINX, Inc. further tests the partner module against functionality that is exclusive to NGINX Plus, and certifies it when it passes all tests.

  1. Partner provides to NGINX, Inc.:

    1. The .so file for at least one (but preferably all) of the platforms the module supports. If multiple NGINX Plus releases are supported, the partner provides .so files for all of them.
    2. Build and running environment, which includes a list of which Unix distributions the partner is supporting.
    3. Dependent files (other .so files, database files, etc.).
    4. Module documentation.
      1. Basic usage and feature documentation is acceptable, but must include instructions for loading and configuring the module in NGINX Plus configuration files, as well as detailed descriptions of any configuration options required. It is helpful to include sample configuration files.
      2. If the module requires non‑standard distribution libraries, such as those contained in CentOS/RHEL EPEL repositories, that must be documented with details on how to make the module compatible with NGINX Plus on those distributions.
    5. The full command used to test the module in Step 5 of Self‑Certifying the Module with the NGINX Test Suite.
    6. The output from the successful tests, gathered in Step 6 of Self‑Certifying the Module with the NGINX Test Suite.
    7. The materials listed in Marketing Support, which enable NGINX, Inc. to provide marketing support.

    If possible, the partner provides the module bundle in standard Linux package formats (.deb, .rpm) with the dependencies appropriate for the corresponding release of NGINX Plus (especially if the module is to be delivered to customers that way).

  2. The NGINX Plus engineering and certification team runs further tests to validate the module against NGINX Plus internals. The expected turnaround time is two weeks, including the time it takes the partner to correct any failures uncovered during testing.

  3. When the module passes all tests, NGINX, Inc. certifies the module, and provides the partner with the following marketing collateral:

    1. Graphics files for the NGINX Plus Certified Module logo, which the partner can use to promote the module.
    2. A listing for the module on the Dynamic Modules page on the NGINX, Inc. website. The listing includes the partner logo, a description of the module, and a link to the partner’s instructions for obtaining and installing the module.

Update and Recertification Process

To remain an NGINX Plus Certified Module, a module must be recertified at each NGINX Plus release and at any other time that NGINX, Inc. significantly changes the NGINX Plus API. To support this requirement:

  1. NGINX, Inc.:

    1. Notifies the partner of the forthcoming NGINX Plus release, typically 10–20 days before the release date.
    2. Grants the partner access to prerelease binaries so it can test the module against the open source version that corresponds to the upcoming release.
    3. Provides the suite of self‑certification tests applicable to the upcoming release.

  2. Partner rebuilds the module against the appropriate open source NGINX version, and runs the new self‑certification tests.

  3. Partner provides to NGINX, Inc. the materials that prove successful recertification (listed in Step 1 of NGINX, Inc. Certification Process).

The partner is not required to submit the updated module to NGINX, Inc. for testing against NGINX Plus features (Step 2 in NGINX, Inc. Certification Process), but NGINX, Inc. will perform such testing at any time as requested.

NGINX, Inc. continues to provide marketing support as described in Marketing Support.

The module remains an NGINX Plus Certified Module until the next major NGINX Plus release, or until there is a major issue with the module in the field that requires an immediate module update. In this case, NGINX, Inc. can provide assistance with the fix.

Marketing Support

To enable NGINX, Inc. to provide Marketing support, before launch the partner provides the following information for publication on the Dynamic Modules page. NGINX, Inc. may edit text to comply with company style guidelines; partner gets to approve changes.

  • Graphics file for its corporate or product logo
  • Module description (50–75 words), including functionality and how the module integrates with the partner’s other solutions
  • Link and instructions for downloading the module
  • Link to written support policy
  • Direct contact information for partner support team, for use by the NGINX Plus support team (information is not shared with customers)

To assist the partner in promoting the module, NGINX, Inc. in addition provides:

  • Key messages highlighting the value of your solution with NGINX Plus
  • NGINX Plus Certified Module logo you can use for your website and collateral
  • A quote suitable for inclusion in partner’s press release

Technical Documentation

This section provides more detailed information about the phases in Module Certification Process, including step‑by‑step instructions.

Design Requirements for Certified Modules

Understanding of NGINX Internals

We recommend that you have a good understanding of the internal NGINX Plus functions for connection and traffic management before you start developing your module. The NGINX Development Guide includes complete documentation. If you have any questions or issues with the documentation, send email to the NGINX development mailing list.

Module Architecture Requirements

Every dynamic module is loaded into NGINX Plus by including a load_module directive for it in the top‑level (“main”) context of the base nginx.conf configuration file. However, the NGINX Plus architecture flexibly allows the module developer to enable, configure, and manage module behavior in other configuration contexts. It’s possible, for example, to include module‑specific directives in the http block or in the server block for a virtual server, either directly in the main nginx.conf file, or (as is recommended) in a function‑specific file located in /etc/nginx/conf.d/.

For your module to be certified, it MUST comply with the following requirements, which provide the most flexibility in development and deployment while still giving the greatest assurance that the module can be loaded and configured without causing an impact to NGINX core.

  • Your module must load in a disabled state; that is, when the load_module directive is evaluated at runtime, the module must load into NGINX Plus but must not perform any actions. For example, if the module initializes by starting a scripting engine to which it passes traffic, it must not do so (and the engine must not start) when the module is loaded, but only when the module is explicitly enabled.
  • Use a directive to explicitly enable and disable the module, with the default value of off (disabled). If you provide a default configuration file with the module, set the directive to off there. If you don’t provide a default configuration file, specify in the documentation that the user needs to set the off value.
  • Use additional directives, or parameters to directives, to pass configuration settings to the module.

  • When the module fails due to a configuration error, it must gracefully exit and inform the user which configuration issue needs to be addressed. For example, suppose you use a directive like the following in the NGINX Plus configuration to pass a file of module configuration instructions to your module:

    hello_world_conf /etc/nginx/hello_world.conf;

    In this case, your module must check for the hello_world.conf file, gracefully exit if it is missing or has errors in it, and alert the user and provide details about the problem.

  • While not yet a requirement, we strongly recommend that your module interact with NGINX Plus functions in a nonblocking way. For example, if you bind your module to port 8888 and your module invokes an out‑of‑band call to an external service, the module must not block NGINX Plus from continuing to process normal traffic on other ports, such as ports 80 or 443.

    At any time, NGINX, Inc. may opt to make the nonblocking architecture a requirement for certification and add it to the set of Perl prove validation tests (see Self‑Certifying the Module with the NGINX Test Suite).

These practices ensure that NGINX Plus can load its configuration and start successfully even if the module is misconfigured (for example, required directives are missing). If NGINX, Inc. discovers during testing that misconfiguration of your module prevents successful NGINX Plus startup, it will not be certified, even if it passes all other tests.

Basic Configuration Example

The following is an example of how to load, configure, and manage your module with NGINX Plus configuration options.

/etc/nginx/nginx.conf:

load_module modules/ngx_acme_http_hello_world.so;

http {
    hello_world_conf /etc/nginx/hello_world.conf; 
    hello_world_enable off;
}

/etc/nginx/conf.d/default.conf:

upstream test_pool {
    server 127.0.0.1:8100;
    server 127.0.0.1:8200;
}

server { 
    listen 172.16.55.10:80 default_server;
    proxy_set_header Host $host;

    location / {
        proxy_pass http://test_pool;
        hello_world_enable on;
        proxy_http_version 1.1;
    }
}

Instructions for Building, Self‑Certifying, and Submitting a Module for Certification

This section provides step‑by‑step instructions for building a module, confirming that it loads correctly in NGINX Plus, running tests to self‑certify it, and submitting it to NGINX, Inc. for full certification.

The instructions assume that you are familiar with the NGINX Plus architecture, know how to interact with various HTTP functions embedded in the NGINX and NGINX Plus core, and understand the process of building a module for NGINX or NGINX Plus.

Module Naming Conventions

We highly recommend that the modules you distribute have descriptive .so filenames that include:

  • Your company or product name.
  • A protocol indicator – http for HTTP or stream for TCP/UDP.
  • The module name.
  • The open source version number that corresponds to an NGINX Plus release, so that customers readily determine which version of the module is running. This can be especially important during upgrades when failures result from a mismatch between the NGINX release and the open source version against which a module is built.

For example, these are appropriate names for a Hello World module from the Acme Corporation that is compatible with NGINX Plus R12 (NGINX version 1.11.10):

ngx_acme_http_hello_world_module_1.11.10.so
ngx_acme_stream_hello_world_module_1.11.10.so

In the documentation that you provide to customers, instruct them to symbolically link the descriptive module name to a generic module name during install:

$ sudo ln -s /etc/nginx/modules/ngx_acme_http_hello_world_module_1.11.10.so /etc/nginx/modules/ngx_acme_http_hello_world.so

The customer’s nginx.conf file then refers to the symbolic link rather than the version‑specific filename:

load_module modules/ngx_acme_http_hello_world.so

Building a Dynamic Module

The first step in certifying your module is to build it against the open source NGINX versions that correspond to the NGINX Plus releases your module needs to support. If you have already done so, skip to Step 4.

  1. Determine which open source NGINX versions correspond to the NGINX Plus releases your module needs to support. For existing NGINX Plus releases, see the NGINX Plus Releases page. For future NGINX Plus releases, contact NGINX, Inc.

  2. Download the sources for each NGINX version from nginx.org (for example, 1.11.10 for NGINX Plus R12).

    $ wget http://nginx.org/download/nginx-version.tar.gz
$ tar -xzvf nginx-version.tar.gz

  3. For each NGINX version and each platform that you are supporting, compile the dynamic module to generate a .so file. For example: 

    $ cd nginx-version
$ ./configure --with-compat --add-dynamic-module=../ngx_acme_http_hello_world_module 
$ make modules

    See our blog for detailed instructions on compiling dynamic modules for NGINX and NGINX Plus or creating installable packages for dynamic modules.

    We also suggest that you build the complete binary for each NGINX version. This is useful to have for testing and debugging if not all self‑certification tests pass in the next section. For instructions, see the NGINX Plus Admin Guide.

  4. For each platform type, install NGINX Plus on the system where the .so file resides. Load your module into the NGINX Plus configuration and verify that the module works as expected.

Self-Certifying the Module with the NGINX Test Suite

Next you run the self‑certification test suite provided by NGINX, Inc. The suite was originally designed to verify that an open source module doesn’t adversely affect any standard functionality of the open source NGINX software. To self‑certify your module, you run the test suite against the NGINX Plus binary for each release you want to support. The suite is a series of Perl tests built for the Perl prove tool. For more information about using the prove tool, see the prove man page.

We strongly recommend that you write prove tests specific to your module as well, to have a test scenario in place for future updates to your module as well as new NGINX Plus releases. While not required, this is an advisable step for all partners developing their own commercial modules for NGINX Plus.

A note on permissions: NGINX and NGINX Plus log files are owned by a specific user, which varies by platform. For example, on Linux‑based installations NGINX and NGINX Plus run as user nginx, whereas on BSD installations the username is www. The following sudo commands are appropriate when NGINX is running as user nginx on a Linux system.

  1. Download the tip.tar.gz test suite from NGINX, Inc. and unpack it in the directory of your choice:

    $ wget http://hg.nginx.org/nginx-tests/archive/tip.tar.gz
$ tar zxvf tip.tar.gz

  2. Stop all running nginx processes. The test suite temporarily opens a series of incoming ports in the 8000–8999 range, which might conflict with ports used by your NGINX or NGINX Plus deployment.

    $ sudo service nginx stop

  3. Change directory to the directory where you extracted the test suite. This directory is named nginx-tests-UUID, where UUID is a unique identifier for each revision of the tip.tar.gz package. The following command shows an example.

    $ cd nginx-tests-d12c45f14102

  4. Verify that the Perl modules required to support all of the NGINX prove tests are installed. The Appendix lists the required Perl modules as of the time of writing, but the list is subject to change as new prove tests are added.

    You can use the following command, which runs a baseline test without any modules loaded, to confirm that the prove tests can access the Perl modules as required.

    $ sudo -u nginx TEST_NGINX_BINARY=/usr/sbin/nginx prove -Q .

    The output includes this message for each missing module:

    skipped: [Perl::Module] not installed

  5. Working in the nginx-tests-UUID directory, run the following command to load your module and any module‑specific configuration (see Basic Configuration Example for sample configuration.) Make sure the module is disabled so that it does not interact with the configuration used, and artificial traffic generated, by each prove test.

    • The TEST_NGINX_GLOBALS environment variable passes in the load_module directive that names the .so file for the dynamic module. Here the module is ngx_acme_hello_world_module_1-11-10.so in the standard modules directory, /etc/nginx/modules.
    • The TEST_NGINX_GLOBALS_HTTP environment variable passes in any module‑specific configuration directives that normally appear in the http context. In the following example, it passes in the hello_world_conf directive to name the configuration file and the hello_world_enable directive to disable the module.
    • The TEST_NGINX_BINARY environment variable specifies the location of the NGINX Plus binary. In this command, it is the standard location, /usr/sbin/nginx.

    $ sudo -u nginx TEST_NGINX_GLOBALS="load_module /etc/nginx/modules/ngx_acme_hello_world_module_1-11-10.so;" TEST_NGINX_GLOBALS_HTTP="hello_world_conf /etc/nginx/conf.d/hello_world.conf; hello_world_enable off;" TEST_NGINX_BINARY=/usr/sbin/nginx prove -Q .

    If all tests pass, a summary report like the following is displayed:

    All tests successful.
Test Summary Report
-------------------
Files=286, Tests=3516, 264 wallclock secs ( 1.30 usr  0.81 sys + 22.75 cusr  4.35 csys = 29.21 CPU)
Result: PASS

  6. Once all tests have passed, run the test suite again to capture verbose output into a text file that you’ll include when submitting the module to NGINX, Inc. for certification:

    $ sudo -u nginx TEST_NGINX_GLOBALS="load_module /etc/nginx/modules/ngx_acme_hello_world_module_1-11-10.so;" TEST_NGINX_GLOBALS_HTTP="hello_world_conf /etc/nginx/conf.d/hello_world.conf; hello_world_enable off;" TEST_NGINX_BINARY=/usr/sbin/nginx prove -v . > ../nginx-plus-module-prove-test-verbose 2>&1

If tests fail, assistance is available from NGINX, Inc., as detailed in the next section.

Debugging and Obtaining Assistance from NGINX, Inc.

If some tests in the NGINX prove suite do not pass and you cannot determine the cause, NGINX, Inc. is available to assist. Please contact your NGINX partner manager.

You must perform additional debugging before requesting assistance, because NGINX, Inc. cannot provide support for basic development of open source modules; direct those questions and requests for advice to the community support sites for open source NGINX.

Methods for determining the cause of test failures include:

  • Extracting the list of failed tests from the prove log files.

  • Running each failed test with a debugger, enabling you to focus on individual errors introduced by your module into the NGINX Plus running environment.

    As part of your normal debugging process, it might be useful to run the tests against the open source NGINX binary as well as the NGINX Plus binary (you compiled the open source binary in Step 3 of Building a Dynamic Module). Change the value of the TEST_NGINX_BINARY environment variable to refer to the open source binary.

  • Capturing all output in a file. The following command writes to a file called nginx-plus-module-prove-test-results.

    $ sudo -u nginx TEST_NGINX_GLOBALS="load_module /etc/nginx/modules/ngx_acme_hello_world_module_1-11-10.so;" TEST_NGINX_GLOBALS_HTTP="hello_world_conf /etc/nginx/conf.d/hello_world.conf; hello_world_enable off;" TEST_NGINX_BINARY=/usr/sbin/nginx prove -Q . > ../nginx-plus-module-prove-test-results 2>&1

  • Capturing a trace of the commands that the tests pass to NGINX (plus the output captured by the previous command), by setting the TEST_NGINX_VERBOSE and TEST_NGINX_LEAVE environment variables to true:

    $ sudo -u nginx TEST_NGINX_GLOBALS="load_module /etc/nginx/modules/ngx_acme_hello_world_module_1-11-10.so;" TEST_NGINX_GLOBALS_HTTP="hello_world_conf /etc/nginx/conf.d/hello_world.conf; hello_world_enable off;" TEST_NGINX_BINARY=/usr/sbin/nginx TEST_NGINX_VERBOSE=true TEST_NGINX_LEAVE=true prove -v . > ../nginx-plus-module-prove-test-verbose 2>&1

  • Running the separate NGINX Plus debugging test suite.

    1. Download and install the nginx-plus-dbg package. For example:

      $ sudo apt install nginx-plus-dbg

    2. Run the prove command with the TEST_NGINX_BINARY environment variable set to the debugging binary (here, it is /usr/sbin/nginx-debug). Also add the -v debug* argument to the prove command.

      $ sudo -u nginx TEST_NGINX_GLOBALS="load_module /etc/nginx/modules/ngx_acme_hello_world_module_1-11-10.so;" TEST_NGINX_GLOBALS_HTTP=”hello_world_conf /etc/nginx/conf.d/hello_world.conf; hello_world_enable off;” TEST_NGINX_BINARY=/usr/sbin/nginx-debug TEST_NGINX_VERBOSE=true TEST_NGINX_LEAVE=true prove -v debug* > ../nginx-plus-module-prove-debug-test-verbose 2>&1

Submitting Your Module for Certification

The final phase is submitting your self‑certified module to NGINX, Inc. for certification against NGINX Plus. The tests in this phase exercise features that are exclusive to NGINX Plus, and are the same ones we run on our own NGINX Plus dynamic modules.

To kick off this testing, please submit your binary .so module file to your NGINX partner manager for testing (per the requirements detailed in NGINX, Inc. Certification Process above). NGINX, Inc. runs the module through the same tests we use when building NGINX Plus modules. If any tests fail, we will provide details about the problem and ways to remedy it. When all tests pass, we inform you that your module is now an NGINX Plus Certified Module.

Submit the following to NGINX, Inc.:

  1. The .so file for at least one (but preferably all) of the platforms the module supports. If multiple NGINX Plus releases are supported, provide .so files for all of them.

  2. Build and running environment, which includes a list of which Unix distributions you are supporting.

  3. Dependent files (other .so files, database files, etc.).

  4. Module documentation.

    • Basic usage and feature documentation is acceptable, but must include instructions for loading and configuring the module in NGINX Plus configuration files, as well as detailed descriptions of any configuration options required. It is helpful to include sample configuration files.
    • If the module requires nonstandard distribution libraries, such as those contained in CentOS/RHEL EPEL repositories, that must be documented with details on how to make the module compatible with NGINX Plus on those distributions.

  5. The full command used to test the module in Step 5 of Self‑Certifying the Module with the NGINX Test Suite.

  6. The output from the successful tests, gathered in Step 6 of Self‑Certifying the Module with the NGINX Test Suite.

  7. The materials listed in Marketing Support, which enable NGINX, Inc. to provide marketing support.

Here is a sample README file with the required information:

Partner: Acme Corporation

Module description: Module returns the “Hello World!” string as an HTTP response when connecting to a certain port on NGINX. 

Build environment: Ubuntu Xenial

Dependent files: 
  - libhw.so.2.1 (located in /usr/lib or linked ref'd with LD_LIBRARY_PATH)
  - hello_world.conf 

Command Used for Testing:

# sudo -u nginx TEST_NGINX_GLOBALS="load_module /etc/nginx/modules/ngx_acme_hello_world_module_1-11-10.so;" TEST_NGINX_GLOBALS_HTTP=”hello_world_conf /etc/nginx/conf.d/hello_world.conf; hello_world_enable off;” TEST_NGINX_BINARY=/usr/sbin/nginx TEST_NGINX_VERBOSE=true prove -v . > ../nginx-plus-module-prove-test-verbose 2>&1

Distributing Certified Modules via the Partner’s Distribution Environment

By distributing the module directly to customers, the partner:

  • Does not have to support all platforms supported by NGINX Plus, though this is always preferable.
  • Is able to provide the module to NGINX, Inc. for certification in the form of source code, an installable package or .so file appropriate for any NGINX Plus supported platform, along with the material listed in Step 1 of NGINX, Inc. Certification Process.

FAQ

NGINX Plus Certified Modules Program

Q: I’ve built (or use) a community module and would like it to become an NGINX Plus Certified Module. Is this possible?
A: Only if you have a professional organization in place to provide support to NGINX Plus customers who deploy the certified module. Community modules distributed and maintained only by volunteers are not eligible.

Q: Can I distribute my NGINX Plus Certified Module via the NGINX Plus repo or another repo managed by NGINX, Inc.?
A: Not at this time. We recommend distributing your module via package repositories suitable for your supported platforms, or as a direct file download.

Q: Our NGINX Plus Certified Module is for the current version of NGINX Plus, but we want to support customers using older NGINX Plus releases. Can they use the current module?
A: No. You need to create a separate version of the module for each NGINX Plus release you want to support, built against the corresponding open source NGINX version. It is already expected that partners provide new modules for customers upgrading to future NGINX Plus major (“Rxx“) releases.

Q: Do I need to maintain multiple versions of my module?
A: Yes, for each combination of NGINX Plus release and platform you support.

Q: What does the upgrade process look like for our customer who is using a previous release of NGINX Plus and attempts to load a module for the current NGINX Plus release?
A: The upgrade attempt will fail because of the mismatch between NGINX Plus releases (or more precisely, between the versions of open source NGINX that correspond to the NGINX Plus releases). To support customers running different NGINX Plus releases, you must provide a separate module for each release, built against the corresponding open source version; see Building a Dynamic Module.

Note that in a related scenario, customers who upgrade to a new NGINX Plus release without upgrading your module to that release will experience a failure. For details that you can share with your customers, see Recovering From a Failed NGINX Plus Upgrade on our blog.

Module Certification

Q: How do the self‑certification tests work?
A: The tests are designed to run independently of any NGINX Plus configuration already installed on the system and loaded into memory. Rather than pull existing configuration from files like /etc/nginx/nginx.conf and the *.conf files in /etc/nginx/conf.d/, each prove Perl script generates a unique and localized NGINX Plus configuration, writes it to a temporary location (typically /tmp/nginx-tests-UUID), and loads it into the instance of NGINX Plus used for the test. Because the NGINX test suite ignores all of the normal, running configuration, you need to pass module loading and configuration directives to the prove tests with the TEST_NGINX_GLOBAL and TEST_NGINX_GLOBAL_HTTP environment variables. For further details, see Step 5 in Self‑Certifying the Module with the NGINX Test Suite.

Q: Do the self‑certification or NGINX Plus tests validate module features?
A: No. They verify that the module does not negatively affect the regular and expected operating behavior of NGINX and NGINX Plus. As detailed in the previous answer, each prove test loads the module into an NGINX Plus instance that is using a custom configuration designed to exercise particular functionality common to NGINX and NGINX Plus. For example, the h2* tests load your module and attempt to terminate and manipulate HTTP/2 traffic to confirm that your module doesn’t impact that functionality, even if your module does not rely on HTTP/2 in any way.

Q: What if my module has additional dependencies, such as creating outbound connections?
A: Generally speaking the tests do not work well with modules that create secondary actions, such as opening outbound ports to pass traffic to an off‑box tool or solution and expecting a response from that process. For example, if your module passes authentication credentials to an off‑box authentication server and doesn’t forward traffic until each session is authenticated, the test suite will most likely fail. But there’s really no need to enable authentication checking during the tests, because the feature functionality of your module is not being tested in any case.

In this case it’s highly advisable to create a disable command for the module so that it can be loaded into memory but does not function or actually send authentication data off‑box. As an example, in Step 5 of Self‑Certifying the Module with the NGINX Test Suite, we use the NGINX_TEST_GLOBAL_HTTP environment variable to pass the hello_world_enable off directive into the test suite.

Appendix: Perl Module Dependencies for the Self‑Certification Tests

Below is a list of Perl modules used by the self‑certification prove tests. Many of them are not included in prebuilt packages from OS vendors, and might themselves have additional dependencies. The list is not necessarily exhaustive, but includes the modules that don’t usually come standard in OS distributions.

On Ubuntu and Debian systems, the usual practice is to use package management tools like apt to install Perl modules from repositories, where they are named as in the following list. Below the list is the appropriate apt-get command for use on these systems.

More generally, the usual practice is to install Perl modules from CPAN, which uses more conventional naming conventions for Perl modules. For example, libio-socket-ssl-perl in this list corresponds to IO::Socket::SSL on CPAN.

libapparmor-perl
libcache-memcached-fast-perl
libcache-memcached-perl
libcgi-compress-gzip-perl
libcgi-fast-perl
libcgi-pm-perl
libencode-locale-perl
liberror-perl
libfcgi-perl
libhtml-parser-perl
libhtml-tagset-perl
libhttp-date-perl
libhttp-message-perl
libio-html-perl
libio-socket-ip-perl
libio-socket-ssl-perl
liblocale-gettext-perl
liblwp-mediatypes-perl
libnet-libidn-perl
libnet-ssleay-perl
libpcre3
libpcre3-dev
libperl5.22
libstring-crc32-perl
libtext-charwidth-perl
libtext-iconv-perl
libtext-wrapi18n-perl
libtimedate-perl
liburi-perl
zlib1g
zlib1g-dev

Ubuntu/Debian apt-get Installation Command

$ sudo apt-get install libapparmor-perl libcache-memcached-fast-perl libcache-memcached-perl libcgi-compress-gzip-perl libcgi-fast-perl libcgi-pm-perl libencode-locale-perl liberror-perl libfcgi-perl libhtml-parser-perl libhtml-tagset-perl libhttp-date-perl libhttp-message-perl libio-html-perl libio-socket-ip-perl libio-socket-ssl-perl liblocale-gettext-perl liblwp-mediatypes-perl libnet-libidn-perl libnet-ssleay-perl libpcre3 libpcre3-dev libperl5.22 libstring-crc32-perl libtext-charwidth-perl libtext-iconv-perl libtext-wrapi18n-perl libtimedate-perl liburi-perl zlib1g zlib1g-dev

For additional information on the NGINX test suite and variables available for prove testing, see the nginx-tests README.

Revision History

  • Version 3 (August 2017) – Addition of nonblocking recommendation to design requirements
  • Version 2 (May 2017) – Clarification of design requirements
  • Version 1 (April 2017) – Initial version (NGINX Plus R12, NGINX 1.11.10)

Get Started

Rocketship

Try Out NGINX Plus on Your Turf

Get Started
head with a headset

Ask Us a Question

Contact Sales