Configuration

This section covers all aspects of configuring Couper.

Blocks
Configuration Blocks
Detailed reference for all configuration blocks.
Access Control
Access Control
The configuration of access controls is twofold in Couper: You define the particular type such as jwt or basic_auth in definitions, each with a distinct label (must not be one of the reserved names: granted_permissions, required_permission).
Anywhere in the server block those labels can be used in the access_control list to protect the respective block.
📝 Access permissions are inherited by nested blocks.
You can also disable access control for blocks with disable_access_control: With disable_access_control = ["bar"], the access_control named bar will be disabled for the corresponding block context.

Command Line Interface

Couper is build as binary called couper with the following commands:

Command	Description
`run`	Start the server with given configuration file.
`help`	Print the usage for the given command: `help run`
`verify`	Verify the syntax of the given configuration file.
`version`	Print the current version and build information.

Most of the following command-line options map to settings.

Basic Options

Argument	Default	Environment	Description
`-f`	`couper.hcl`	`COUPER_FILE`	Path to a Couper configuration file.
`-d`	`""`	`COUPER_FILE_DIRECTORY`	Path to a directory containing Couper configuration files.
`-p`	`8080`	`COUPER_DEFAULT_PORT`	Sets the default port to the given value and does not override explicit `[host:port]` configurations from file.
`-e`	`""`	`COUPER_ENVIRONMENT`	Name of environment in which Couper is currently running.
`-watch`	`false`	`COUPER_WATCH`	Watch for configuration file changes and reload on modifications.
`-watch-retries`	`5`	`COUPER_WATCH_RETRIES`	Maximum retry count for configuration reloads which could not bind the configured port.
`-watch-retry-delay`	`500ms`	`COUPER_WATCH_RETRY_DELAY`	Delay duration before next attempt if an error occurs.

Note: Apart from e and p, these options do not map to settings.

Configuration File
Configuration File
The language for Couper’s configuration file is HCL 2.0, a configuration language by HashiCorp.
IDE Extension
Couper provides its own IDE extension that adds Couper-specific highlighting and autocompletion to Couper’s configuration file couper.hcl in Visual Studio Code.
Get it from the Visual Studio Market Place or visit the Extension repository.
File Name
The file-ending of your configuration file should be .hcl to have syntax highlighting within your IDE.
The file name defaults to couper.hcl in your working directory. This can be changed with the -f command-line flag. With -f /opt/couper/my_conf.hcl couper changes the working directory to /opt/couper and loads my_conf.hcl.
Errors
Errors
Introduction
Errors can occur in various places: due to invalid client requests or problems on the backend and network side. Couper specifies some generic error categories (like configuration, server, backend or access_control) to help you identify the occurring problems faster.
Error messages
Error messages are only sent to the client as a summary. Detailed information is provided via log message. This way, all information can be viewed without accidentally revealing confidential information.

Expressions

Since we use HCL 2.0 for our configuration, we are able to use attribute values as expression.

# Arithmetic with literals and application-provided variables.
sum = 1 + addend

# String interpolation and templates.
message = "Hello, ${name}!"

# Application-provided functions.
shouty_message = upper(message)

See functions.

Functions

This functions can be used and combined as standalone call with all kind of hcl expressions. But some of them requires a definitions reference.

