Here is the list of "official" plugins that we maintain (see thebunkerweb-plugins repository for more information) :

How to use a plugin

Automatic

If you want to quickly install external plugins, you can use theEXTERNAL_PLUGIN_URLS setting. It takes a list of URLs separated by spaces, each pointing to a compressed (zip format) archive containing one or more plugins.

You can use the following value if you want to automatically install the official plugins :EXTERNAL_PLUGIN_URLS=https://github.com/bunkerity/bunkerweb-plugins/archive/refs/tags/v1.9.zip

Manual

The first step is to install the plugin by placing its files inside the correspondingplugins data folder. The procedure depends on your integration :

mkdir-p./bw-data/plugins

gitclonehttps://github.com/bunkerity/bunkerweb-plugins&&\cp-rp./bunkerweb-plugins/*./bw-data/plugins

mkdirbw-data&&\chownroot:101bw-data&&\chmod770bw-data

chown-Rroot:101bw-data&&\chmod-R770bw-data

grep^$(whoami):/etc/subuid&&\grep^$(whoami):/etc/subgid

mkdirbw-data&&\sudochgrp100100bw-data&&\chmod770bw-data

sudochgrp-R100100bw-data&&\chmod-R770bw-data

services:...bw-scheduler:image:bunkerity/bunkerweb-scheduler:1.6.5volumes:-./bw-data:/data...

mkdir-p./bw-data/plugins

gitclonehttps://github.com/bunkerity/bunkerweb-plugins&&\cp-rp./bunkerweb-plugins/*./bw-data/plugins

chown-R101:101./bw-data

services:...bw-scheduler:image:bunkerity/bunkerweb-scheduler:1.6.5volumes:-./bw-data:/data...

mkdir-p/shared/bw-plugins

gitclonehttps://github.com/bunkerity/bunkerweb-plugins&&\cp-rp./bunkerweb-plugins/*/shared/bw-plugins

chown-R101:101/shared/bw-plugins

services:...bw-scheduler:image:bunkerity/bunkerweb-scheduler:1.6.5volumes:-/shared/bw-plugins:/data/plugins...

apiVersion:v1kind:PersistentVolumeClaimmetadata:name:pvc-bunkerweb-pluginsspec:accessModes:-ReadWriteOnceresources:requests:storage:5Gi

apiVersion:apps/v1kind:Deploymentmetadata:name:bunkerweb-schedulerspec:replicas:1strategy:type:Recreateselector:matchLabels:app:bunkerweb-schedulertemplate:metadata:labels:app:bunkerweb-schedulerspec:serviceAccountName:sa-bunkerwebcontainers:-name:bunkerweb-schedulerimage:bunkerity/bunkerweb-scheduler:1.6.5imagePullPolicy:Alwaysenv:-name:KUBERNETES_MODEvalue:"yes"-name:"DATABASE_URI"value:"mariadb+pymysql://bunkerweb:changeme@svc-bunkerweb-db:3306/db"volumeMounts:-mountPath:"/data/plugins"name:vol-pluginsinitContainers:-name:bunkerweb-scheduler-initimage:alpine/gitcommand:["/bin/sh","-c"]args:["gitclonehttps://github.com/bunkerity/bunkerweb-plugins/data/plugins&&chown-R101:101/data/plugins"]volumeMounts:-mountPath:"/data/plugins"name:vol-pluginsvolumes:-name:vol-pluginspersistentVolumeClaim:claimName:pvc-bunkerweb-plugins

gitclonehttps://github.com/bunkerity/bunkerweb-plugins&&\cp-rp./bunkerweb-plugins/*/etc/bunkerweb/plugins&&\chown-Rnginx:nginx/etc/bunkerweb/plugins

Writing a plugin

Structure

What a plugin structure looks like:

plugin /    confs / conf_type / conf_name.conf    ui / actions.py         hooks.py         template.html         blueprints / <blueprint_file(s)>              templates / <blueprint_template(s)>    jobs / my-job.py    bwcli / my-command.py    templates / my-template.json          my-template / configs / conf_type / conf_name.conf    plugin.lua    plugin.json

• conf_name.conf : Addcustom NGINX configurations (as Jinja2 templates).

• actions.py : Script to execute on the Flask server. This script runs in a Flask context, giving you access to libraries and utilities likejinja2 andrequests.

