Installing the NGINX Lua module

The NGINX Lua module leverages OpenResty's Lua module for NGINX (often referred to as ngx_http_lua_module), which allows for embedded Lua code directly in your NGINX configuration. This module is written in the Lua scripting language and can be integrated with NGINX Open Source, NGINX Plus, and OpenResty.

Prerequisites

Before installing our NGINX Lua Module, your NGINX installation must be compiled with Lua support or be loaded via the OpenResty Lua module. When determining how to add Lua, keep the following things in mind:

• Since availability around the Lua module varies between distributions and vendors, we recommended using OpenResty or using a distribution and third-party repository that provides the appropriate Lua dependencies and modules.
• As of May 2019, OpenResty's Lua module requires resty.core. Due to this change, certain NGINX package maintainers stopped providing Lua packages for NGINX (e.g., Ubuntu 22.04 and above) and certain packages may no longer include Lua (e.g., nginx-full or nginx-extras).
• After September 2019, we stopped releasing new versions of our Lua module (nginx-module-lua). Existing installations that depend on this module are supported until the module reaches its end of life.

Once you've added Lua, check that it is loaded correctly.

Adding our package repositories

After completing the prerequisites, configure your package management system to pull from our repositories.

Amazon Linux

$ echo '[sigsci_release]
name=sigsci_release
baseurl=https://yum.signalsciences.net/release/el/$releasever/$basearch
gpgcheck=1
repo_gpgcheck=1
enabled=1
gpgkey=https://yum.signalsciences.net/release/gpgkey https://dl.signalsciences.net/sigsci-agent/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt' | sudo tee /etc/yum.repos.d/sigsci.repo

Debian

$ sudo apt-get update
$ sudo apt-get install -y apt-transport-https wget gnupg lsb-release
$ sudo wget -qO - https://apt.signalsciences.net/release/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/sigsci.gpg
$ sudo echo "deb [signed-by=/usr/share/keyrings/sigsci.gpg] https://apt.signalsciences.net/release/debian/ `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/sigsci-release.list
$ sudo apt-get update

RHEL and derivatives

This refers to Red Hat Enterprise Linux (RHEL) and its derivatives such as CentOS. Tab names refer to the base RHEL source version.

1
2
3
4
5
6
7
8
9
10
11

$ sudo tee /etc/yum.repos.d/sigsci.repo <<-'EOF'
[sigsci_release]
name=sigsci_release
baseurl=https://yum.signalsciences.net/release/el/$releasever/$basearch
repo_gpgcheck=1
gpgcheck=1
enabled=1
gpgkey=https://yum.signalsciences.net/release/gpgkey https://dl.signalsciences.net/sigsci-agent/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
EOF

Ubuntu

$ sudo apt-get update
$ sudo apt-get install -y apt-transport-https wget gnupg lsb-release
$ wget -qO - https://apt.signalsciences.net/release/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/sigsci.gpg
$ sudo echo "deb [signed-by=/usr/share/keyrings/sigsci.gpg] https://apt.signalsciences.net/release/ubuntu/ `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/sigsci-release.list
$ sudo apt-get update

Installing the NGINX Lua module

Once you've configured your package management system to pull from our repositories, install the NGINX Lua module:

1. Install the appropriate module package for your distribution:

   1. Debian / Ubuntu
   2. RHEL / Centos / Amazon

   $ sudo apt install sigsci-module-nginx

2. Add the following line to your NGINX configuration file (located by default at /etc/nginx/nginx.conf) in the http context:

   include "/opt/sigsci/nginx/sigsci.conf";

3. Restart the NGINX service to initialize the new module:

   • systemd based systems:

     $ sudo systemctl restart nginx

   • upstart based systems:

     $ sudo restart nginx

   • no init system or service file:

     $ sudo nginx -s reload

Checking that Lua is loaded correctly

After installing the NGINX Lua module, verify that Lua is working and that the NGINX Lua module is running correctly:

1. Run the following script to add the following file to the installation directly:

   cat <<'EOF' >/opt/sigsci/nginx/sigsci_check_lua.conf
   # If you installed Lua as a dynamic module, uncomment the following load_module directives. This is not required if using openresty.
   # load_module modules/ndk_http_module.so;
   # load_module modules/ngx_http_lua_module.so;
   
   events {
      worker_connections 768;
      # multi_accept on;
   }
   
   http {
   init_by_lua '
   local m = {}
   local ngx_lua_version = "dev"
   
   if ngx then
   -- if not in testing environment
   ngx_lua_version = tostring(ngx.config.ngx_lua_version)
   ngx.log(ngx.STDERR, "INFO:", " Check for jit: lua version: ", ngx_lua_version)
   end
   
   local r, jit = pcall(require, "jit")
   if not r then
   error("ERROR: No lua jit support: No support for NGWAF Lua module")
   else
   
   if jit then
      m._SERVER_FLAVOR = ngx_lua_version .. ", lua=" .. jit.version
      if os.getenv("SIGSCI_NGINX_DISABLE_JIT") == "true" then
         nginx.log(ngx.STDERR, "WARNING:", "Disabling lua jit because env var: SIGSCI_NGINX_DISABLE_JIT=", "true")
      end
      ngx.log(ngx.STDERR, "INFO:", " Bravo! You have lua jit support=", m._SERVER_FLAVOR)
   else
      error("ERROR: No luajit support: No support for NGWAF module")
   end
   end
   ';
   }
   EOF

2. Run the following command to test if Lua is loaded correctly:

   $ nginx -t -c /opt/sigsci/nginx/sigsci_check_lua.conf

   The output will look something like this:

   nginx: [] [lua] init_by_lua:9: INFO: Check for jit: lua version: 10000
   nginx: [] [lua] init_by_lua:22: INFO: Bravo! You have lua jit support=10000, lua=LuaJIT 2.0.4
   nginx: the configuration file <your explicit path>/sigsci_check_lua.conf syntax is ok
   nginx: configuration file <your explicit path>/sigsci_check_lua.conf test is successful

Working with multiple Lua scripts in NGINX

NGINX supports one init_by_lua or init_by_lua_file, which is used by the our NGINX Lua module. If you have your own Lua scripts embedded within NGINX, you will need to splice the NGINX Lua module into your custom Lua code.

To add the NGINX Lua module into your existing Lua code:

1. Remove all sigsci references from your NGINX configuration. References may look something like this:

   include /opt/sigsci/nginx/sigsci.conf;

2. Add the following lines to your NGINX configuration:

   lua_shared_dict sigsci_conf 12k;
   lua_use_default_type off;

3. Within your init_by_lua or the file specified by init_by_lua_file, include the following snippet:

   package.path = "/opt/sigsci/nginx/?.lua;" .. package.path
   sigsci = require("SignalSciences")

4. Add an access_by_lua and log_by_lua into your NGINX configuration. If you already have these directives defined, copy the sigsci.prerequest() and sigsci.postrequest() statements to their respective Lua callers.

   access_by_lua 'sigsci.prerequest()';
   log_by_lua    'sigsci.postrequest()';

5. Restart NGINX.