Skip to content

DOCS-3011 Docs for v0.9.0 #128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
afr1ka merged 1 commit into from
Apr 4, 2025
Merged

DOCS-3011 Docs for v0.9.0 #128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/configuration-guides/endpoint-related-response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Endpoint-Related Response Actions

You can configure [validation modes](../installation-guides/docker-container.md#apifw-req-val) (`RequestValidation`, `ResponseValidation`) for each endpoint separately. If not set for the endpoint specifically, global value is used.

!!! info "Example of `apifw.yaml`"
```yaml
mode: "PROXY"
RequestValidation: "BLOCK"
ResponseValidation: "BLOCK"
...
Endpoints:
- Path: "/test/endpoint1"
RequestValidation: "LOG_ONLY"
ResponseValidation: "LOG_ONLY"
- Path: "/test/endpoint1/{internal_id}"
Method: "get"
RequestValidation: "LOG_ONLY"
ResponseValidation: "DISABLE"
```

The `Method` value is optional. If the `Method` is not set then the validation modes will be applied to all methods of the endpoint.

Example of the same configuration via environment variables:

```
APIFW_ENDPOINTS=/test/endpoint1|LOG_ONLY|LOG_ONLY,GET:/test/endpoint1/{internal_id}|LOG_ONLY|DISABLE
```

The format of the `APIFW_ENDPOINTS` environment variable:

```
[METHOD:]PATH|REQUEST_VALIDATION|RESPONSE_VALIDATION
```
44 changes: 24 additions & 20 deletions docs/configuration-guides/system-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,27 @@
# System Settings

To fine-tune system API Firewall settings, use the following optional environment variables:
To fine-tune system API Firewall settings, use the following optional environment variables or YAML parameters:

| Environment variable | Description |
| -------------------- | ----------- |
| `APIFW_READ_TIMEOUT` | The timeout for API Firewall to read the full request (including the body) sent to the application URL. The default value is `5s`. |
| `APIFW_WRITE_TIMEOUT` | The timeout for API Firewall to return the response to the request sent to the application URL. The default value is `5s`. |
| `APIFW_SERVER_MAX_CONNS_PER_HOST`<br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | The maximum number of connections that API Firewall can handle simultaneously. The default value is `512`. |
| `APIFW_SERVER_READ_TIMEOUT` <br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | The timeout for API Firewall to read the full response (including the body) returned to the request by the application. The default value is `5s`. |
| `APIFW_SERVER_WRITE_TIMEOUT` <br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | The timeout for API Firewall to write the full request (including the body) to the application. The default value is `5s`. |
| `APIFW_SERVER_DIAL_TIMEOUT` <br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | The timeout for API Firewall to connect to the application. The default value is `200ms`. |
| `APIFW_SERVER_CLIENT_POOL_CAPACITY` <br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | Maximum number of the fasthttp clients. The default value is `1000`. |
| `APIFW_HEALTH_HOST` | The host of the health check service. The default value is `0.0.0.0:9667`. The liveness probe service path is `/v1/liveness` and the readiness service path is `/v1/readiness`. |
| `APIFW_READ_BUFFER_SIZE`<br>(for APIFW server) | Per-connection buffer size for request reading. This also limits the maximum header size. Increase this buffer if your clients send multi-KB RequestURIs and/or multi-KB headers (for example, BIG cookies). The default value is `8192`. |
| `APIFW_WRITE_BUFFER_SIZE`<br>(for APIFW server) | Per-connection buffer size for response writing. The default value is `8192`. |
| `APIFW_MAX_REQUEST_BODY_SIZE`<br>(for APIFW server) | Maximum request body size. The server rejects requests with bodies exceeding this limit. The default value is `4194304`. |
| `APIFW_DISABLE_KEEPALIVE`<br>(for APIFW server) | Disables the keep-alive connections. The server will close all the incoming connections after sending the first response to the client if this option is set to `true`. The default value is `false`. |
| `APIFW_MAX_CONNS_PER_IP`<br>(for APIFW server) | Maximum number of concurrent client connections allowed per IP. The default value is `0` (means "unlimited"). |
| `APIFW_MAX_REQUESTS_PER_CONN`<br>(for APIFW server) | Maximum number of requests served per connection. The server closes the connection after the last request. The `Connection: close` header is added to the last response. The default value is `0` (means "unlimited"). |
| `APIFW_SERVER_READ_BUFFER_SIZE`<br>(for HTTP client sending requests) | Per-connection buffer size for request reading. This also limits the maximum header size. The default value is `8192`. |
| `APIFW_SERVER_WRITE_BUFFER_SIZE`<br>(for HTTP client sending requests) | Per-connection buffer size for response writing. The default value is `8192`. |
| `APIFW_SERVER_MAX_RESPONSE_BODY_SIZE`<br>(for HTTP client sending requests) | Maximum response body size. The default value is `0` (means "unlimited"). |
| Environment variable | YAML parameter | Description |
| -------------------- | ----------- | ----------- |
| `APIFW_READ_TIMEOUT` | Server → `ReadTimeout` | The timeout for API Firewall to read the full request (including the body) sent to the application URL. The default value is `5s`. |
| `APIFW_WRITE_TIMEOUT` | Server → `WriteTimeout` | The timeout for API Firewall to return the response to the request sent to the application URL. The default value is `5s`. |
| `APIFW_SERVER_MAX_CONNS_PER_HOST`<br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | `MaxConnsPerHost` | The maximum number of connections that API Firewall can handle simultaneously. The default value is `512`. |
| `APIFW_SERVER_READ_TIMEOUT` <br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | Backend → ProtectedAPI → `ReadTimeout` | The timeout for API Firewall to read the full response (including the body) returned to the request by the application. The default value is `5s`. |
| `APIFW_SERVER_WRITE_TIMEOUT` <br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | Backend → ProtectedAPI → `WriteTimeout` | The timeout for API Firewall to write the full request (including the body) to the application. The default value is `5s`. |
| `APIFW_SERVER_DIAL_TIMEOUT` <br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | `DialTimeout` | The timeout for API Firewall to connect to the application. The default value is `200ms`. |
| `APIFW_SERVER_CLIENT_POOL_CAPACITY` <br>(for [`PROXY`](../installation-guides/docker-container.md) and [`graphql`](../installation-guides/graphql/docker-container.md) modes) | `ClientPoolCapacity` | Maximum number of the fasthttp clients. The default value is `1000`. |
| `APIFW_HEALTH_HOST` | HealthAPIHost | The host of the health check service. The default value is `0.0.0.0:9667`. The liveness probe service path is `/v1/liveness` and the readiness service path is `/v1/readiness`. |
| `APIFW_READ_BUFFER_SIZE`<br>(for APIFW server) | `ReadBufferSize` | Per-connection buffer size for request reading. This also limits the maximum header size. Increase this buffer if your clients send multi-KB RequestURIs and/or multi-KB headers (for example, BIG cookies). The default value is `8192`. |
| `APIFW_WRITE_BUFFER_SIZE`<br>(for APIFW server) | `WriteBufferSize` | Per-connection buffer size for response writing. The default value is `8192`. |
| `APIFW_MAX_REQUEST_BODY_SIZE`<br>(for APIFW server) | `MaxRequestBodySize` | Maximum request body size. The server rejects requests with bodies exceeding this limit. The default value is `4194304`. |
| `APIFW_DISABLE_KEEPALIVE`<br>(for APIFW server) | `DisableKeepalive` | Disables the keep-alive connections. The server will close all the incoming connections after sending the first response to the client if this option is set to `true`. The default value is `false`. |
| `APIFW_MAX_CONNS_PER_IP`<br>(for APIFW server) | `MaxConnsPerIP` | Maximum number of concurrent client connections allowed per IP. The default value is `0` (means "unlimited"). |
| `APIFW_MAX_REQUESTS_PER_CONN`<br>(for APIFW server) | `MaxRequestsPerConn` | Maximum number of requests served per connection. The server closes the connection after the last request. The `Connection: close` header is added to the last response. The default value is `0` (means "unlimited"). |
| `APIFW_SERVER_READ_BUFFER_SIZE`<br>(for HTTP client sending requests) | `ReadBufferSize` | Per-connection buffer size for request reading. This also limits the maximum header size. The default value is `8192`. |
| `APIFW_SERVER_WRITE_BUFFER_SIZE`<br>(for HTTP client sending requests) | `WriteBufferSize` | Per-connection buffer size for response writing. The default value is `8192`. |
| `APIFW_SERVER_MAX_RESPONSE_BODY_SIZE`<br>(for HTTP client sending requests) | `MaxResponseBodySize` | Maximum response body size. The default value is `0` (means "unlimited"). |

<a name="apifw-yaml-example"></a>
??? info "Example of `apifw.yaml`"
--8<-- "include/apifw-yaml-example.md"
83 changes: 83 additions & 0 deletions docs/include/apifw-yaml-example.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
```yaml
mode: "PROXY"
RequestValidation: "BLOCK"
ResponseValidation: "BLOCK"
CustomBlockStatusCode: 403
AddValidationStatusHeader: false
APISpecs: "openapi.yaml"
APISpecsCustomHeader:
Name: ""
Value: ""
PassOptionsRequests: true
SpecificationUpdatePeriod: "0"
Server:
APIHost: "http://0.0.0.0:8282"
HealthAPIHost: "0.0.0.0:9999"
ReadTimeout: "5s"
WriteTimeout: "5s"
ReadBufferSize: 8192
WriteBufferSize: 8192
MaxRequestBodySize: 4194304
DisableKeepalive: false
MaxConnsPerIP: 0
MaxRequestsPerConn: 0
DNS:
Nameserver:
Host: ""
Port: "53"
Proto: "udp"
Cache: false
FetchTimeout: "1m"
LookupTimeout: "1s"
Denylist:
Tokens:
CookieName: ""
HeaderName: ""
TrimBearerPrefix: true
File: ""
AllowIP:
File: ""
HeaderName: ""
ShadowAPI:
ExcludeList:
- 404
- 200
UnknownParametersDetection: false
TLS:
CertsPath: "certs"
CertFile: "localhost.crt"
CertKey: "localhost.key"
ModSecurity:
ConfFiles: []
RulesDir: ""
Endpoints: []
Backend:
Oauth:
ValidationType: "JWT"
JWT:
SignatureAlgorithm: "RS256"
PubCertFile: ""
SecretKey: ""
Introspection:
ClientAuthBearerToken: ""
Endpoint: ""
EndpointParams: ""
TokenParamName: ""
ContentType: ""
EndpointMethod: "GET"
RefreshInterval: "10m"
ProtectedAPI:
URL: "http://localhost:3000/v1/"
RequestHostHeader: ""
ClientPoolCapacity: 1000
InsecureConnection: false
RootCA: ""
MaxConnsPerHost: 512
ReadTimeout: "5s"
WriteTimeout: "5s"
DialTimeout: "200ms"
ReadBufferSize: 8192
WriteBufferSize: 8192
MaxResponseBodySize: 0
DeleteAcceptEncoding: false
```
Loading