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.
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.
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.
This section is a detailed walk‑through of the stages in the NGINX Plus Certified Module Program, including requirements and procedures.
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:
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.
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.
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:
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.
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.
To assist the partner in promoting the module, NGINX, Inc. in addition provides:
This section provides more detailed information about the phases in Module Certification Process, including step‑by‑step instructions.
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.
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.
hello_world_conf /etc/nginx/hello_world.conf;
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.
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;
}
}
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.
We highly recommend that the modules you distribute have descriptive .so filenames that include:
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
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.
$ wget http://nginx.org/download/nginx-version.tar.gz
$ tar -xzvf nginx-version.tar.gz
$ cd nginx-version
$ ./configure --with-compat --add-dynamic-module=../ngx_acme_http_hello_world_module
$ make modules
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.
$ wget http://hg.nginx.org/nginx-tests/archive/tip.tar.gz
$ tar zxvf tip.tar.gz
$ sudo service nginx stop
$ cd nginx-tests-d12c45f14102
$ sudo -u nginx TEST_NGINX_BINARY=/usr/sbin/nginx prove -Q .
skipped: [Perl::Module] not installed
$ 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 .
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
$ 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:
$ 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
$ 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
$ sudo apt install nginx-plus-dbg
$ 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
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.:
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
By distributing the module directly to customers, the partner:
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.
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.
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
$ 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.