FrostFS HTTP Gateway configuration file
This section contains detailed FrostFS HTTP Gateway configuration file description
including default config values and some tips to set up configurable values.
There are some custom types used for brevity:
duration
-- string consisting of a number and a suffix. Suffix examples include s
(seconds), m
(minutes), ms
(
milliseconds).
Reload on SIGHUP
Some config values can be reloaded on SIGHUP signal.
Such parameters have special mark in tables below.
You can send SIGHUP signal to app using the following command:
$ kill -s SIGHUP <app_pid>
Example:
$ ./bin/frostfs-http-gw --config config.yaml &> http.log &
[1] 998346
$ cat http.log
# ...
2022-10-03T09:37:25.826+0300 info frostfs-http-gw/app.go:332 starting application {"app_name": "frostfs-http-gw", "version": "v0.24.0"}
# ...
$ kill -s SIGHUP 998346
$ cat http.log
# ...
2022-10-03T09:38:16.205+0300 info frostfs-http-gw/app.go:470 SIGHUP config reload completed
Structure
General section
rpc_endpoint: http://morph-chain.frostfs.devenv:30333
resolve_order:
- nns
- dns
connect_timeout: 5s
stream_timeout: 10s
request_timeout: 5s
rebalance_timer: 30s
pool_error_threshold: 100
reconnect_interval: 1m
worker_pool_size: 1000
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
rpc_endpoint |
string |
yes |
|
The address of the RPC host to which the gateway connects to resolve bucket names. |
resolve_order |
[]string |
yes |
[nns, dns] |
Order of bucket name resolvers to use. |
connect_timeout |
duration |
|
10s |
Timeout to connect to a node. |
stream_timeout |
duration |
|
10s |
Timeout for individual operations in streaming RPC. |
request_timeout |
duration |
|
15s |
Timeout to check node health during rebalance. |
rebalance_timer |
duration |
|
60s |
Interval to check node health. |
pool_error_threshold |
uint32 |
|
100 |
The number of errors on connection after which node is considered as unhealthy. |
reconnect_interval |
duration |
no |
1m |
Listeners reconnection interval. |
worker_pool_size |
int |
no |
1000 |
Maximum worker count in handler's worker pool. |
wallet
section
wallet:
path: /path/to/wallet.json
address: NfgHwwTi3wHAS8aFAN243C5vGbkYDpqLHP
passphrase: pwd
Parameter |
Type |
Default value |
Description |
path |
string |
|
Path to the wallet. |
address |
string |
|
Account address to get from wallet. If omitted default one will be used. |
passphrase |
string |
|
Passphrase to decrypt wallet. |
peers
section
# Nodes configuration
# This configuration makes the gateway use the first node (node1.frostfs:8080)
# while it's healthy. Otherwise, gateway uses the second node (node2.frostfs:8080)
# for 10% of requests and the third node (node3.frostfs:8080) for 90% of requests.
# Until nodes with the same priority level are healthy
# nodes with other priority are not used.
# The lower the value, the higher the priority.
peers:
0:
address: node1.frostfs:8080
priority: 1
weight: 1
1:
address: node2.frostfs:8080
priority: 2
weight: 0.1
2:
address: node3.frostfs:8080
priority: 2
weight: 0.9
Parameter |
Type |
Default value |
Description |
address |
string |
|
Address of storage node. |
priority |
int |
1 |
It allows to group nodes and don't switch group until all nodes with the same priority will be unhealthy. The lower the value, the higher the priority. |
weight |
float |
1 |
Weight of node in the group with the same priority. Distribute requests to nodes proportionally to these values. |
server
section
You can specify several listeners for server. For example, for http
and https
.
server:
- address: 0.0.0.0:8080
tls:
enabled: false
cert_file: /path/to/cert
key_file: /path/to/key
- address: 0.0.0.0:8081
tls:
enabled: true
cert_file: /path/to/another/cert
key_file: /path/to/another/key
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
address |
string |
|
0.0.0.0:8080 |
The address that the gateway is listening on. |
tls.enabled |
bool |
|
false |
Enable TLS or not. |
tls.cert_file |
string |
yes |
|
Path to the TLS certificate. |
tls.key_file |
string |
yes |
|
Path to the key. |
logger
section
logger:
level: debug
destination: stdout
sampling:
enabled: false
initial: 100
thereafter: 100
interval: 1s
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
level |
string |
yes |
debug |
Logging level. Possible values: debug , info , warn , error , dpanic , panic , fatal . |
destination |
string |
no |
stdout |
Destination for logger: stdout or journald |
sampling.enabled |
bool |
no |
false |
Sampling enabling flag. |
sampling.initial |
int |
no |
'100' |
Sampling count of first log entries. |
sampling.thereafter |
int |
no |
'100' |
Sampling count of entries after an interval . |
sampling.interval |
duration |
no |
'1s' |
Sampling interval of messaging similar entries. |
web
section
web:
read_buffer_size: 4096
write_buffer_size: 4096
read_timeout: 10m
write_timeout: 5m
stream_request_body: true
max_request_body_size: 4194304
Parameter |
Type |
Default value |
Description |
read_buffer_size |
int |
4096 |
Per-connection buffer size for requests' reading. This also limits the maximum header size. |
write_buffer_size |
int |
4096 |
Per-connection buffer size for responses' writing. |
read_timeout |
duration |
10m |
The amount of time allowed to read the full request including body. The connection's read deadline is reset when the connection opens, or for keep-alive connections after the first byte has been read. |
write_timeout |
duration |
5m |
The maximum duration before timing out writes of the response. It is reset after the request handler has returned. |
stream_request_body |
bool |
true |
Enables request body streaming, and calls the handler sooner when given body is larger than the current limit. |
max_request_body_size |
int |
4194304 |
Maximum request body size. The server rejects requests with bodies exceeding this limit. |
upload_header:
use_default_timestamp: false
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
use_default_timestamp |
bool |
yes |
false |
Create timestamp for object if it isn't provided by header. |
zip
section
zip:
compression: false
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
compression |
bool |
yes |
false |
Enable zip compression when download files by common prefix. |
pprof
section
Contains configuration for the pprof
profiler.
pprof:
enabled: true
address: localhost:8083
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
enabled |
bool |
yes |
false |
Flag to enable the service. |
address |
string |
yes |
localhost:8083 |
Address that service listener binds to. |
prometheus
section
Contains configuration for the prometheus
metrics service.
prometheus:
enabled: true
address: localhost:8084
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
enabled |
bool |
yes |
false |
Flag to enable the service. |
address |
string |
yes |
localhost:8084 |
Address that service listener binds to. |
tracing
section
Contains configuration for the tracing
service.
tracing:
enabled: true
exporter: "otlp_grpc"
endpoint: "localhost:4317"
trusted_ca: "/etc/ssl/telemetry-trusted-ca.pem"
attributes:
- key: key0
value: value
- key: key1
value: value
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
enabled |
bool |
yes |
false |
Flag to enable the tracing. |
exporter |
string |
yes |
|
Trace collector type (stdout or otlp_grpc are supported). |
endpoint |
string |
yes |
|
Address of collector endpoint for OTLP exporters. |
trusted_ca |
string |
yes |
|
Path to certificate of a certification authority in pem format, that issued the TLS certificate of the telemetry remote server. |
attributes |
[]Attributes |
yes |
|
An array of configurable attributes in key-value format. |
attributes
subsection
attributes:
- key: key0
value: value
- key: key1
value: value
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
key |
string |
yes |
|
Attribute key. |
value |
string |
yes |
|
Attribute value. |
runtime
section
Contains runtime parameters.
runtime:
soft_memory_limit: 1gb
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
soft_memory_limit |
size |
yes |
maxint64 |
Soft memory limit for the runtime. Zero or no value stands for no limit. If GOMEMLIMIT environment variable is set, the value from the configuration file will be ignored. |
frostfs
section
Contains parameters of requests to FrostFS.
frostfs:
client_cut: false
buffer_max_size_for_put: 1048576 # 1mb
tree_pool_max_attempts: 0
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
client_cut |
bool |
yes |
false |
This flag enables client side object preparing. |
buffer_max_size_for_put |
uint64 |
yes |
1048576 |
Sets max buffer size for read payload in put operations. |
tree_pool_max_attempts |
uint32 |
no |
0 |
Sets max attempt to make successful tree request. Value 0 means the number of attempts equals to number of nodes in pool. |
cache
section
cache:
buckets:
lifetime: 1m
size: 1000
Parameter |
Type |
Default value |
Description |
buckets |
Cache config |
lifetime: 60s
size: 1000 |
Cache which contains mapping of bucket name to bucket info. |
cache
subsection
lifetime: 1m
size: 1000
Parameter |
Type |
Default value |
Description |
lifetime |
duration |
depends on cache |
Lifetime of entries in cache. |
size |
int |
depends on cache |
LRU cache size. |
resolve_bucket
section
Bucket name resolving parameters from and to container ID.
resolve_bucket:
namespace_header: X-Frostfs-Namespace
default_namespaces: [ "", "root" ]
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
namespace_header |
string |
yes |
X-Frostfs-Namespace |
Header to determine zone to resolve bucket name. |
default_namespaces |
[]string |
yes |
["","root"] |
Namespaces that should be handled as default. |
index_page
section
Parameters for index HTML-page output. Activates if GetObject
request returns not found
. Two
index page modes available:
s3
mode uses tree service for listing objects,
native
sends requests to nodes via native protocol.
If request pass S3-bucket name instead of CID, s3
mode will be used, otherwise native
.
index_page:
enabled: false
template_path: ""
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
enabled |
bool |
yes |
false |
Flag to enable index_page return if no object with specified S3-name was found. |
template_path |
string |
yes |
"" |
Path to .gotmpl file with html template for index_page. |
cors
section
Parameters for CORS (used in OPTIONS requests and responses in all handlers).
If values are not set, headers will not be included to response.
cors:
allow_origin: "*"
allow_methods: ["GET", "HEAD"]
allow_headers: ["Authorization"]
expose_headers: ["*"]
allow_credentials: false
max_age: 600
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
allow_origin |
string |
yes |
|
Values for Access-Control-Allow-Origin headers. |
allow_methods |
[]string |
yes |
|
Values for Access-Control-Allow-Methods headers. |
allow_headers |
[]string |
yes |
|
Values for Access-Control-Allow-Headers headers. |
expose_headers |
[]string |
yes |
|
Values for Access-Control-Expose-Headers headers. |
allow_credentials |
bool |
yes |
false |
Values for Access-Control-Allow-Credentials headers. |
max_age |
int |
yes |
600 |
Values for Access-Control-Max-Age headers. |
multinet
section
Configuration of multinet support.
multinet:
enabled: false
balancer: roundrobin
restrict: false
fallback_delay: 300ms
subnets:
- mask: 1.2.3.4/24
source_ips:
- 1.2.3.4
- 1.2.3.5
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
enabled |
bool |
yes |
false |
Enables multinet setting to manage source ip of outcoming requests. |
balancer |
string |
yes |
"" |
Strategy to pick source IP. By default picks first address. Supports roundrobin setting. |
restrict |
bool |
yes |
false |
Restricts requests to an undefined subnets. |
fallback_delay |
duration |
yes |
300ms |
Delay between IPv6 and IPv4 fallback stack switch. |
subnets |
[]Subnet |
yes |
|
Set of subnets to apply multinet dial settings. |
subnet
subsection
- mask: 1.2.3.4/24
source_ips:
- 1.2.3.4
- 1.2.3.5
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
mask |
string |
yes |
|
Destination subnet. |
source_ips |
[]string |
yes |
|
Array of source IP addresses to use when dialing destination subnet. |
kludge
section
Workarounds for non-standard use cases.
kludge:
additional_search: true
Parameter |
Type |
SIGHUP reload |
Default value |
Description |
kludge.additional_search |
bool |
yes |
false |
Enable using additional search by attribute. If the value of the FilePath attribute in the request contains no / symbols or single leading / symbol and the object was not found, then an attempt is made to search for the object by the attribute FileName . |