• hooks.py : Custom Python file that contains flask's hooks and will be executed when the plugin is loaded.

• template.html : Custom plugin page accessed via the UI.

• blueprints folder (within ui): This folder is used to override existing Flask blueprints or create new ones. Inside, you can include blueprint files and an optionaltemplates subfolder for blueprint-specific templates.

• jobs py file : Custom Python files executed as jobs by the scheduler.

• bwcli folder : Python (or executable) files that extend thebwcli CLI through custom commands.

• my-template.json : Addcustom templates to override the default values of settings and apply custom configurations easily.

• plugin.lua : Code executed on NGINX using theNGINX LUA module.

• plugin.json : Metadata, settings, and job definitions for your plugin.

Getting started

The first step is to create a folder that will contain the plugin :

mkdirmyplugin&&\cdmyplugin

Metadata

A file namedplugin.json and written at the root of the plugin folder must contain metadata about the plugin. Here is an example :

{"id":"myplugin","name":"My Plugin","description":"Just an example plugin.","version":"1.0","stream":"partial","settings":{"DUMMY_SETTING":{"context":"multisite","default":"1234","help":"Here is the help of the setting.","id":"dummy-id","label":"Dummy setting","regex":"^.*$","type":"text"}},"jobs":[{"name":"my-job","file":"my-job.py","every":"hour"}]}

Here are the details of the fields :

Each setting has the following fields (the key is the ID of the settings used in a configuration) :

Each job has the following fields :

CLI commands

Plugins can extend thebwcli tool with custom commands that run underbwcli plugin <plugin_id> ...:

1. Add abwcli directory in your plugin and drop one file per command (for examplebwcli/list.py). The CLI adds the plugin path tosys.path before executing the file.
2. Declare the commands in the optionalbwcli section ofplugin.json, mapping each command name to its executable file name.

{"bwcli":{"list":"list.py","save":"save.py"}}

The scheduler automatically exposes the declared commands once the plugin is installed. Core plugins, such asbackup insrc/common/core/backup, follow the same pattern.

Configurations

You can add custom NGINX configurations by adding a folder namedconfs with content similar to thecustom configurations. Each subfolder inside theconfs will containjinja2 templates that will be generated and loaded at the corresponding context (http,server-http,default-server-http,stream,server-stream,modsec,modsec-crs,crs-plugins-before andcrs-plugins-after).

Here is an example for a configuration template file inside theconfs/server-http folder namedexample.conf :

location/setting{default_type'text/plain';content_by_lua_block{ngx.say('{{DUMMY_SETTING}}')}}

{{ DUMMY_SETTING }} will be replaced by the value of theDUMMY_SETTING chosen by the user of the plugin.

Templates

Check thetemplates documentation for more information.

LUA

Main script

Under the hood, BunkerWeb is using theNGINX LUA module to execute code within NGINX. Plugins that need to execute code must provide a lua file at the root directory of the plugin folder using theid value ofplugin.json as its name. Here is an example namedmyplugin.lua :

localclass=require"middleclass"localplugin=require"bunkerweb.plugin"localutils=require"bunkerweb.utils"localmyplugin=class("myplugin",plugin)functionmyplugin:initialize(ctx)plugin.initialize(self,"myplugin",ctx)self.dummy="dummy"endfunctionmyplugin:init()self.logger:log(ngx.NOTICE,"init called")returnself:ret(true,"success")endfunctionmyplugin:set()self.logger:log(ngx.NOTICE,"set called")returnself:ret(true,"success")endfunctionmyplugin:access()self.logger:log(ngx.NOTICE,"access called")returnself:ret(true,"success")endfunctionmyplugin:log()self.logger:log(ngx.NOTICE,"log called")returnself:ret(true,"success")endfunctionmyplugin:log_default()self.logger:log(ngx.NOTICE,"log_default called")returnself:ret(true,"success")endfunctionmyplugin:preread()self.logger:log(ngx.NOTICE,"preread called")returnself:ret(true,"success")endfunctionmyplugin:log_stream()self.logger:log(ngx.NOTICE,"log_stream called")returnself:ret(true,"success")endreturnmyplugin

The declared functions are automatically called during specific contexts. Here are the details of each function :

Libraries

