Backend

The backend block defines the connection to a local/remote backend service.

Backends can be defined in the Definitions Block and referenced by label.

Block name	Context	Label
`backend`	Definitions Block, Proxy Block, Request Block, JWT Block, OAuth2 AC (Beta) Block, OIDC Block	⚠ required, if defined in Definitions Block

Attributes

Name	Type	Default	Description
`add_form_params`	object	-	Key/value pairs to add form parameters to the upstream request body.
`add_query_params`	object	-	Key/value pairs to add query parameters to the upstream request URL.
`add_request_headers`	object	-	Key/value pairs to add as request headers in the upstream request.
`add_response_headers`	object	-	Key/value pairs to add as response headers in the client response.
`basic_auth`	string	-	Basic auth for the upstream request with format `user:pass`.
`connect_timeout`	duration	`"10s"`	The total timeout for dialing and connect to the origin.
`custom_log_fields`	object	-	Log fields for custom logging. Inherited by nested blocks.
`disable_certificate_validation`	bool	`false`	Disables the peer certificate validation. Must not be used in backend refinement.
`disable_connection_reuse`	bool	`false`	Disables reusage of connections to the origin. Must not be used in backend refinement.
`hostname`	string	-	Value of the HTTP host header field for the origin request. Since hostname replaces the request host the value will also be used for a server identity check during a TLS handshake with the origin.
`http2`	bool	`false`	Enables the HTTP2 support. Must not be used in backend refinement.
`max_connections`	number	`0`	The maximum number of concurrent connections in any state (active or idle) to the origin. Must not be used in backend refinement.
`origin`	string	-	URL to connect to for backend requests.
`path`	string	-	Changeable part of upstream URL.
`path_prefix`	string	-	Prefixes all backend request paths with the given prefix.
`proxy`	string	-	A proxy URL for the related origin request.
`remove_form_params`	object	-	List of names to remove form parameters from the upstream request body.
`remove_query_params`	tuple (string)	`[]`	List of names to remove query parameters from the upstream request URL.
`remove_request_headers`	tuple (string)	`[]`	List of names to remove headers from the upstream request.
`remove_response_headers`	tuple (string)	`[]`	List of names to remove headers from the client response.
`set_form_params`	object	-	Key/value pairs to set query parameters in the upstream request URL.
`set_query_params`	object	-	Key/value pairs to set query parameters in the upstream request URL.
`set_request_headers`	object	-	Key/value pairs to set as request headers in the upstream request.
`set_response_headers`	object	-	Key/value pairs to set as response headers in the client response.
`set_response_status`	number	-	Modifies the response status code.
`timeout`	duration	`"300s"`	The total deadline duration a backend request has for write and read/pipe.
`ttfb_timeout`	duration	`"60s"`	The duration from writing the full request to the origin and receiving the answer.
`use_when_unhealthy`	bool	`false`	Ignores the health state and continues with the outgoing request.

Duration

Values of type duration are provided as number string followed by a unit listed below.

Example: timeout = "300s"

Duration units	Description
`ns`	nanoseconds
`us` (or `µs`)	microseconds
`ms`	milliseconds
`s`	seconds
`m`	minutes
`h`	hours

Nested Blocks

Name	Description
`beta_health`	Configures a health check (zero or one).
`beta_rate_limit`	Configures rate limiting (zero or one).
`beta_token_request`	Configures a token request authorization (zero or more).
`oauth2`	Configures an OAuth2 authorization (zero or one).
`openapi`	Configures OpenAPI validation (zero or one).
`tls`	Configures backend TLS (zero or one).

Refining a referenced backend

Referenced backends may be "refined" by using a labeled backend block in places where an unlabeled backend block would also be allowed, e.g. in a proxy block:

    proxy {
      backend "ref_be" {      # refine referenced backend
        path = "/b"           # override existing attribute value
        add_form_params = {   # set new attribute
          # ...
        }
      }
    }

# ...

definitions {
  backend "ref_be" {
    origin = "https://example.com"
    path = "/a"
  }
}

If an attribute is set in both the referenced and the refining block, the value in the refining block is used.

Note: Child blocks and the following attributes are not allowed in refining backend blocks:

disable_certificate_validation,
disable_connection_reuse,
http2 and
max_connections.

< TLS (Backend)

Basic Auth >