Skip to main content
Version: v1.2

Nginx Bouncer

CrowdSec

๐Ÿ“š Documentation๐Ÿ’  Hub๐Ÿ’ฌ Discourse

A lua bouncer for nginx.

How does it work ?#

This bouncer leverages nginx lua's API, namely access_by_lua_file.

New/unknown IP are checked against crowdsec API, and if request should be blocked, a 403 is returned to the user, and put in cache.

At the back, this bouncer uses crowdsec lua lib.

Installation

Using packages#

Setup crowdsec repositories.

sudo apt install crowdsec-nginx-bouncer

Manual installation#

warning

nginx bouncer depends on nginx, libnginx-mod-http-lua, lua-logging, lua, lua-sec. it has been tested only on debian/ubuntu based distributions.

Download the latest release here

tar xvzf crowdsec-nginx-bouncer.tgzcd crowdsec-nginx-bouncer-v*/sudo ./install.sh

If you are on a mono-machine setup, the crowdsec-nginx-bouncer install script will register directly to the local crowdsec, so you're good to go !

Upgrade script#

Upgrade#

If you already have crowdsec-nginx-bouncer installed, please download the latest release and run the following commands:

tar xzvf crowdsec-nginx-bouncer.tgzcd crowdsec-nginx-bouncer-v*/sudo ./upgrade.shsudo systemctl restart nginx

Configuration#

If your nginx bouncer needs to communicate with a remote crowdsec API, you can configure API url and key in /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf:

API_URL=http://127.0.0.1:8080API_KEY=<API KEY> --generated with `cscli bouncers add -n <bouncer_name>LOG_FILE=/tmp/lua_mod.logCACHE_EXPIRATION=1CACHE_SIZE=1000

Then restart nginx:

Restart Nginx
sudo systemctl restart nginx

โš ๏ธ the installation script will take care of dependencies for Debian/Ubuntu

non-debian based dependencies
  • libnginx-mod-http-lua : nginx lua support
  • lua-sec : for https client request

From source#

Requirements#

The following packages are required :

  • lua
  • lua-sec
  • libnginx-mod-http-lua

Debian/Ubuntu#

sudo apt-get install lua5.3 libnginx-mod-http-lua lua-sec

Download the following 2 repositories:

git clone https://github.com/crowdsecurity/lua-cs-bouncer.git
git clone https://github.com/crowdsecurity/cs-nginx-bouncer.git

Installation#

lua-cs-bouncer#

cd ./lua-cs-bouncer/sudo make install

crowdsec-nginx-bouncer#

  • Copy the crowdsec-nginx-bouncer/nginx/crowdsec_nginx.conf into /etc/nginx/conf.d/crowdsec_nginx.conf:
cp ./crowdsec-nginx-bouncer/nginx/crowdsec_nginx.conf /etc/nginx/conf.d/crowdsec_nginx.conf
  • Copy the crowdsec-nginx-bouncer/nginx/access.lua into /usr/local/lua/crowdec/access.lua:
cp ./crowdsec-nginx-bouncer/nginx/access.lua /usr/local/lua/crowdec/access.lua

Configure your API url and key in /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf:

API_URL=http://127.0.0.1:8080API_KEY=<API KEY> --generated with `cscli bouncers add -n <bouncer_name>LOG_FILE=/tmp/lua_mod.logCACHE_EXPIRATION=1CACHE_SIZE=1000

You can now restart your nginx server:

systemctl restart nginx

Configuration

The configuration file loaded by nginx is /etc/nginx/conf.d/crowdsec_nginx.conf, but you shouldn't have to edit it, the relevant configuration file being /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf :

API_URL=http://localhost:8080                 <-- the API urlAPI_KEY=                                      <-- the API Key generated with `cscli bouncers add -n <bouncer_name>` LOG_FILE=/tmp/lua_mod.log                     <-- path to log fileCACHE_EXPIRATION=1                            <-- in seconds : how often is the yes/no decisions for an IP refreshedCACHE_SIZE=1000                               <-- cache size : how many simulatenous entries are kept in 

How it works

  • deploys /etc/nginx/conf.d/crowdsec_nginx.conf with access_by_lua directive
  • deploys /usr/local/lua/crowdsec/access.lua with the lua code checking incoming IPs against crowdsec API

Testing

When your IP is blocked, any request should lead to a 403 http response.