Skip to main content
Version: Next

Nginx Bouncer


๐Ÿ“š 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.


Using packages#

Setup crowdsec repositories.

sudo apt install crowdsec-nginx-bouncer

Manual installation#


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 ./

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 !

โš ๏ธ 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#


The following packages are required :

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

Download the following 2 repositories:

git clone
git clone


cd ./lua-cs-bouncer/sudo make install
  • 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=<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


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


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=<API KEY> --generated with `cscli bouncers add -n <bouncer_name>LOG_FILE=/tmp/lua_mod.logCACHE_EXPIRATION=1CACHE_SIZE=1000

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


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