1. Home
  2. Guides
  3. Next-Gen WAF
  4. Setup and configuration
  5. Module-agent deployment
  6. NGINX module

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.

HINT: 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 the availability of the Lua module varies between distributions and vendors, we recommend using OpenResty or using a distribution and third-party repository that provides the appropriate Lua dependencies and modules.
  • OpenResty's Lua module requires resty.core. Certain NGINX package maintainers do not provide 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).

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.

Alpine Linux

Add the version of the Alpine Linux package repository that you want to use.

  1. Alpine Linux 3.23
$ echo '[sigsci_release]
name=sigsci_release
baseurl=https://apk.security.fastly.com/release/amazon/2023/noarch
gpgcheck=1
repo_gpgcheck=1
enabled=1
gpgkey=https://yum.security.fastly.com/release/gpgkey https://dl.security.fastly.com/sigsci-agent/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt' | sudo tee /etc/yum.repos.d/sigsci.repo

Amazon Linux

Add the version of the Amazon Linux package repository that you want to use.

NOTE: Following these instructions will configure your package manager to pull from https://yum.security.fastly.com. You can find the same package repositories at https://yum.signalsciences.net. To configure your package manager to pull from https://yum.signalsciences.net, replace all instances of security.fastly.com with signalsciences.net in the relevant code sample.

  1. Amazon Linux 2023
  2. Amazon Linux 2
$ echo '[sigsci_release]
name=sigsci_release
baseurl=https://yum.security.fastly.com/release/amazon/2023/noarch
gpgcheck=1
repo_gpgcheck=1
enabled=1
gpgkey=https://yum.security.fastly.com/release/gpgkey https://dl.security.fastly.com/sigsci-agent/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt' | sudo tee /etc/yum.repos.d/sigsci.repo

Debian

Add the version of the Debian package repository that you want to use.

NOTE: Following these instructions will configure your package manager to pull from https://apt.security.fastly.com. You can find the same package repositories at https://apt.signalsciences.net. To configure your package manager to pull from https://apt.signalsciences.net, replace all instances of security.fastly.com with signalsciences.net in the relevant code sample.

  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.security.fastly.com/release/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/sigsci.gpg
$ sudo echo "deb [signed-by=/usr/share/keyrings/sigsci.gpg] https://apt.security.fastly.com/release/debian/ `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/sigsci-release.list
$ sudo apt-get update

RHEL and derivatives

The following commands apply to Red Hat Enterprise Linux (RHEL) and its derivatives (e.g., CentOS). Tab names refer to the base RHEL source version.

NOTE: Following these instructions will configure your package manager to pull from https://yum.security.fastly.com. You can find the same package repositories at https://yum.signalsciences.net. To configure your package manager to pull from https://yum.signalsciences.net, replace all instances of security.fastly.com with signalsciences.net in the relevant code sample.

  1. RHEL 10
  2. RHEL 9
  3. RHEL 8
  4. RHEL 7
$ sudo tee /etc/yum.repos.d/sigsci.repo <<-'EOF'
[sigsci_release]
name=sigsci_release
baseurl=https://yum.security.fastly.com/release/el/$releasever/noarch
repo_gpgcheck=1
gpgcheck=1
enabled=1
gpgkey=https://yum.security.fastly.com/release/gpgkey https://dl.security.fastly.com/sigsci-agent/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
EOF

Ubuntu

Add the version of the Ubuntu package repository that you want to use.

NOTE: Following these instructions will configure your package manager to pull from https://apt.security.fastly.com. You can find the same package repositories at https://apt.signalsciences.net. To configure your package manager to pull from https://apt.signalsciences.net, replace all instances of security.fastly.com with signalsciences.net in the relevant code sample.

  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.security.fastly.com/release/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/sigsci.gpg
$ sudo echo "deb [signed-by=/usr/share/keyrings/sigsci.gpg] https://apt.security.fastly.com/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 relevant NGINX server 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.

HINT: 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.

Related content

Fastly
© Fastly 2026