Name	Type	Description	Arguments	Example
`base64_decode`	string	Decodes Base64 data, as specified in RFC 4648.	`encoded` (string)	`base64_decode("Zm9v")`
`base64_encode`	string	Encodes Base64 data, as specified in RFC 4648.	`decoded` (string)	`base64_encode("foo")`
`can`	bool	Tries to evaluate the expression given in its first argument.	`expression` (expression)	`{ for k in ["not_there", "method", "path"] : k => request[k] if can(request[k]) }`
`contains`	bool	Determines whether a given list contains a given single value as one of its elements.	`list` (tuple or list), `value` (various)	`contains([1,2,3], 2)`
`default`	string	Returns the first of the given arguments that is not null or an empty string. If no argument matches, the last argument is returned.	`arg...` (various)	`default(request.cookies.foo, "bar")`
`join`	string	Concatenates together the string elements of one or more lists with a given separator.	`sep` (string), `lists...` (tuples or lists)	`join("-", [0,1,2,3])`
`json_decode`	various	Parses the given JSON string and, if it is valid, returns the value it represents.	`encoded` (string)	`json_decode("{\"foo\": 1}")`
`json_encode`	string	Returns a JSON serialization of the given value.	`val` (various)	`json_encode(request.context.myJWT)`
`jwt_sign`	string	Creates and signs a JSON Web Token (JWT) from information from a referenced JWT Signing Profile Block (or JWT Block with `signing_ttl`) and additional claims provided as a function parameter.	`label` (string), `claims` (object)	`jwt_sign("myJWT")`
`keys`	list	Takes a map and returns a sorted list of the map keys.	`inputMap` (object or map)	`keys(request.headers)`
`length`	integer	Returns the number of elements in the given collection.	`collection` (tuple, list or map; no object)	`length([0,1,2,3])`
`lookup`	various	Performs a dynamic lookup into a map. The default (third argument) is returned if the key (second argument) is not found in the inputMap (first argument).	`inputMap` (object or map), `key` (string), `default` (various)	`lookup({a = 1}, "b", "def")`
`merge`	object or tuple	Deep-merges two or more of either objects or tuples. `null` arguments are ignored. An attribute value with a different type than the current value is set as the new value. `merge()` with no parameters returns `null`.	`arg...` (object or tuple)	`merge(request.headers, { x-additional = "myval" })`
`oauth2_authorization_url`	string	Creates an OAuth2 authorization URL from a referenced OAuth2 AC (Beta) Block or OIDC Block.	`label` (string)	`oauth2_authorization_url("myOAuth2")`
`oauth2_verifier`	string	Creates a cryptographically random key as specified in RFC 7636, applicable for all verifier methods; e.g. to be set as a cookie and read into `verifier_value`. Multiple calls of this function in the same client request context return the same value.		`oauth2_verifier()`
`relative_url`	string	Returns a relative URL by retaining `path`, `query` and `fragment` components. The input URL `s` must begin with `/<path>`, `//<authority>`, `http://` or `https://`, otherwise an error is thrown.	`s` (string)	`relative_url("https://httpbin.org/anything?query#fragment") // returns "/anything?query#fragment"`
`saml_sso_url`	string	Creates a SAML SingleSignOn URL (including the `SAMLRequest` parameter) from a referenced SAML Block.	`label` (string)	`saml_sso_url("mySAML")`
`set_intersection`	list or tuple	Returns a new set containing the elements that exist in all of the given sets.	`sets...` (tuple or list)	`set_intersection(["A", "B", "C"], ["B", D"])`
`split`	tuple	Divides a given string by a given separator, returning a list of strings containing the characters between the separator sequences.	`sep` (string), `str` (string)	`split(" ", "foo bar qux")`
`substr`	string	Extracts a sequence of characters from another string and creates a new string. The “`offset`” index may be negative, in which case it is relative to the end of the given string. The “`length`” may be `-1`, in which case the remainder of the string after the given offset will be returned.	`str` (string), `offset` (integer), `length` (integer)	`substr("abcdef", 3, -1)`
`to_lower`	string	Converts a given string to lowercase.	`s` (string)	`to_lower(request.cookies.name)`
`to_number`	number	Converts its argument to a number value. Only numbers, `null`, and strings containing decimal representations of numbers can be converted to number. All other values will produce an error.	`num` (string or number)	`to_number("1,23")`, `to_number(env.PI)`
`to_upper`	string	Converts a given string to uppercase.	`s` (string)	`to_upper("CamelCase")`
`trim`	string	Removes any whitespace characters from the start and end of the given string.	`str` (string)	`trim(" foo ")`
`unixtime`	integer	Retrieves the current UNIX timestamp in seconds.		`unixtime()`
`url_decode`	string	URL-decodes a given string according to RFC 3986.	`s` (string)	`url_decode("abc%25%26%2C123")`
`url_encode`	string	URL-encodes a given string according to RFC 3986.	`s` (string)	`url_encode("abc%&,123")`

Merge of Configuration File(s)
Merging
Couper supports merging of blocks and attributes from multiple configuration files (see Basic Options of Command Line Interface).
General Rules of Merging
When merging, all attributes (except environment_variables in the defaults block) replace existing attributes with the same name, if any, otherwise they are added.
Blocks that cannot have labels (eg. cors, files etc.) replace existing blocks with the same name, if any, otherwise they are added.

Modifiers

Request Header

Couper offers three attributes to manipulate the request header fields. The header attributes can be defined unordered within the configuration file but will be executed ordered as follows:

Modifier	Contexts	Description
`remove_request_headers`	Endpoint Block, Proxy Block, Backend Block, Error Handler	List of request header to be removed from the upstream request.
`set_request_headers`	Endpoint Block, Proxy Block, Backend Block, Error Handler	Key/value(s) pairs to set request header in the upstream request.
`add_request_headers`	Endpoint Block, Proxy Block, Backend Block, Error Handler	Key/value(s) pairs to add request header to the upstream request.

All *_request_headers are executed from: endpoint, proxy, backend and error_handler.

Variables
Variables
The configuration file allows the use of some predefined variables. There are two phases when those variables get evaluated. The first phase is at config load which is currently related to env and simple function usage. The second evaluation will happen during the request/response handling.
- env are the environment variables.
- request is the client request.
- backend_requests contains all modified backend requests.
- backend_responses contains all original backend responses.
couper
Variable Type Description Example
version string Couper’s version number. "1.9.2"
environment string The environment Couper currently runs in. "prod"
env
Environment variables can be accessed everywhere within the configuration file since these references get evaluated at start.

Couper Documentation

Configuration

Configuration

Configuration Blocks

Access Control

Command Line Interface

Basic Options

Configuration File

IDE Extension

File Name

Errors

Introduction

Error messages

Expressions

Functions

Merging

General Rules of Merging

Modifiers

Request Header

Variables

`couper`

`env`

Variable	Type	Description	Example
`version`	string	Couper’s version number.	`"1.9.2"`
`environment`	string	The environment Couper currently runs in.	`"prod"`