Skip to main content
Version: v1.2.2

OpenResty Bouncer

CrowdSec

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

A lua bouncer for OpenResty.

How does it work ?#

This bouncer leverages OpenResty 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.

Installation#

Before installation

openresty bouncer depends on openresty, openresty-opm, gettext-base. it has been tested only on debian/ubuntu based distributions. You can install openresty and openresty-opm from openresty linux packages.

Using packages#

Setup crowdsec repositories.

sudo apt install crowdsec-openresty-bouncer

Manual installation#

Download the latest release here

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

If you are on a mono-machine setup, the crowdsec-openresty-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
  • openresty-opm : OpenResty Package Manager
  • pintsized/lua-resty-http : lua lib managed by openresty-opm

From source#

Requirements#

Debian/Ubuntu#
sudo apt-get install gettext-base build-essential

Build the package :

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

Build package#

cd crowdsec-openresty-bouncer/make release

Installation#

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

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

Otherwise, configure your API url and key in /etc/crowdsec/bouncers/crowdsec-openresty-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=1000BOUNCING_ON_TYPE=banREQUEST_TIMEOUT=0.2

You can now restart your openresty server:

systemctl restart openresty

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-openresty-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=1000BOUNCING_ON_TYPE=banREQUEST_TIMEOUT=0.2

How it works#

  • deploys /usr/local/openresty/nginx/conf/conf.d/crowdsec_openresty.conf with access_by_lua directive
  • deploys /usr/local/openresty/lualib/plugins/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.