All directives fromNGINX LUA module and are available andNGINX stream LUA module. On top of that, you can use the LUA libraries included within BunkerWeb : seethis script for the complete list.

If you need additional libraries, you can put them in the root folder of the plugin and access them by prefixing them with your plugin ID. Here is an example file namedmylibrary.lua :

local_M={}_M.dummy=function()return"dummy"endreturn_M

And here is how you can use it from themyplugin.lua file :

localmylibrary=require"myplugin.mylibrary"...mylibrary.dummy()...

Helpers

Some helpers modules provide common helpful helpers :

• self.variables : allows to access and store plugins' attributes
• self.logger : print logs
• bunkerweb.utils : various useful functions
• bunkerweb.datastore : access the global shared data on one instance (key/value store)
• bunkerweb.clusterstore : access a Redis data store shared between BunkerWeb instances (key/value store)

To access the functions, you first need torequire the modules :

localutils=require"bunkerweb.utils"localdatastore=require"bunkerweb.datastore"localclustestore=require"bunkerweb.clustertore"

Retrieve a setting value :

localmyvar=self.variables["DUMMY_SETTING"]ifnotmyvarthenself.logger:log(ngx.ERR,"can't retrieve setting DUMMY_SETTING")elseself.logger:log(ngx.NOTICE,"DUMMY_SETTING = "..value)end

Store something in the local cache :

localok,err=self.datastore:set("plugin_myplugin_something","somevalue")ifnotokthenself.logger:log(ngx.ERR,"can't save plugin_myplugin_something into datastore : "..err)elseself.logger:log(ngx.NOTICE,"successfully saved plugin_myplugin_something into datastore")end

Check if an IP address is global :

localret,err=utils.ip_is_global(ngx.ctx.bw.remote_addr)ifret==nilthenself.logger:log(ngx.ERR,"error while checking if IP "..ngx.ctx.bw.remote_addr.." is global or not : "..err)elseifnotretthenself.logger:log(ngx.NOTICE,"IP "..ngx.ctx.bw.remote_addr.." is not global")elseself.logger:log(ngx.NOTICE,"IP "..ngx.ctx.bw.remote_addr.." is global")end

Jobs

BunkerWeb uses an internal job scheduler for periodic tasks like renewing certificates with certbot, downloading blacklists, downloading MMDB files, ... You can add tasks of your choice by putting them inside a subfolder namedjobs and listing them in theplugin.json metadata file. Don't forget to add the execution permissions for everyone to avoid any problems when a user is cloning and installing your plugin.

Plugin page

Everything related to the web UI is located inside the subfolderui as we seen in theprevious structure section..

Prerequisites

When you want to create a plugin page, you need two files :

• template.html that will be accessible with aGET /plugins/<plugin_id>.

• actions.py where you can add some scripting and logic with aPOST /plugins/<plugin_id>. Notice that this fileneed a function with the same name as the plugin to work. This file is needed even if the function is empty.

Basic example

We can put aside theactions.py file and startonly using the template on a GET situation. The template can access app context and libs, so you can use Jinja, request or flask utils.

For example, you can get the request arguments in your template like this :

<p>request args : {{ request.args.get() }}.</p>

Actions.py

<inputtype="hidden"name="csrf_token"value="{{ csrf_token() }}"/>

You can power-up your plugin page with additional scripting with theactions.py file when sending aPOST /plugins/<plugin_id>.

You have two functions by default inactions.py :

pre_render function

This allows you to retrieve data when youGET the template, and to use the data with the pre_render variable available in Jinja to display content more dynamically.

defpre_render(**kwargs)return<pre_render_data>

BunkerWeb will send you this type of response :

returnjsonify({"status":"ok|ko","code":XXX,"data":<pre_render_data>}),200

<plugin_id> function

This allows you to retrieve data when you make aPOST from the template endpoint, which must be used in AJAX.

defmyplugin(**kwargs)return<plugin_id_data>

BunkerWeb will send you this type of response :

returnjsonify({"message":"ok","data":<plugin_id_data>}),200

What you can access from action.py

Here are the arguments that are passed and access on action.py functions:

function(app=app,args=request.args.to_dict()orrequest.jsonorNone)

fromflaskimportrequestimportbcrypt

Some examples

• Retrieve form submitted data

fromflaskimportrequestdefmyplugin(**kwargs):my_form_value=request.form["my_form_input"]returnmy_form_value

