Skip to main content
Version: v1.0

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.


Install script#

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 !

Upgrade script#


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

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#


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


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


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