> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-general.md).
# General plugins
Plugins in this category provide utility behaviour that does not fit a more specific category: redirects, mirroring, request validation, response substitution. Useful when the policy you need does not map cleanly to authentication, traffic control, or observability. The catalogue ships 8 General plugins.
{% hint style="info" %}
**In this category:** [`echo`](#echo), [`ext-plugin-post-req`](#ext-plugin-post-req), [`ext-plugin-post-resp`](#ext-plugin-post-resp), [`ext-plugin-pre-req`](#ext-plugin-pre-req), [`gzip`](#gzip), [`inspect`](#inspect), [`real-ip`](#real-ip), [`redirect`](#redirect)
{% endhint %}
### `echo`
The `echo` Plugin is to help users understand how they can develop an AILIX Plugin.
{% hint style="info" %}
**Priority** `412` · **Category** General
{% endhint %}
Configuration and details
This Plugin addresses common functionalities in phases like init, rewrite, access, balancer, header filter, body filter and log.
:::caution WARNING
The `echo` Plugin is built as an example. It has missing cases and should **not** be used in production environments.
:::
| Name | Type | Requirement | Default | Valid | Description |
| ------------ | ------ | ----------- | ------- | ----- | ----------------------------------------- |
| before\_body | string | optional | | | Body to use before the filter phase. |
| body | string | optional | | | Body that replaces the Upstream response. |
| after\_body | string | optional | | | Body to use after the modification phase. |
| headers | object | optional | | | New headers to use for the response. |
### `ext-plugin-post-req`
`ext-plugin-post-req` differs from the ext-plugin-pre-req Plugin in that it runs after executing the built-in Lua Plugins and before proxying to the Upstream.
{% hint style="info" %}
**Priority** `-3000` · **Category** General
{% endhint %}
Configuration and details
You can learn more about the configuration from the ext-plugin-pre-req Plugin document.
### `ext-plugin-post-resp`
The `ext-plugin-post-resp` Plugin is for running specific external Plugins in the Plugin Runner before executing the built-in Lua Plugins.
{% hint style="info" %}
**Priority** `-4000` · **Category** General
{% endhint %}
Configuration and details
The `ext-plugin-post-resp` plugin will be executed after the request gets a response from the upstream.
This plugin uses lua-resty-http library under the hood to send requests to the upstream, due to which the proxy-control, proxy-mirror, and proxy-cache plugins are not available to be used alongside this plugin. Also, mTLS Between AILIX and Upstream is not yet supported.
See External Plugin to learn more.
:::note
Execution of External Plugins will affect the response of the current request.
:::
| Name | Type | Required | Default | Valid values | Description |
| ------------------ | ------- | -------- | ------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| conf | array | False | | \[{"name": "ext-plugin-A", "value": "{"enable":"feature"}"}] | List of Plugins and their configurations to be executed on the Plugin Runner. |
| allow\_degradation | boolean | False | false | | Sets Plugin degradation when the Plugin Runner is not available. When set to `true`, requests are allowed to continue. |
### `ext-plugin-pre-req`
The `ext-plugin-pre-req` Plugin is for running specific external Plugins in the Plugin Runner before executing the built-in Lua Plugins.
{% hint style="info" %}
**Priority** `12000` · **Category** General
{% endhint %}
Configuration and details
See External Plugin to learn more.
:::note
Execution of External Plugins will affect the behavior of the current request.
:::
| Name | Type | Required | Default | Valid values | Description |
| ------------------ | ------- | -------- | ------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| conf | array | False | | \[{"name": "ext-plugin-A", "value": "{"enable":"feature"}"}] | List of Plugins and their configurations to be executed on the Plugin Runner. |
| allow\_degradation | boolean | False | false | | Sets Plugin degradation when the Plugin Runner is not available. When set to `true`, requests are allowed to continue. |
### `gzip`
The `gzip` Plugin dynamically sets the behavior of [gzip in Nginx](https://docs.nginx.com/nginx/admin-guide/web-server/compression/). When the `gzip` plugin is enabled, the client needs to include `Accept-Encoding: gzip` in the request header to indicate support for gzip compression. Upon receiving the request, AILIX dynamically determines whether to compress the response content based on the client's support and server configuration. If the conditions are met, `AILIX` adds the `Content-Encoding: gzip` header to the response, indicating that the response content has been compressed using gzip. Upon receiving the response, the client uses the corresponding decompression algorithm based on the `Content-Encoding` header to decompress the response content and obtain the original response content.
{% hint style="info" %}
**Priority** `995` · **Category** General
{% endhint %}
Configuration and details
:::info IMPORTANT
This Plugin requires AILIX to run on AILIX-Runtime.
:::
| Name | Type | Required | Default | Valid values | Description |
| -------------- | ---------------------- | -------- | -------------- | ------------ | --------------------------------------------------------------------------------------- |
| types | array\[string] or "\*" | False | \["text/html"] | | Dynamically sets the `gzip_types` directive. Special value `"*"` matches any MIME type. |
| min\_length | integer | False | 20 | >= 1 | Dynamically sets the `gzip_min_length` directive. |
| comp\_level | integer | False | 1 | \[1, 9] | Dynamically sets the `gzip_comp_level` directive. |
| http\_version | number | False | 1.1 | 1.1, 1.0 | Dynamically sets the `gzip_http_version` directive. |
| buffers.number | integer | False | 32 | >= 1 | Dynamically sets the `gzip_buffers` directive parameter `number`. |
| buffers.size | integer | False | 4096 | >= 1 | Dynamically sets the `gzip_buffers` directive parameter `size`. The unit is in bytes. |
| vary | boolean | False | false | | Dynamically sets the `gzip_vary` directive. |
### `inspect`
It's useful to set arbitrary breakpoint in any Lua file to inspect the context information, e.g. print local variables if some condition satisfied.
{% hint style="info" %}
**Priority** `200` · **Category** General
{% endhint %}
Configuration and details
In this way, you don't need to modify the source code of your project, and just get diagnose information on demand, i.e. dynamic logging.
This plugin supports setting breakpoints within both interpretd function and jit compiled function. The breakpoint could be at any position within the function. The function could be global/local/module/ananymous.
| Name | Type | Required | Default | Description |
| ----------- | ------- | -------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| delay | integer | False | 3 | Time in seconds specifying how often to check the hooks file. |
| hooks\_file | string | False | "/usr/local/ailix/plugin\_inspect\_hooks.lua" | Lua file to define hooks, which could be a link file. Ensure only administrator could write this file, otherwise it may be a security risk. |
### `real-ip`
The `real-ip` Plugin allows AILIX to set the client's real IP by the IP address passed in the HTTP header or HTTP query string. This is particularly useful when AILIX is behind a reverse proxy since the proxy could act as the request-originating client otherwise.
{% hint style="info" %}
**Priority** `23000` · **Category** General · **Required** `source`
{% endhint %}
Configuration and details
The Plugin is functionally similar to NGINX's [ngx\_http\_realip\_module](https://nginx.org/en/docs/http/ngx_http_realip_module.html) but offers more flexibility.
| Name | Type | Required | Default | Valid values | Description |
| ------------------ | -------------- | -------- | ------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| source | string | True | | | A built-in AILIX variable or [NGINX variable](https://nginx.org/en/docs/varindex.html), such as `http_x_forwarded_for` or `arg_realip`. The variable value should be a valid IP address that represents the client's real IP address, with an optional port. |
| trusted\_addresses | array\[string] | False | | array of IPv4 or IPv6 addresses (CIDR notation acceptable) | Trusted addresses that are known to send correct replacement addresses. This configuration sets the [`set_real_ip_from`](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. |
| recursive | boolean | False | False | | If false, replace the original client address that matches one of the trusted addresses by the last address sent in the configured source.
If true, replace the original client address that matches one of the trusted addresses by the last non-trusted address sent in the configured source.
|
### `redirect`
The `redirect` Plugin can be used to configure redirects.
{% hint style="info" %}
**Priority** `900` · **Category** General
{% endhint %}
Configuration and details
| Name | Type | Required | Default | Valid values | Description |
| --------------------- | -------------- | -------- | ------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| http\_to\_https | boolean | False | false | | When set to `true` and the request is HTTP, it will be redirected to HTTPS with the same URI with a 301 status code. Note the querystring from the raw URI will also be contained in the Location header. |
| uri | string | False | | | URI to redirect to. Can contain Nginx variables. For example, `/test/index.html`, `$uri/index.html`, `${uri}/index.html`, `https://example.com/foo/bar`. If you refer to a variable name that doesn't exist, instead of throwing an error, it will treat it as an empty variable. |
| regex\_uri | array\[string] | False | | | Match the URL from client with a regular expression and redirect. If it doesn't match, the request will be forwarded to the Upstream. Only either of `uri` or `regex_uri` can be used at a time. For example, \[" ^/iresty/(.*)/(.*)/(.\*)", "/$1-$2-$3"], where the first element is the regular expression to match and the second element is the URI to redirect to. AILIX only support one `regex_uri` currently, so the length of the `regex_uri` array is `2`. |
| ret\_code | integer | False | 302 | \[200, ...] | HTTP response code. |
| encode\_uri | boolean | False | false | | When set to `true` the URI in the `Location` header will be encoded as per [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986). |
| append\_query\_string | boolean | False | false | | When set to `true`, adds the query string from the original request to the `Location` header. If the configured `uri` or `regex_uri` already contains a query string, the query string from the request will be appended to it with an `&`. Do not use this if you have already handled the query string (for example, with an Nginx variable `$request_uri`) to avoid duplicates. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-general.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.