• Access app config

action.py

fromflaskimportrequestdefpre_render(**kwargs):config=kwargs['app'].config["CONFIG"].get_config(methods=False)returnconfig

template

<!-- metadata + config --><div>{{ pre_render }}</div>

Hooks.py

This documentation outlines the lifecycle hooks used for managing different stages of a request within the application. Each hook is associated with a specific phase.

fromflaskimportrequest,Responsedefbefore_request():print("Before-request: Validating request...",flush=True)# Perform authentication, validation, or logging hereifnotis_valid_request(request):# We are in the app contextreturnResponse("Invalid request!",status=400)defis_valid_request(request):# Dummy validation logicreturn"user"inrequest

fromflaskimportrequestdefafter_request(response):print("After-request: Logging response...",flush=True)# Perform logging, cleanup, or response modifications herelog_response(response)returnresponsedeflog_response(response):# Dummy logging logicprint("Response logged:",response,flush=True)

defteardown_request(error=None):print("Teardown-request: Cleaning up resources...",flush=True)# Perform cleanup, release resources, or handle errors hereiferror:handle_error(error)cleanup_resources()defhandle_error(error):# Dummy error handling logicprint("Error encountered:",error,flush=True)defcleanup_resources():# Dummy resource cleanup logicprint("Resources have been cleaned up.",flush=True)

defcontext_processor()->dict:print("Context-processor: Injecting context data...",flush=True)# Return a dictionary containing context data for templates/viewsreturn{"current_user":"John Doe","app_version":"1.0.0","feature_flags":{"new_ui":True}}

This lifecycle hook design provides a modular and systematic approach to managing various aspects of a request's lifecycle:

• Modularity: Each hook is responsible for a distinct phase, ensuring that concerns are separated.
• Maintainability: Developers can easily add, modify, or remove hook implementations without impacting other parts of the request lifecycle.
• Extensibility: The framework is flexible, allowing for additional hooks or enhancements as application requirements evolve.

By clearly defining the responsibilities of each hook and their associated logging prefixes, the system ensures that each stage of request processing is transparent and manageable.

Blueprints

In Flask,blueprints serve as a modular way to organize related components—such as views, templates, and static files—within your application. They allow you to group functionality logically and can be used to create new sections of your app or override existing ones.

Creating a Blueprint

To define a blueprint, you create an instance of theBlueprint class, specifying its name and import path. You then define routes and views associated with this blueprint.

Example: Defining a New Blueprint

fromos.pathimportdirnamefromflaskimportBlueprint,render_template# Define the blueprintmy_blueprint=Blueprint('my_blueprint',__name__,template_folder=dirname(__file__)+'/templates')# The template_folder is set to avoid conflicts with the original blueprint# Define a route within the blueprint@my_blueprint.route('/my_blueprint')defmy_blueprint_page():returnrender_template('my_blueprint.html')

In this example, a blueprint namedmy_blueprint is created, and a route/my_blueprint is defined within it.

Overriding an Existing Blueprint

Blueprints can also override existing ones to modify or extend functionality. To do this, ensure that the new blueprint has the same name as the one you're overriding and register it after the original.

Example: Overriding an Existing Blueprint

fromos.pathimportdirnamefromflaskimportFlask,Blueprint# Original blueprintinstances=Blueprint('instances',__name__,template_folder=dirname(__file__)+'/templates')# The template_folder is set to avoid conflicts with the original blueprint@instances.route('/instances')defoverride_instances():return"My new instances page"

In this scenario, accessing the URL/instances will display "My new instances page" because theinstances blueprint, registered last, overrides the originalinstances blueprint.

Naming Conventions

For consistency and clarity, it's advisable to follow these naming conventions:

• Blueprint Names: Use short, all-lowercase names. Underscores can be used for readability, e.g.,user_auth.

• File Names: Match the filename to the blueprint name, ensuring it's all lowercase with underscores as needed, e.g.,user_auth.py.

This practice aligns with Python's module naming conventions and helps maintain a clear project structure.

Example: Blueprint and File Naming

plugin /    ui / blueprints / user_auth.py                      templates / user_auth.html

In this structure,user_auth.py contains theuser_auth blueprint, anduser_auth.html is the associated template, adhering to the recommended naming conventions.