If you have made a plugin and want it to be listed here, feel free to [create a pull request](https://github.com/bunkerity/bunkerized-nginx/pulls) and edit that section.
- Download the plugin into your local drive (e.g., git clone)
- Edit the settings inside the plugin.json files (e.g., myplugin/plugin.json)
- If you are using a container based integration, you need to mount it to the [plugins special folder](https://bunkerized-nginx.readthedocs.io/en/latest/special_folders.html#plugins) inside the container (e.g., /where/is/myplugin:/plugins/myplugin)
- If you are using Linux integration, copy the downloaded plugin folder to the [plugins special folder](https://bunkerized-nginx.readthedocs.io/en/latest/special_folders.html#plugins) (e.g., cp -r myplugin /plugins)
To check if the plugin is loaded you should see log entries like that :
```log
2021/06/05 09:19:47 [error] 104#104: [PLUGINS] *NOT AN ERROR* plugin MyPlugin/1.0 has been loaded
```
## Write a plugin
A plugin is composed of a plugin.json which contains metadata (e.g. : name, settings, ...) and a set of LUA files for the plugin code.
### plugin.json
```json
{
"id": "myplugin",
"name": "My Plugin",
"description": "Short description of my plugin.",
"version": "1.0",
"settings": {
"MY_SETTING": "value1",
"ANOTHER_SETTING": "value2",
}
}
```
The `id` value is really important because it must match the subfolder name inside the `plugins` volume. Choose one which isn't already used to avoid conflicts.
Settings names and default values can be choosen freely. There will be no conflict when you retrieve them because they will be prefixed with your plugin id (e.g. : `myplugin_MY_SETTING`).
local my_setting = ngx.shared.plugins_data:get("pluginid_MY_SETTING")
-- a dummy example to show how to block a request
if my_setting == "block" then
ngx.exit(ngx.HTTP_FORBIDDEN)
end
end
return M
```
That file must have the same name as the `id` defined in the plugin.json with a .lua suffix (e.g. : `myplugin.lua`).
Under the hood, bunkerized-nginx uses the [lua nginx module](https://github.com/openresty/lua-nginx-module) therefore you should be able to access to the whole **ngx.\*** functions.
Since the core already uses some external libraries you can use it in your own plugins too (see the [compile.sh](https://github.com/bunkerity/bunkerized-nginx/blob/master/compile.sh) file and the [core lua files](https://github.com/bunkerity/bunkerized-nginx/tree/master/lua)).
In case you need to add dependencies, you can do it by placing the corresponding files into the same folder of your main plugin code. Here is an example with a file named **dependency.lua** :
```lua
local M = {}
function M.my_function ()
return "42"
end
return M
```
To include it from you main code you will need to prefix it with your plugin id like that :
```lua
...
local my_dependency = require "pluginid.dependency"