Skip to content

Commit b37716a

Browse files
MaximBashurovMaximBashurov
committed
DOCS-3011 Docs for v0.9.0
1 parent 0e7032c commit b37716a

File tree

6 files changed

+186
-49
lines changed

6 files changed

+186
-49
lines changed

‎docs/configuration-guides/endpoint-related-response.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Endpoint-Related Response Actions
2+
3+
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.
4+
5+
!!! info "Example of `apifw.yaml`"
6+
```yaml
7+
mode: "PROXY"
8+
RequestValidation: "BLOCK"
9+
ResponseValidation: "BLOCK"
10+
...
11+
Endpoints:
12+
- Path: "/test/endpoint1"
13+
RequestValidation: "LOG_ONLY"
14+
ResponseValidation: "LOG_ONLY"
15+
- Path: "/test/endpoint1/{internal_id}"
16+
Method: "get"
17+
RequestValidation: "LOG_ONLY"
18+
ResponseValidation: "DISABLE"
19+
```
20+
21+
The `Method` value is optional. If the `Method` is not set then the validation modes will be applied to all methods of the endpoint.
22+
23+
Example of the same configuration via environment variables:
24+
25+
```
26+
APIFW_ENDPOINTS=/test/endpoint1|LOG_ONLY|LOG_ONLY,GET:/test/endpoint1/{internal_id}|LOG_ONLY|DISABLE
27+
```
28+
29+
The format of the `APIFW_ENDPOINTS` environment variable:
30+
31+
```
32+
[METHOD:]PATH|REQUEST_VALIDATION|RESPONSE_VALIDATION
33+
```

‎docs/configuration-guides/system-settings.md‎

Lines changed: 24 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,27 @@
11
# System Settings
22

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

5-
| Environment variable | Description |
6-
| -------------------- | ----------- |
7-
| `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`. |
8-
| `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`. |
9-
| `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`. |
10-
| `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`. |
11-
| `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`. |
12-
| `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`. |
13-
| `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`. |
14-
| `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`. |
15-
| `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`. |
16-
| `APIFW_WRITE_BUFFER_SIZE`<br>(for APIFW server) | Per-connection buffer size for response writing. The default value is `8192`. |
17-
| `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`. |
18-
| `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`. |
19-
| `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"). |
20-
| `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"). |
21-
| `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`. |
22-
| `APIFW_SERVER_WRITE_BUFFER_SIZE`<br>(for HTTP client sending requests) | Per-connection buffer size for response writing. The default value is `8192`. |
23-
| `APIFW_SERVER_MAX_RESPONSE_BODY_SIZE`<br>(for HTTP client sending requests) | Maximum response body size. The default value is `0` (means "unlimited"). |
5+
| Environment variable | YAML parameter | Description |
6+
| -------------------- | ----------- | ----------- |
7+
| `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`. |
8+
| `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`. |
9+
| `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`. |
10+
| `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`. |
11+
| `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`. |
12+
| `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`. |
13+
| `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`. |
14+
| `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`. |
15+
| `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`. |
16+
| `APIFW_WRITE_BUFFER_SIZE`<br>(for APIFW server) | `WriteBufferSize` | Per-connection buffer size for response writing. The default value is `8192`. |
17+
| `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`. |
18+
| `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`. |
19+
| `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"). |
20+
| `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"). |
21+
| `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`. |
22+
| `APIFW_SERVER_WRITE_BUFFER_SIZE`<br>(for HTTP client sending requests) | `WriteBufferSize` | Per-connection buffer size for response writing. The default value is `8192`. |
23+
| `APIFW_SERVER_MAX_RESPONSE_BODY_SIZE`<br>(for HTTP client sending requests) | `MaxResponseBodySize` | Maximum response body size. The default value is `0` (means "unlimited"). |
24+
25+
<a name="apifw-yaml-example"></a>
26+
??? info "Example of `apifw.yaml`"
27+
--8<-- "include/apifw-yaml-example.md"

‎docs/include/apifw-yaml-example.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
```yaml
2+
mode: "PROXY"
3+
RequestValidation: "BLOCK"
4+
ResponseValidation: "BLOCK"
5+
CustomBlockStatusCode: 403
6+
AddValidationStatusHeader: false
7+
APISpecs: "openapi.yaml"
8+
APISpecsCustomHeader:
9+
Name: ""
10+
Value: ""
11+
PassOptionsRequests: true
12+
SpecificationUpdatePeriod: "0"
13+
Server:
14+
APIHost: "http://0.0.0.0:8282"
15+
HealthAPIHost: "0.0.0.0:9999"
16+
ReadTimeout: "5s"
17+
WriteTimeout: "5s"
18+
ReadBufferSize: 8192
19+
WriteBufferSize: 8192
20+
MaxRequestBodySize: 4194304
21+
DisableKeepalive: false
22+
MaxConnsPerIP: 0
23+
MaxRequestsPerConn: 0
24+
DNS:
25+
Nameserver:
26+
Host: ""
27+
Port: "53"
28+
Proto: "udp"
29+
Cache: false
30+
FetchTimeout: "1m"
31+
LookupTimeout: "1s"
32+
Denylist:
33+
Tokens:
34+
CookieName: ""
35+
HeaderName: ""
36+
TrimBearerPrefix: true
37+
File: ""
38+
AllowIP:
39+
File: ""
40+
HeaderName: ""
41+
ShadowAPI:
42+
ExcludeList:
43+
- 404
44+
- 200
45+
UnknownParametersDetection: false
46+
TLS:
47+
CertsPath: "certs"
48+
CertFile: "localhost.crt"
49+
CertKey: "localhost.key"
50+
ModSecurity:
51+
ConfFiles: []
52+
RulesDir: ""
53+
Endpoints: []
54+
Backend:
55+
Oauth:
56+
ValidationType: "JWT"
57+
JWT:
58+
SignatureAlgorithm: "RS256"
59+
PubCertFile: ""
60+
SecretKey: ""
61+
Introspection:
62+
ClientAuthBearerToken: ""
63+
Endpoint: ""
64+
EndpointParams: ""
65+
TokenParamName: ""
66+
ContentType: ""
67+
EndpointMethod: "GET"
68+
RefreshInterval: "10m"
69+
ProtectedAPI:
70+
URL: "http://localhost:3000/v1/"
71+
RequestHostHeader: ""
72+
ClientPoolCapacity: 1000
73+
InsecureConnection: false
74+
RootCA: ""
75+
MaxConnsPerHost: 512
76+
ReadTimeout: "5s"
77+
WriteTimeout: "5s"
78+
DialTimeout: "200ms"
79+
ReadBufferSize: 8192
80+
WriteBufferSize: 8192
81+
MaxResponseBodySize: 0
82+
DeleteAcceptEncoding: false
83+
```

0 commit comments

Comments
 (0)