Couper Documentation

edge

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 nameContextLabel
backendDefinitions Block, Proxy Block, Request Block, JWT Block, OAuth2 AC (Beta) Block, OIDC Blockโš  required, if defined in Definitions Block

Attributes

NameTypeDefaultDescription
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 unitsDescription
nsnanoseconds
us (or ยตs)microseconds
msmilliseconds
sseconds
mminutes
hhours

Nested Blocks

NameDescription
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.