---
title: Installing the NGINX Lua module
summary: null
url: >-
  https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/nginx-module/installing-the-nginx-lua-module
---


The NGINX Lua module leverages [OpenResty's Lua module](https://github.com/openresty/lua-nginx-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](/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/nginx-module/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](https://github.com/openresty/lua-nginx-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](https://openresty.org/en/ann-1015008001.html), 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](#checking-that-lua-is-loaded-correctly) that it is loaded correctly.

## Adding our package repositories

After [completing the prerequisites](#prerequisites), configure your package management system to pull from our repositories.

### Amazon Linux

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

> **NOTE:** <Partial name='ngwaf-package-download-from-yum' inline />

<!-- TabbedPanels component: 
<Panel id="amazon-linux-2023" label="Amazon Linux 2023">

```term copy nolinenums
$ echo '[sigsci_release]
name=sigsci_release
baseurl=https://yum.security.fastly.com/release/amazon/2023/$basearch
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
```

</Panel>
<Panel id="amazon-linux-2" label="Amazon Linux 2">

NGINX versions `1.18.0` and above:
```term copy nolinenums
$ echo '[sigsci_release]
name=sigsci_release
baseurl=https://yum.security.fastly.com/release/amazon/2/$basearch
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
```

</Panel>
 -->

### Debian

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

> **NOTE:** <Partial name='ngwaf-package-download-from-apt' inline />

<!-- TabbedPanels component: 
<Panel id="bullseye-(11)-and-above" label="Bullseye (11) and above">

```term copy nolinenums
$ 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
```

</Panel>
<Panel id="buster-(10)-and-below" label="Buster (10) and below">

```term copy nolinenums
$ sudo apt-get update
$ sudo apt-get install -y apt-transport-https wget lsb-release
$ wget -qO - https://apt.security.fastly.com/release/gpgkey | sudo apt-key add -
$ sudo echo "deb 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
```

</Panel>
 -->

### 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:** <Partial name='ngwaf-package-download-from-yum' inline />

<!-- TabbedPanels component: 
<Panel id="rhel-9" label="RHEL 9">

```term copy nolines
$ sudo tee /etc/yum.repos.d/sigsci.repo <<-'EOF'
[sigsci_release]
name=sigsci_release
baseurl=https://yum.security.fastly.com/release/el/$releasever/$basearch
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
```

</Panel>
<Panel id="rhel-8" label="RHEL 8">

> **WARNING:** Red Hat's full support of RHEL 8 ended in May 2024. We recommend reviewing the [Red Hat Enterprise Linux Life Cycle](https://access.redhat.com/support/policy/updates/errata#Life_Cycle_Dates) before installing RHEL 8.

```term copy nolinenums
$ echo '[sigsci_release]
name=sigsci_release
baseurl=https://yum.security.fastly.com/release/el/$releasever/$basearch
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
```

</Panel>
<Panel id="rhel-7" label="RHEL 7">

> **WARNING:** Red Hat's full support of RHEL 7 ended in August 2019. We recommend reviewing the [Red Hat Enterprise Linux Life Cycle](https://access.redhat.com/support/policy/updates/errata#Life_Cycle_Dates) before installing RHEL 7.

```term copy nolinenums
$ echo '[sigsci_release]
name=sigsci_release
baseurl=https://yum.security.fastly.com/release/el/$releasever/$basearch
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
```

</Panel>
 -->

### Ubuntu

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

> **NOTE:** <Partial name='ngwaf-package-download-from-apt' inline />

<!-- TabbedPanels component: 
<Panel id="releases-22.04+" label="Releases 22.04+">

```term copy nolinenums
$ 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
```

</Panel>
<Panel id="releases-20.04-and-below" label="Releases 20.04 and below">

```term copy nolinenums
$ sudo apt-get update
$ sudo apt-get install -y apt-transport-https wget lsb-release
$ wget -qO - https://apt.security.fastly.com/release/gpgkey | sudo apt-key add -
$ sudo echo "deb 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
```

</Panel>
 -->

## Installing the NGINX Lua module

Once you've configured your package management system to [pull from our repositories](#adding-our-package-repositories), install the NGINX Lua module:

1. Install the appropriate module package for your distribution:

   <!-- TabbedPanels component: 
   <Panel id="debian-/-ubuntu" label="Debian / Ubuntu">

   ```term copy
   $ sudo apt install sigsci-module-nginx
   ```

   </Panel>
   <Panel id="rhel-/-centos-/-amazon" label="RHEL / CentOS / Amazon">

   ```term copy
   $ sudo yum install sigsci-module-nginx
   ```

   </Panel>
    -->

1. Add the following line to your NGINX configuration file (located by default at `/etc/nginx/nginx.conf`) in the relevant NGINX [`server`](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) context:

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

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

   * `systemd` based systems:

      ```term copy
      $ sudo systemctl restart nginx
      ```

   * `upstart` based systems:

      ```term copy
      $ sudo restart nginx
      ```
   * no `init` system or service file:

      ```term copy
      $ 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:

   ```bash copy nolinenums
   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

   ```

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

   ```term copy
   $ nginx -t -c /opt/sigsci/nginx/sigsci_check_lua.conf
   ```

   The output will look something like this:

   ```term nolinenums
   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;
   ```

1. Add the following lines to your NGINX configuration:

   ```
   lua_shared_dict sigsci_conf 12k;
   lua_use_default_type off;
   ```

1. 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")
   ```

1. 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()';
   ```

1. Restart NGINX.

## Related content

* [About module-agent deployment](/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/about-module-agent-deployment)
* [Using an API with the Next-Gen WAF](/guides/next-gen-waf/developer/using-an-api-with-the-next-gen-waf)