Configuration

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 (CLI)

  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

  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

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

  • Merging
  • General Rules of Merging
  • Merging of server Blocks
  • Merging of definitions Blocks
  • Merging of defaults Blocks
  • Merging of settings Blocks

  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

  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.