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¶

Section	Description
no section	General parameters
`wallet`	Wallet configuration
`peers`	Nodes configuration
`logger`	Logger configuration
`web`	Web configuration
`server`	Server configuration
`upload-header`	Upload header configuration
`zip`	ZIP configuration
`archive`	Archive configuration
`pprof`	Pprof configuration
`prometheus`	Prometheus configuration
`tracing`	Tracing configuration
`runtime`	Runtime configuration
`frostfs`	Frostfs configuration
`cache`	Cache configuration
`resolve_bucket`	Bucket name resolving configuration
`index_page`	Index page configuration
`cors`	CORS configuration
`multinet`	Multinet configuration
`features`	Features configuration
`containers`	Containers configuration
`contracts`	Contracts configuration

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	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
  tags:
    - names: "app,datapath"
      level: info
    - names: "external_storage_tree"

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.
`sampling.tags`	`[]Tag`	yes		Tagged log entries that should be additionally logged (available tags see in the next section).

Tags¶

There are additional log entries that can hurt performance and can be additionally logged by using logger.tags parameter. Available tags:

tags:
  - names: "app,datapath"
    level: info

Parameter	Type	SIGHUP reload	Default value	Description
`names`	`[]string`	yes		Tag names separated by `,`. Possible values see below in `Tag values` section.
`level`	`string`	yes	Value from `logger.level`	Logging level for specific tag. Possible values: `debug`, `info`, `warn`, `dpanic`, `panic`, `fatal`.

Tag values¶

app - common application logs (enabled by default).
datapath - main logic of application (enabled by default).
external_storage - external interaction with storage node (enabled by default).
external_storage_tree - external interaction with tree service in storage node (enabled by default).

`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
  max_response_attribute_size: 1024

Parameter	Type	SIGHUP reload	Default value	Description
`read_buffer_size`	`int`	no	`4096`	Per-connection buffer size for requests' reading. This also limits the maximum header size.
`write_buffer_size`	`int`	no	`4096`	Per-connection buffer size for responses' writing.
`read_timeout`	`duration`	no	`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`	no	`5m`	The maximum duration before timing out writes of the response. It is reset after the request handler has returned.
`stream_request_body`	`bool`	no	`true`	Enables request body streaming, and calls the handler sooner when given body is larger than the current limit.
`max_request_body_size`	`int`	no	`4194304`	Maximum request body size. The server rejects requests with bodies exceeding this limit.
`max_response_attribute_size`	`int`	yes	`0`	Maximum response attribute size in bytes. The server omits attribute values which exceed this limit limit. `0` means no limit.

`upload-header` section¶

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¶

DEPRECATED: Use archive section instead

zip:
  compression: false

Parameter	Type	SIGHUP reload	Default value	Description
`compression`	`bool`	yes	`false`	Enable zip compression when download files by common prefix.

`archive` section¶

archive:
  compression: false

Parameter	Type	SIGHUP reload	Default value	Description
`compression`	`bool`	yes	`false`	Enable archive 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
  netmap:
    lifetime: 1m
  cors:
    lifetime: 5m
    size: 1000

Parameter	Type	Default value	Description
`buckets`	Cache config	`lifetime: 60s` `size: 1000`	Cache which contains mapping of bucket name to bucket info.
`netmap`	Cache config	`lifetime: 1m`	Cache which stores netmap. `netmap.size` isn't applicable for this cache.
`cors`	Cache config	`lifetime: 5m` `size: 1000`	Cache which stores container CORS configurations.

`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, settings from CORS container will be used.

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.

`features` section¶

Contains parameters for enabling features.

features:
  enable_filepath_fallback: true
  enable_filepath_slash_fallback: false
  tree_pool_netmap_support: true

Parameter	Type	SIGHUP reload	Default value	Description
`features.enable_filepath_fallback`	`bool`	yes	`false`	Enable using fallback path to search for a object by `FileName` attribute if object with `FilePath` attribute wasn't found.
`features.enable_filepath_slash_fallback`	`bool`	yes	`false`	Enable using fallback path to search for a object by `FilePath`/`FileName` with/without (depends on provided value in `FilePath`/`FileName`) leading slash if object with provided `FilePath`/`FileName` wasn't found. This fallback goes before `enable_filepath_fallback`.
`features.tree_pool_netmap_support`	`bool`	no	`false`	Enable using new version of tree pool, which uses netmap to select nodes, for requests to tree service.

`containers` section¶

Section for well-known containers to store data and settings.

containers:
  cors: AZjLTXfK4vs4ovxMic2xEJKSymMNLqdwq9JT64ASFCRj

Parameter	Type	SIGHUP reload	Default value	Description
`cors`	`string`	yes		Container name for CORS configurations. If not set and cors section is not configured, CORS configuration feature is disabled.

`contracts` section¶

contracts:
  container:
    name: container.frostfs

Parameter	Type	SIGHUP reload	Default value	Description
`container.name`	`string`	no	`container.frostfs`	Container contract hash (LE) or name in NNS.

FrostFS HTTP Gateway configuration file¶

Reload on SIGHUP¶

Structure¶

General section¶

wallet section¶

peers section¶

server section¶

logger section¶

Tags¶

Tag values¶

web section¶

upload-header section¶

zip section¶

archive section¶

pprof section¶

prometheus section¶

tracing section¶

attributes subsection¶

runtime section¶

frostfs section¶

cache section¶

cache subsection¶

resolve_bucket section¶

index_page section¶

cors section¶

multinet section¶

subnet subsection¶

features section¶

containers section¶

contracts section¶