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.

TIP

If Lua support is not one of your hosting environment requirements, we recommend installing the NGINX dynamic module instead of the NGINX Lua module. The NGINX dynamic module has fewer dependencies.

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

  1. Amazon Linux 2023 (AL2023)
  2. Amazon Linux 2 (AL2)
  3. Amazon Linux 2018.03
$ 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

  1. Bullseye (11) and above
  2. Buster (10) and below
$ 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. RHEL 9
  2. RHEL 8
  3. RHEL 7
  4. RHEL 6
1$ sudo tee /etc/yum.repos.d/sigsci.repo <<-'EOF'
2[sigsci_release]
3name=sigsci_release
4baseurl=https://yum.signalsciences.net/release/el/$releasever/$basearch
5repo_gpgcheck=1
6gpgcheck=1
7enabled=1
8gpgkey=https://yum.signalsciences.net/release/gpgkey https://dl.signalsciences.net/sigsci-agent/gpg.key
9sslverify=1
10sslcacert=/etc/pki/tls/certs/ca-bundle.crt
11EOF

Ubuntu

  1. Releases 22.04+
  2. Releases 20.04 and below
$ 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.

NOTE

If you don't use the sigsci.conf configuration file, you will need to review your Lua module when the NGINX Lua module is upgraded because your configuration file won't get updated.

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.

Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.